Completed Route Architecture Note
Scenario
Atlas is launching /reports/revenue, a high-traffic revenue dashboard for managers. Users filter by date range, region, segment, and product line. The route has charts, a table, exports, saved views, role-based fields, analytics events, and mobile usage from field teams.
1. User contract
Users must be able to:
- load the dashboard on slow mobile networks
- understand whether data is loading, stale, empty, or failed
- share a filtered URL with another authorized user
- change filters without stale responses overwriting fresh results
- export data only when permitted
- recover from export failure without losing current filters
Non-goals:
- real-time collaborative editing
- sub-second freshness for all metrics
- offline export creation
2. Business and risk context
| Risk | Impact |
|---|---|
| Slow first load | managers abandon dashboard and ask analysts manually |
| stale data shown as fresh | bad operational decisions |
| unauthorized field exposure | customer/account privacy incident |
| broken export | support burden and lost trust |
| inaccessible filters | users cannot complete primary workflow |
3. Rendering decision
Decision: server-render the route shell and initial summary, stream lower-priority panels, hydrate filter controls, table interactions, and chart tooltips.
Rejected alternatives:
| Alternative | Rejected because |
|---|---|
| Full client-side rendering | delays first useful state and pushes too much data orchestration into the browser |
| Fully static route | report data and permissions are user-specific |
| Fully interactive client dashboard | increases JavaScript and hydration cost for non-interactive chrome |
Verification:
- LCP on mobile p75 below route budget
- INP for filter apply below interaction budget
- JavaScript shipped per route tracked in CI
- field metrics segmented by device class
4. Data and state ownership
| State/data | Owner/location | Notes |
|---|---|---|
| date range, region, segment, product line | URL | shareable and restorable |
| report result data | server/BFF cache | keyed by user permissions and filters |
| visible table sort | URL if shareable; component state if temporary | product decision per view |
| saved view name | server | auditable user setting |
| export job | server | side-effecting operation with idempotency key |
| chart hover state | component | transient interaction |
| density preference | preference store | cross-session but not product truth |
Freshness:
- summary cards: tolerate 5 minutes stale
- permissions: near-immediate, no browser-side authority
- export job status: poll or subscribe until terminal state
- AI-generated insight panel, if enabled later: must show source freshness
5. Mutation contract
Export action:
- server enforces authorization
- input schema accepts only report id, filters, format, and idempotency key
- duplicate idempotency key returns existing job
- pending state disables duplicate submit
- failure preserves filters and explains retry
- audit event records user, report id, filters hash, format, and outcome
6. Accessibility contract
- filters have visible labels and programmatic names
- keyboard users can reach and apply all filters
- result updates announce through polite live region
- loading does not steal focus
- export success/failure moves focus to an actionable status region
- charts have table or text alternative for key values
- target sizes and spacing support touch usage
7. Security and privacy contract
- no sensitive filters in analytics payloads
- role-restricted fields excluded on server before payload reaches browser
- export endpoint checks authorization server-side
- third-party analytics script loads after consent where required
- CSP/reporting configured for route shell
- errors redact query payload and account identifiers
8. Failure matrix
| Failure | User experience | Detection | Recovery |
|---|---|---|---|
| report API timeout | panel-level error; other panels remain usable | panel error metric and trace | retry panel |
| stale data | freshness timestamp visible | stale age metric | refresh action |
| filter race | latest request wins | request sequence test | abort/ignore stale responses |
| export fails | status shows failure and retry | export job failure metric | retry same idempotency key or create new job |
| analytics blocked | user workflow unaffected | event delivery metric | no user action |
| unauthorized export | clear permission error | authorization denial metric | request access or remove action |
9. Performance budget
| Budget | Target |
|---|---|
| p75 mobile LCP | below product threshold for dashboard routes |
| p75 filter INP | below interaction threshold |
| initial route JS | capped and tracked in CI |
| chart render cost | measured with trace on representative dataset |
| third-party script cost | registered and budgeted |
10. Observability
Events and metrics:
- route loaded with release, cohort, device class
- filter applied with non-sensitive filter categories
- report API latency by panel
- cache hit/miss by route and filter hash
- export started/completed/failed
- accessibility error reports from automated and manual testing
- Core Web Vitals by route
- client error boundary activation by panel
11. Rollout
- feature flag by tenant and role
- start with internal managers
- then 10% cohort for target customers
- kill switch for export only
- kill switch for chart enhancement only
- rollback route to previous dashboard link if critical path fails
12. Open risks
| Risk | Owner | Expiry |
|---|---|---|
| chart text alternative is manual for v1 | design system owner | before GA |
| export retry UX needs support review | reports team | two weeks after beta |
| analytics schema still missing saved view events | data platform | before experiment launch |
13. Decision summary
The route uses a hybrid rendering strategy because the shell and initial summary need fast first useful paint while filters, charts, and exports need client interactivity. Data ownership remains server/BFF-led, URL owns shareable filters, and side effects use server-enforced authorization and idempotency. The primary architectural risks are stale data, mobile performance, authorization leakage, and export reliability.
Source lens
This example combines Part 0 production readiness, Part III rendering/data architecture, Part VI performance budgets, Part VIII security/privacy, and Part XII review packet practices.