AI_template/docs/frontend/overview.md

Frontend: Overview

---

Last Updated: 2025-01-17
Phase: Phase 0 (Planning)
Status: Draft
Owner: Frontend Architect
References:

• /docs/project-overview.md (product goals)
• /docs/frontend/architecture.md (technical approach)
• /docs/content-structure.md (screens and flows)

---

1. Role of Frontend

• Deliver the primary user experience for your chosen archetype (chat, generation workflow, pipeline review, automation dashboard) plus onboarding/settings and optional billing.
• Keep flows fast, explainable (surface reasoning traces/scores when used), and safe (reflect provider states, avoid double actions).

2. Core Screens & Flows

• Core screens depend on the chosen archetype (see /docs/archetypes.md).
  Example for pipeline products:
  • Marketing/landing with CTA to signup.
  • Onboarding: signup/login, plan selection (provider Checkout/Portal if applicable), source connection (OAuth2/webhooks), team invites.
  • Items/records: lists/filters, detail drawer (raw fields, scores, LLM reasoning trace), bulk actions.
  • Human review (optional): approval/override UI, optional rules/policies editor.
  • Reports (optional): dashboards/summaries, exports.
  • Billing & Settings (optional): subscription status, payment method, tenant/team management, integrations health, audit/event log view.

3. Technical Principles

• Next.js (App Router) with TypeScript; Tailwind for styling; React Query/SWR for data fetching and cache orchestration.
• Feature-first structure; keep state local to features when possible.
• Prefer Server Components; mark client components explicitly; use route handlers/server actions where appropriate.
• Strong loading/error/empty states for data-heavy lists; avoid blocking UX during long jobs (categorization replays, exports).

4. Backend Interaction

• All data via backend APIs; frontend never calls external providers (data, payment, LLM) directly.
• Payments: initiate via backend (payment provider session/portal) and show statuses driven by webhooks.
• LLM: never called from the browser; surfaced reasoning traces come from backend responses.
• Auth: Clerk/Auth.js; guard routes per tenant/role; handle token refresh gracefully.

5. I18n

• Primary UI in English; other locales optional. Keep copy concise and domain-appropriate.