Cuan Portal
Financial command center. Currently a single 1,715-line file in the main repo. Future state: separate team, separate repo, dedicated audit infrastructure for fraud prevention through Separation of Duties.
Module tree (current state)
Dashboard, what's visible
The cuan dashboard surfaces all financial KPIs in one view:
Top-line metrics
- Today's GMV: Gross Merchandise Value for the current day
- MTD Revenue: Month-to-date platform revenue
- Active Sellers: Sellers with active listings or recent activity
- Orders Today: Order volume for the day
Platform revenue breakdown
| Stream | What it tracks |
|---|---|
| Commission | BPF + shipping markup + payment markup |
| Boost | Boost product purchases |
| Premium | Future premium feature revenue |
Operational queues
- Disbursement Queue: pending seller payouts awaiting maker-checker
- Fraud Alerts: flagged suspicious activity
- Recent Activity: real-time financial events
Reconciliation
- Net Revenue Reconciliation (MTD): Revenue minus expenses = net
Module groups
Dashboard
The default landing page. Read-only summary of financial health.
Revenue
Detailed revenue analytics, by stream, by period, by seller cohort.
Orders
Financial view of orders, every transaction's fee breakdown, escrow state, disbursement status.
Operations
Day-to-day finance work.
| Module | Purpose |
|---|---|
| Payouts | Manage seller disbursements with maker-checker workflow |
| Expenses | Track operational expenses by category |
| Boost and Premium | Boost product transactions and analytics |
Security
Fraud prevention and audit.
| Module | Purpose |
|---|---|
| Fraud and Integrity | Real-time fraud monitoring |
| Reports | Generate financial reports |
| Xero Sync | 🟡 Placeholder, only flips boolean, no real API call yet |
| Audit Log | Complete record of every financial change |
Admin
| Module | Purpose |
|---|---|
| Settings | Cuan-specific configuration |
AI Help Bot
🔵 Planned, not yet built. Future capability to query financial data conversationally.
Maker-checker workflow
Every disbursement ≥ IDR 500,000 requires two-person approval:
Rule: Maker and checker must be different finance admins. Same person cannot initiate and approve.
Audit trail
Every cuan action logged to fin_audit_log with:
- Actor user_id
- Action type
- Before/after JSONB snapshot
- Timestamp
- Optional reason
This enables full reconstruction of any financial change for dispute or audit.
Current limitations
1. Single-file architecture
The entire cuan portal is currently src/app/pages/cuan/FinancesDashboard.tsx, 1,715 lines. This works but doesn't scale. Refactor planned to proper route tree:
cuan/
├── routes.ts
├── pages/
│ ├── DashboardPage.tsx
│ ├── RevenuePage.tsx
│ ├── OrdersPage.tsx
│ ├── PayoutsPage.tsx
│ ├── ExpensesPage.tsx
│ ├── BoostPremiumPage.tsx
│ ├── FraudIntegrityPage.tsx
│ ├── ReportsPage.tsx
│ ├── XeroSyncPage.tsx
│ ├── AuditLogPage.tsx
│ └── SettingsPage.tsx
└── components/
├── DisbursementQueue.tsx
├── FraudAlertCard.tsx
└── NetRevenueWidget.tsx
2. Xero sync is placeholder
Currently xero_synced boolean is flipped to true but no actual Xero API call happens. Real implementation needed:
3. AI bot not yet built
Cuan AI bot is on the roadmap but not implemented. Future capabilities:
- "What was our MTD revenue from Boost?"
- "Show me disbursements pending approval over IDR 1M"
- "Reconcile this Xero discrepancy"
- "Audit trail for seller X"
Future separation plan
The cuan module currently shares the main pasarseken repo and database. Future state separates it for fraud prevention.
Why separate finance?
Separation of Duties (SoD)
A core fraud prevention principle: the people who build the platform shouldn't have unilateral control over financial flows.
Risks of bundled finance:
- Founder with code access could modify finance data
- Bug in main repo could corrupt financial records
- Single point of failure for audit trail
Benefits of separated finance:
- Independent codebase reduces blast radius
- Dedicated finance team without code access to product
- Independent audit trail
- Cleaner Xero pipeline
- Better suited for compliance audits
When to migrate?
Estimated post-launch month 6+, contingent on:
- Transaction volume justifying dedicated finance team
- Hiring finance lead
- Xero sync fully built and validated
- Migration plan reviewed with auditor
The deferred finances Postgres schema migration (2026-04-28 decision) is part of this trigger, not a separate concern, when cuan separates, the schema migration runs as part of the same transition.
Open questions
| Question | Owner |
|---|---|
| When to refactor cuan from single file to route tree? | Engineer |
| Hire dedicated finance lead, when and what profile? | Founder |
Resolved 2026-04-28: finances schema migration, deferred to cuan separation; finance tables stay in public with fin_ prefix pre-launch.
Where to look in the codebase
| What you want | Where it lives |
|---|---|
| Cuan frontend app shell | pasarseken-cuan/frontend/src/components/CuanApp.tsx |
| Finance domain entities | pasarseken-cuan/backend/server/domain/ |
| Finance repositories | pasarseken-cuan/backend/server/infrastructure/repositories/ |
| Route handlers | pasarseken-cuan/backend/server/interface/http/routes-*.ts |
| Comms monitor (CommsPage) | pasarseken-cuan/frontend/src/pages/CommsPage.tsx |
| Disputes UI | pasarseken-cuan/frontend/src/pages/DisputesPage.tsx |
| Outbox processor (cuan→main) | pasarseken-cuan/backend/server/infrastructure/outbox/FinOutboxProcessor.ts |
| Command client | pasarseken-cuan/backend/server/infrastructure/commands/FinCommandClient.ts |
| Main ops comms monitor | pasarseken/src/app/components/admin/CuanOutboxMonitor.tsx |
Cross-service communication
As of 2026-05-16, pasarseken-cuan has a fully deployed bidirectional communication layer with the SEKEN marketplace:
- Type 1 (events): Outbox pattern in both directions. Main → cuan delivers order lifecycle + boost events. Cuan → main delivers disbursement and fraud flag events.
- Type 2 (commands): Finance admin can resolve disputes from cuan's UI. Command executes synchronously in main's context.
- Type 3 (query proxy): Balance queries from sellers hit main's API but data is sourced live from cuan.
See Cuan Bidirectional Communication → for full route reference, sequence diagrams, secrets, failure modes, and monitoring surfaces.
Next: Integrations →