Cross-Cutting Concerns

These are platform-level concerns identified during the 2026-03-17 docs audit. They span all layers of the architecture and are not covered by any single chapter. Each topic will eventually need its own design — some before launch, some during implementation.

Note

This is not a backlog or a wish list. These are real engineering concerns that an engineer building from these docs will encounter. They are organized by urgency: pre-launch blockers first, then implementation-time concerns, then post-launch topics.

Pre-Launch (Design Needed Before Launch)

Security Model

Security considerations are scattered across chapters: session key risk in Chapter 3, off-ramp security in Chapter 5, webhook signature validation in Chapters 5 and 11, HTTP action auth in Chapter 9. There is no consolidated security model — no threat model, no trust boundary diagram, no systematic “what happens if X is compromised” analysis.

What’s needed: A unified security design covering trust boundaries (which components trust which), threat model (what can go wrong and how), key compromise scenarios (session key, Openfort API key, Convex admin, webhook secret), and the security properties the platform guarantees.

• Status: Design needed before launch

Rate Limiting and Abuse Prevention

Public webhook endpoints receive unauthenticated HTTP requests. Session key transactions are automated. Auto-routing triggers on claim events. There is no abuse detection, rate limiting, or circuit-breaking design.

What’s needed: Rate limiting strategy for webhook endpoints, abuse detection for session key transactions (e.g., unusual volume), circuit breakers for provider API calls, and monitoring for anomalous patterns.

• Status: Design needed before launch

Application-Level Authorization

Multiple organizations share the same Convex backend. The docs never discuss data isolation, access control at the Convex query/mutation level, or what prevents Org A from reading Org B’s data. Zodiac Roles handle on-chain permissions; there is no equivalent for the off-chain layer.

What’s needed: Authorization model for Convex queries and mutations — who can read/write what, how org boundaries are enforced, how admin roles work, and how the auth session maps to data access.

• Status: Design needed before launch

Implementation-Time (Document During Build)

Convex Schema Specifications

The docs reference approximately 12 Convex tables (financialDocuments, fiatTransactions, bridgeTransactions, verificationRecords, jurisdictionThresholds, rampProviders, cardProviders, verificationProviders, chainConfigs, safeRegistry, indexerCursors, treasuryBalances, and more). Each is described in prose. None has a formal schema definition — no TypeScript types, no Convex schema DSL.

What’s needed: Formal schema definitions (in Convex’s schema DSL) for all tables, generated from or validated against the prose descriptions. This is naturally produced during implementation but should be documented as the authoritative reference.

• Status: Document during implementation

Frontend Architecture

Zero documentation on the frontend. The providers.tsx code sample in Chapter 3 implies React with wagmi/tanstack-query, but this is not stated as a decision. No component architecture, routing, state management, or design system.

What’s needed: Frontend technology decision (framework, state management, component library), page/route structure, and how the frontend consumes Convex real-time subscriptions.

• Status: Design needed

API Design

The indexer calls Convex HTTP actions. The auth server exposes endpoints. Webhook endpoints receive provider callbacks. There is no API design section — no endpoint listing, no request/response schemas, no authentication model for HTTP actions beyond “shared secret.”

What’s needed: API surface documentation covering all HTTP endpoints (Convex HTTP actions, auth server, webhook receivers), authentication mechanisms, request/response schemas, and error response format.

• Status: Document during implementation

Testing Strategy

The POC in Chapter 13 validates 10 scenarios, but there is no testing strategy: no unit test philosophy, no integration test approach, no testnet deployment strategy, no staging environment plan.

What’s needed: Testing approach for each layer — unit tests for Convex functions, integration tests for provider facades (with sandbox environments), on-chain tests on Base testnet, and end-to-end test scenarios.

• Status: Design needed

Deployment and CI/CD

The indexer runs on Railway. Convex deploys via its own CLI. Better Auth runs on a separate server. There is no deployment architecture, CI/CD pipeline, or environment strategy.

What’s needed: Deployment topology (which services run where), CI/CD pipeline (build, test, deploy), environment strategy (dev/staging/prod), and how database migrations (Convex schema changes) are handled.

• Status: Design needed

Post-Launch (Address as Platform Matures)

Platform-Wide Monitoring and Observability

Only the indexer has a monitoring section (Chapter 9). There is no platform-wide observability strategy: no logging infrastructure, no distributed tracing across Convex + indexer + auth server + providers, no alerting for non-indexer components, no incident response playbook.

What’s needed: Observability stack decision, structured logging format, key metrics and alerts per component, and an on-call / incident response process.

• Status: Design needed

Data Backup and Disaster Recovery

Convex is the single source of truth for all application state. On-chain state is immutable, but all off-chain state (routing rules, financial documents, verification records, transaction history) lives in Convex.

What’s needed: Backup strategy for Convex data, recovery plan for data corruption or loss, and defined RPO/RTO targets. Convex may provide built-in backup features — this needs investigation.

• Status: Design needed

Notification System

Email, push, and in-app notifications are referenced throughout the docs (“the employee is notified,” “alerts are triggered”) but never designed. Chapter 10 mentions “Resend/Postmark” for report delivery. Chapter 3 mentions magic link emails.

What’s needed: Notification trigger definitions (what events produce notifications), delivery channels (email, push, in-app), template system, and delivery infrastructure.

• Status: Design needed

Internationalization and Localization

Capxul serves users across Africa and will expand to Middle East, Latin America, and Europe. The docs never mention language support, currency formatting, timezone handling, or localization strategy.

What’s needed: i18n framework decision, supported languages, currency/number formatting approach, and timezone handling (especially for financial documents and reporting periods).

• Status: Design needed

Audit Logging

For a financial platform, there is no system-level audit trail design. Chapter 8 covers financial document immutability and on-chain anchoring, but there is no audit trail for administrative actions — who changed a spending limit, who added a role, who approved a verification override.

What’s needed: Audit log schema, what actions are logged, retention policy, and how audit logs are queried/exported.

• Status: Design needed

Data Retention and Deletion

No retention policies for personal financial data across jurisdictions. Operating in Africa and expanding to Middle East, Latin America, and Europe means different data protection regimes.

What’s needed: Data retention policy per data type (financial documents, verification records, transaction history), deletion mechanisms, and compliance with relevant data protection regulations per jurisdiction.

• Status: Legal + design needed