Architecture
Route, contract, and projection structure used to keep UI behavior deterministic and auditable.
Key points
- App routes consume typed API responses sourced from projection helpers.
- Shared contracts reduce drift between route handlers and page-level assumptions.
- Dashboard payloads include confidence and recommended actions, not just raw scores.
- Error handling remains structured for debug traceability in demo conditions.
System view
Next.js PagesAPI Route HandlersProjection LayerContracts + Snapshot
API route matrix
| Method | Route | Primary consumer | Response contract |
|---|---|---|---|
| GET | /api/profile/[id] | Profile page | ProfileResponse |
| GET | /api/fundraisers/[id] | Fundraiser page | FundraiserResponse |
| GET | /api/communities/[id] | Community page | CommunityResponse |
| GET | /api/dashboard/overview | Dashboard KPI grid | DashboardOverviewResponse |
| GET | /api/dashboard/fraud | Fraud explainability cards | DashboardFraudResponse |
| GET | /api/dashboard/alerts/top | Alert queue | DashboardAlertsResponse |
Payload summary
| Surface | Payload highlights | Latency target | Failure envelope |
|---|---|---|---|
| Entity pages | Identity, momentum, integrity signals, and deep-link refs. | p75 <= 250ms | Typed ApiError with request_id. |
| Dashboard overview | Performance + engagement + philanthropy KPI cards. | p75 <= 250ms | Fallback cards + explicit empty states. |
| Fraud and alerts | Bucketed fraud cards, confidence, reasons, recommended_action. | p75 <= 250ms | Queue still renders with partial data. |
Risk and mitigation
- Risk: contract drift. Mitigation: centralized TypeScript interfaces in `contracts`.
- Risk: hidden coupling. Mitigation: explicit route-to-consumer mapping table.
- Risk: opaque failures. Mitigation: standardized error shape with `request_id` traceability.