# Payment Frontend Architecture

Torbat Pay (`frontend/modules/payment/`) mirrors the Experience/Delivery module layout.

## Layers

```
Browser → /api/payment BFF → payment-service:8012
```

- **BFF:** `frontend/app/api/payment/[...path]/route.ts` — forwards `Authorization`, `X-Tenant-ID`, `Idempotency-Key`
- **API client:** `services/payment-api.ts` — real endpoints only (MVP 14.0–14.5)
- **Checkout session:** `PaymentRequest` detail at `/payment/requests/[id]`

## Module structure

| Path | Role |
| --- | --- |
| `components/` | PaymentPortalShell, PaymentListPage, PaymentCharts, createPortalLayout |
| `constants/` | portals.ts (nav + MVP routes), permissions.ts |
| `features/` | Screen implementations (26 files) |
| `hooks/` | usePaymentCapabilities, usePaymentPermissions |
| `pages/shared.tsx` | Loaders, errors, CSV export |
| `types/` | API response types |

## Auth & tenant

- `AuthGuard` + `useMe` tenant gate (same as other portals)
- `X-Tenant-ID` on all authenticated API calls
- Bundle-gated nav via `filterNavByBundles(active_bundles)`

## Charts

Dashboard and KPIs use `PaymentCharts` (recharts): bar, donut, stat cards.

## Validation

```bash
npm run validate:payment
```

## Out of scope (14.6+)

Refunds, splits, subscriptions, wallet top-up UI — backend phases not yet implemented.