62 lines
2.7 KiB
Markdown
62 lines
2.7 KiB
Markdown
# 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.
|