AI_template/docs/frontend/FRONTEND_ARCHITECTURE_PLAN.md

Frontend Architecture Plan — AI Product Template

Status: Phase 0 (Planning) — recommendations to finalize in Phase 1
Scope: Next.js (App Router, TS) + Tailwind + React Query/SWR for ingestion → categorization → approvals → reporting → billing
Sources: Next.js App Router best practices (per latest docs), product/domain docs in /docs

0. Goals & Non-Goals

• Ship a clear, predictable frontend for users in your target domain: fast tables, reliable status, explainability (rule hit, embedding score, LLM reasoning trace).
• Optimize for multi-tenant, webhook-driven states, and payment‑provider‑hosted billing; no direct provider/LLM calls from the browser.
• Non-goal: custom card forms or direct provider SDKs in the browser.

1. Routing & Layout

• App Router with app/; root layout.tsx imports globals (per Next.js docs).
• Layout shells: public (marketing), app shell (auth/tenant-protected), auth screens.
• Minimal routes: /, /records, /records/review, /rules, /reports, /settings/billing, /settings/integrations, /settings/team.
• Navigation state from next/navigation; avoid dynamic href objects in <Link> (App Router requirement).

2. Feature/Folder Structure

src/
  app/                   # routes/layouts
  features/              # onboarding, records, approvals, rules, reports, billing, settings
  entities/              # tenant, user, record, rule, report, event, integration
  shared/                # ui kit, hooks, api client, lib (formatting, domain utils), auth client
  widgets/               # composed UI blocks (dashboards, charts, tables)

• Co-locate queries/mutations/types/tests per feature; keep shared minimal.

3. Data Layer & State

• HTTP client with typed fetchers; attach auth/tenant context; central 401/403 handling.
• React Query/SWR for cache + background refresh; server-side data where possible (RSC) with client wrappers for interactivity.
• Pagination/virtualization for large lists (/records, /events); filters persisted in URL search params.
• Optimistic updates only for low-risk actions (naming/rule toggles); approvals/overrides stay pessimistic with clear status.

4. Auth, Tenant, Roles

• Clerk/Auth.js client; protect routes via middleware and layout guards.
• Tenant selector (if multiple) with context propagated to fetchers.
• Role-based UI gating (owner/admin/viewer); hide/disable disallowed actions.

5. UX for Key Flows

• Records: table with status chips (ingested/categorized/needs_approval/approved/error), drawer: raw payload, rule hit, embedding score, reasoning_trace, attachments, history.
• Approvals: queue view, approve/override with confirmation; optional rule creation inline; show impact preview.
• Rules: list (priority, hit rate), editor with condition/action JSON preview, test on sample set.
• Reports: date range and domain indicators (e.g., timezone/currency if relevant); async export with status chips and download links.
• Billing: payment‑provider‑hosted Checkout/Portal; post-return state from backend; recovery CTAs.
• Integrations: external provider connection status, webhook health, rotate secrets; surface retry guidance.
• Errors/Support: human-readable errors with traceId; recovery steps for webhook/LLM failures.

6. Styling & UI Kit

• Tailwind for utilities; small UI kit in shared/ui (buttons, inputs, selects, tables, drawer, modal, badge, toast, skeleton).
• Use accessible patterns: focus states, keyboard nav, ARIA labels for tables/dialogs.

7. Forms & Validation

• React Hook Form + Zod (or similar).
• Common patterns: debounced search, controlled filters, guarded destructive actions.
• Show server errors inline; avoid duplicate submits; loading/disabled states on primary actions.

8. Data Fetching Patterns (per Next.js App Router)

• Server Components for initial data where possible; client components for interactive tables/forms.
• Route Handlers/Server Actions for simple backend-for-frontend glue (if used).
• Avoid dynamic Link objects; use string hrefs for dynamic routes.

9. Observability & Telemetry

• Log traceId from responses in UI for support; send non-PII analytics for funnel: onboarding, connection success/failure, categorize actions, approvals, billing, exports.
• Respect consent; no PII in client analytics events.

10. Performance

• Table virtualization for large datasets; incremental rendering with skeletons/placeholders.
• Code splitting by route/feature; lazy-load heavy widgets (charts, diff/trace viewers).
• Image optimization via Next.js Image if/when used; minimize client JS in shells.

11. Testing

• Unit: helpers/formatters.
• Component: records table/drawer, approvals flow, rule editor, billing/status banners.
• E2E: onboarding + source connect, record ingest display, categorize → approve, rule create/apply, billing flow, report export.

12. Open Questions / To Finalize

• Exact table virtualization lib (if any) and charting choice.
• How much data is loaded server-side vs client-side for /records (depends on API paging).
• Error surface for LLM fallback (what to show vs hide).
• i18n scope (English only vs multi-lingual).
• Whether to expose rawSnippet of LLM response in UI or keep to audit logs only.