Frontend: Overview

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

1. Role of Frontend

Deliver onboarding, data connection, categorization review, approval, reporting, and billing experiences for SMB finance users.
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 (Stripe Checkout/portal), source connection (QuickBooks OAuth2, bank webhooks health), team invites.
Transactions: 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: P&L/summary dashboards, exports with statuses.
Billing & Settings: subscription status, payment method, tenant/team management, integrations health, audit/event log view.
Routes (min set): /, /transactions, /transactions/review, /rules, /reports, /settings/billing, /settings/accounts.

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 providers (Stripe/QuickBooks/banks/LLM) directly.
Payments: initiate via backend (Stripe 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 finance-friendly.