Frontend: Architecture (Recommendations)

Last Updated: 2025-01-17
Phase: Phase 0 (Planning)
Status: Draft — finalize in Phase 1
Owner: Frontend Architect
References:

/docs/project-overview.md
/docs/content-structure.md
/docs/backend/api-design.md
/docs/backend/payment-flow.md
/docs/frontend/ui-ux-guidelines.md

Recommendations for Phase 0. Lock decisions in Phase 1.
After Phase 1, this file is the canonical record of locked frontend architecture decisions.
Use FRONTEND_ARCHITECTURE_PLAN.md for working notes and archive/delete it after Phase 1.
Modules like records/rules/approvals/billing are examples for one archetype. Rename or omit per /docs/archetypes.md.

1. Stack

Framework: Next.js (App Router) + TypeScript.
Styling: Tailwind CSS.
Data: React Query or SWR; keep fetchers typed.
Forms: React Hook Form (or similar) + Zod (or similar) for validation.

2. Structure (feature-first)

src/
  app/            # routes/layouts
  features/       # flows: onboarding, records, approvals, reports, billing
  entities/       # domain: tenant, user, record, rule, report, event
  shared/         # ui kit, hooks, api client, utils
  widgets/        # composed UI blocks
  i18n/           # translations (if added)

Principles: co-locate tests/types; avoid cross-feature coupling; keep shared minimal.

3. Data & API

Single typed HTTP client; attach auth tokens; handle 401/403 centrally.
Cache with React Query/SWR; use optimistic/paused states carefully for approvals and rule edits.
Prefer RSC for data loading; mark interactive leaf nodes with "use client".
Pagination/filtering for record-heavy views; background refetch for webhook-driven updates.

4. Payments & Billing UI

Backend initiates payment-provider sessions/portal links; frontend renders statuses only.
After return from payment provider, fetch status from backend (webhook-driven source of truth); show success/fail/pending and recovery options.
Never collect raw card data; no custom card forms.

5. LLM & Explainability Surfacing

Frontend never calls LLMs directly. Display reasoning_trace, matched rule, and embedding score from backend payloads.
Provide expandable details, copyable traces, and clear labels for confidence/status.

6. Authentication & Access

Use Clerk/Auth.js client libraries; guard routes per tenant/role; soft-redirect unauthenticated users.
Support tenant context switching if user belongs to multiple tenants.

7. Testing

Unit: utility/helpers.
Component: critical UI (records list, approval drawer, rule editor, billing modal).
E2E: onboarding, ingestion health check, categorize + approve, billing change, report export.

2.7 KiB Raw Blame History