# 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.

## 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, transactions, approvals, reports, billing
  entities/       # domain: tenant, user, transaction, 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 transaction-heavy views; background refetch for webhook-driven updates.

## 4. Payments & Billing UI
- Backend initiates Stripe sessions/portal links; frontend renders statuses only.
- After return from Stripe, 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 (transactions list, approval drawer, rule editor, billing modal).
- E2E: onboarding, ingestion health check, categorize + approve, billing change, report export.