create AI_template

docs/frontend/architecture.md

@@ -0,0 +1,58 @@
+# 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.