Frontend: Overview

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

1. Role of Frontend

Deliver onboarding, data connection, categorization review, approval, reporting, and optional billing experiences for users in your target domain.
Keep flows fast, explainable (surface reasoning trace, rule hit), and safe (reflect webhook/provider states, avoid double actions).

Marketing/landing with CTA to signup.
Onboarding: signup/login, plan selection (payment provider Checkout/Portal if applicable), source connection (external providers via OAuth2/webhooks), team invites.
Records: lists/filters, detail drawer (raw fields, rule hit, embedding score, LLM reasoning trace), bulk actions.
Approvals & Rules: approval queue, override + optional rule creation, rule list/editor, history snippets.
Reports: dashboards/summaries, exports with statuses.
Billing & Settings: subscription status, payment method, tenant/team management, integrations health, audit/event log view.
Routes (min set): /, /records, /records/review, /rules, /reports, /settings/billing, /settings/integrations.

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

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.

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