# Navi Money Operations Architecture Audit

Date: 2026-05-06  
Branch: `wave1/payment-refund-commission-reporting`

## Current Readiness

| Flow | Current state | Readiness | Priority |
| --- | --- | ---: | --- |
| Booking lifecycle | `Booking` exists with compact statuses: `PENDING_PAYMENT`, `CONFIRMED`, `COMPLETED`, `CANCELLED`, `REFUNDED`. | 5/10 | P0 before launch |
| Order lifecycle | `Order` exists, but `OrderItem` is missing and service-specific fulfillment is thin. | 3/10 | P0 |
| Payment lifecycle | `PaymentIntent` exists with idempotency key and provider abstraction. Live webhook completion is not production-ready. | 4/10 | P0 |
| Refund lifecycle | Refund request and approve foundation exists. Full state machine/reject/process/complete flow is missing. | 4/10 | P0 |
| Commission lifecycle | Provider integrations have `commissionEnabled`; no commission rate, ledger, or settlement model exists. | 2/10 | P1 |
| Payout lifecycle | `Payout` exists with business, period, amount, status. Status enum/state machine is missing. | 4/10 | P1 |
| Review lifecycle | No full review/rating operational workflow found in this slice. | 2/10 | P2 |
| Customer lookup | User/profile/read-side exists; customer 360 timeline is not complete. | 4/10 | P1 |
| Dashboard reports | Analytics endpoints exist; this branch adds finance report foundation. | 6/10 | P1 |
| Audit logs | Payment/refund decorators exist; status-change coverage still needs hardening. | 5/10 | P0 |
| Data exports | Not implemented; should be audited when added. | 2/10 | P2 |
| Demo data risk | Current provider/payment readiness must remain clearly labeled and non-production. | 7/10 after provider control polish | P0 |

## Missing Models

- `OrderItem` for food, grocery, pharmacy, SIM, and service line integrity.
- `CommissionRule` or equivalent provider/category commission-rate model.
- `CommissionLedgerEntry` for immutable earned commission records.
- `PaymentTransaction` or webhook event linkage for provider-settled events.
- Expanded `Refund` timestamps and transition metadata such as rejected/processed/completed fields.
- Payout status enum and settlement transaction references.
- Customer support timeline notes tied to payments/bookings/orders.

## Missing APIs

- Booking quote/status/cancel/refund state transitions.
- Order create with line items and provider/driver status transitions.
- Payment webhook completion with signed provider verification.
- Refund reject/process/complete/failed endpoints.
- Commission report endpoint backed by a real ledger.
- Payout generation and payout transition endpoints.
- Customer 360 endpoint combining profile, bookings, orders, refunds, support, and engagement.
- Export endpoints for finance reports with audit logs.

## Missing Dashboard Screens

- Finance report detail and export workflow.
- Refund approval/rejection/processing queue.
- Payout generation and settlement review.
- Commission rules and commission ledger.
- Customer 360 lookup.
- Payment webhook/event timeline.

## This Branch Adds

- `GET /v1/admin/analytics/finance-report`
- Dashboard Reports page integration for payment/refund/payout totals and risk queue.
- Commission-readiness reporting that is explicit about the missing rate/ledger model.
- Shared DTO/API-client support for the finance report.

## Risks

1. Do not represent commission revenue as real until a ledger model exists.
2. Do not mark payment completion production-ready until Stripe/Telr webhook processing is complete.
3. Do not process refunds against provider APIs until signed webhook and refund state machine are implemented.
4. Payout records are read-only in this branch and should not be used as financial settlement proof.

## Exact Implementation Order

1. Normalize booking lifecycle state machine.
2. Add `OrderItem` and service order lifecycle.
3. Complete payment provider/webhook state transitions.
4. Complete refund state machine.
5. Add commission rules and immutable commission ledger.
6. Add payout generation/state machine.
7. Add customer 360 dashboard.
8. Add audited finance exports.