# 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. The concrete flows (chat, generation, pipeline, approvals, billing) depend on the chosen archetype in `/docs/archetypes.md`.  
> **Sources:** Next.js App Router best practices (per latest docs), product/domain docs in `/docs`

> **Purpose:** This file is a scratchpad for exploring options and trade‑offs.  
> Move finalized decisions into `/docs/frontend/architecture.md`.  
> **Archive or delete this plan after Phase 1** to avoid duplication.

## 0. Goals & Non-Goals
- Ship a clear, predictable frontend for your chosen archetype: fast core interactions (chat/workflow/pipeline/automation), reliable status, explainability when applicable (scores, traces, source).
- Optimize for long‑running or webhook‑driven states if your product uses them; 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 depend on archetype. Example for pipeline products: `/`, `/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/              # archetype flows (e.g., onboarding, chat, items, approvals, reports, billing, settings)
  entities/              # domain entities (tenant/user optional; items/messages/drafts/tasks, etc.)
  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.