create AI_template

docs/backend/api-design.md

@@ -0,0 +1,57 @@
+# Backend: API Design
+
+---
+**Last Updated:** 2025-01-17  
+**Phase:** Phase 0 (Planning)  
+**Status:** Draft — finalize in Phase 1  
+**Owner:** Backend Architect  
+**References:**
+- `/docs/backend/architecture.md`
+- `/docs/backend/payment-flow.md`
+- `/docs/backend/security.md`
+---
+
+## 1. Principles
+- REST with versioning (`/api/v1`), consistent envelope and errors.
+- Tenant-scoped resources; role-based authorization.
+- Idempotent ingestion/webhook endpoints; trace IDs for debugging.
+
+## 2. Core Resources (high-level)
+- `/auth` — login, tenant context, token refresh.
+- `/tenants` — tenant profile, roles, invites.
+- `/integrations` — connect sources (OAuth2/webhooks), view health, rotate secrets, webhook endpoints.
+- `/records` — list/filter, detail (raw + normalized + reasoning), bulk actions, reprocess.
+- `/rules` — CRUD, enable/disable, test/preview, stats.
+- `/processing` — trigger re-evaluation (rules → embeddings → LLM), inspect outcomes.
+- `/approvals` — approval queue, approve/override, optional rule creation.
+- `/reports` — dashboards/summary generation, export status/download.
+- `/billing` — session/portal links, subscription status (webhook-driven).
+- `/events` — read-only event log feed for downstream agents.
+- `/files/attachments` — uploads/metadata (if exposed).
+
+## 3. Payments/Billing (Provider-agnostic)
+- `POST /billing/session` — create checkout session for subscription/plan change.
+- `GET /billing/status` — current subscription status (webhook-driven source of truth).
+- `GET /billing/portal` — customer portal link for payment method/plan management.
+- `POST /billing/webhooks/provider` — verify signature; idempotent subscription updates; log billing events.
+
+## 4. Ingestion/Webhooks
+- Receivers for external providers (e.g., `/integrations/webhooks/{provider}`): verify signature, dedupe, enqueue to BullMQ; emit `INGESTED` with `source_agent`.
+
+## 5. Processing & Approvals
+- `POST /processing/run` — trigger re-evaluation for a scoped set (source/date/status).
+- `POST /approvals/{id}/approve` — accept decision; log `APPROVED`.
+- `POST /approvals/{id}/override` — override outcome; optional rule payload; log `APPROVED` and `RULE_CREATED` when applicable.
+
+## 6. Events
+- `GET /events` — read-only feed (paginated) for downstream agents/clients; filters: tenant, type, time range, source_agent.
+
+## 7. Response Envelope (example)
+```json
+{
+  "data": { ... },
+  "error": null,
+  "meta": { "traceId": "..." }
+}
+```
+Errors: `data = null`, `error` with code/message/context.

docs/backend/architecture.md

@@ -0,0 +1,63 @@
+# Backend: Architecture (Recommendations)
+
+---
+**Last Updated:** 2025-01-17  
+**Phase:** Phase 0 (Planning)  
+**Status:** Draft — finalize in Phase 1  
+**Owner:** Backend Architect  
+**References:**
+- `/docs/project-overview.md`
+- `/docs/backend/api-design.md`
+- `/docs/backend/security.md`
+- `/docs/backend/payment-flow.md`
+---
+
+> Recommendations for Phase 0. Lock decisions in Phase 1.
+
+## 1. Approach & Stack
+- Style: modular monolith with clear modules; containerized.
+- Language/Runtime: Node.js (LTS) + TypeScript.
+- Framework: Express or Fastify with modular structure and DI where helpful.
+- DB: Postgres (managed: Supabase/RDS). Vector: `pgvector` for embeddings.
+- Queue: BullMQ (Redis) for ingestion, categorization, notifications.
+- Auth: Clerk/Auth.js (or equivalent) with tenant-aware RBAC.
+- Payments: provider-hosted subscriptions; no raw card data stored.
+- LLM: OpenAI API (or equivalent) via single helper (e.g., `callLLM()`), configurable model/params.
+
+## 2. Modules (logical)
+- `auth` — tenants, users, roles, sessions.
+- `integrations` — external connectors, OAuth2, webhooks, connection health.
+- `records` — normalized record store, statuses, `reasoning_trace` JSONB.
+- `rules` — rule definitions, evaluation order, testing, hit stats.
+- `processing` — pipeline: rule engine → embeddings similarity → LLM fallback; writes `PROCESSED`, updates records.
+- `approvals` — queues for human review, overrides, optional rule creation; logs `TX_APPROVED`/`RULE_CREATED` with `source_agent`.
+- `reports` — dashboards/exports, history.
+- `billing` — provider checkout/portal, webhooks, plan enforcement per tenant.
+- `events` — audit/event log (`EventLog`), read-only `/api/events` for downstream agents.
+- `files/receipts` — attachment storage metadata (`Receipt` with file URL/mime).
+
+## 3. API Layers
+- HTTP API (REST) with versioning (`/api/v1`).
+- Service layer for business logic and transactions.
+- Repositories for data access; use migrations for schema evolution.
+
+## 4. Infrastructure & Ops
+- Environments: dev/stage/prod; Docker images; CI/CD.
+- Observability: structured logging, metrics, tracing; dead-letter queues for failed jobs.
+- Secrets management per environment; rotate webhook/LLM/payment provider secrets.
+
+## 5. Data & Schema Notes
+- Records: store raw payload + normalized fields + `reasoning_trace` JSONB (model, rationale, confidence, source).
+- EventLog: include `source_agent` (default `balance`) and payload for auditability; ensure filters by tenant/time/type.
+- Embeddings: table keyed by transaction/merchant strings to support similarity search; index with `pgvector`.
+- Multi-tenant: all core tables carry `tenantId` and enforce scoped queries; `User` role per tenant.
+
+## 6. Payment & Messaging (High-Level)
+- Payment provider: initiate sessions via backend; handle webhooks idempotently; map provider status to internal billing/subscription states; update tenant access.
+- Notifications: optional email/webhook callbacks to surface ingestion/categorization failures; keep out of PII exposure.
+
+## 7. Queues (BullMQ)
+- `records:ingest` — normalize webhook payloads, write `Record`, emit `INGESTED`.
+- `records:process` — rule engine → embeddings similarity → LLM fallback; emit `PROCESSED` with `reasoning_trace`.
+- `reports:generate` — build P&L/exports, emit `REPORT_GENERATED`.
+- Dead-letter queues per stream; retries with backoff; idempotent handlers keyed by external event IDs.

docs/backend/overview.md

@@ -0,0 +1,33 @@
+# Backend: Overview
+
+---
+**Last Updated:** 2025-01-17  
+**Phase:** Phase 0 (Planning)  
+**Status:** Approved  
+**Owner:** Backend Architect  
+**References:**
+- `/docs/project-overview.md`
+- `/docs/backend/architecture.md`
+- `/docs/backend/payment-flow.md`
+---
+
+## 1. Role of Backend
+- Own business logic for ingestion, processing/classification (rules + embeddings + LLM fallback), approvals, reporting, billing, and audit.
+- Integrate safely with external providers (OAuth2/webhooks, payment provider, LLM provider) and expose consistent APIs + events.
+- Enforce security: tenant isolation, RBAC, webhook verification, event/audit logging.
+
+## 2. Main Domain Areas
+- **Auth & Tenants:** authentication/authorization, roles, tenant-scoped access.
+- **Integrations:** external providers via OAuth2/webhooks; connection health.
+- **Records:** normalized feeds, statuses (ingested, processed, needs_approval, approved, failed), `reasoning_trace` JSONB.
+- **Rules & Processing:** rules engine, embeddings similarity, LLM fallback; logging with `source_agent`.
+- **Approvals:** human-in-the-loop decisions, overrides, optional rule creation; audit trail.
+- **Reports & Exports:** dashboards/summaries with export history.
+- **Billing:** provider-hosted subscriptions, tenant-scoped access control, webhooks.
+- **Events:** `/api/events` feed for downstream agents and internal observability.
+
+## 3. Integrations
+- **External data providers:** OAuth2 + webhooks; signatures/verification; idempotent writes via workers.
+- **Payment provider:** subscriptions, checkout/portal; webhooks for lifecycle events.
+- **LLM provider:** OpenAI API via single helper; configurable model.
+- **Queues:** BullMQ (Redis) for ingestion/categorization/notifications.

docs/backend/payment-flow.md

@@ -0,0 +1,45 @@
+# Payment & Billing Flow (Provider‑agnostic)
+
+---
+**Last Updated:** 2025-01-17  
+**Phase:** Phase 0 (Planning)  
+**Status:** Draft — finalize in Phase 1  
+**Owner:** Backend Architect  
+**References:**
+- `/docs/project-overview.md`
+- `/docs/backend/architecture.md`
+- `/docs/backend/api-design.md`
+- `/docs/backend/security.md`
+---
+
+Single source of truth for subscription billing with an external payment provider. No raw card data is handled by our app.
+
+## 1) High-Level Flow
+1. Frontend calls backend to create a Checkout/Portal Session (`POST /billing/session`) with tenant/context.
+2. Backend creates/updates the Customer (if needed) and Session at the payment provider; returns `sessionUrl`.
+3. User completes checkout on provider‑hosted page.
+4. Payment provider sends webhooks (e.g., subscription created/updated/canceled).
+5. Backend verifies signatures, updates subscription state in DB, and logs events (`BILLING_UPDATED`).
+6. Frontend reads subscription status from backend (`/billing/status`) — webhook‑driven source of truth.
+
+## 2) Required Endpoints
+- `POST /billing/session` — init checkout/plan change. Request: tenant ID inferred from auth; plan/tier; success/cancel URLs. Response: `sessionUrl`.
+- `GET /billing/status` — return subscription status, current plan, renewal/cancel info (cached from webhook‑driven DB state).
+- `POST /billing/webhooks/provider` — verify signature; idempotent upsert of subscription state; update tenant access.
+
+## 3) Data Model Notes
+- Store provider customer ID, subscription ID, price/plan, status, current period dates, cancel_at/canceled_at, seats (if applicable).
+- All writes must be idempotent (webhook retries). Use provider event IDs for dedupe.
+- Permissions are enforced per tenant based on subscription status.
+
+## 4) States & Mapping (common)
+- `trialing`, `active`, `past_due`, `canceled`, `incomplete/incomplete_expired`, `unpaid` → map to internal states that drive access. Deny critical actions when subscription is inactive.
+
+## 5) Security & Compliance
+- Verify webhook signatures with provider secret; reject if invalid; log failures with trace IDs.
+- Do not log sensitive payloads; store only necessary billing identifiers.
+- Expose no card data; rely on provider‑hosted UIs (Checkout/Portal) for payment method management.
+
+## 6) Frontend UX Notes
+- Use provider trust cues and clear statuses after redirect: success/pending/fail with recovery (retry checkout, contact support).
+- All status displays must read from backend (webhook‑driven), not query params.

docs/backend/security.md

@@ -0,0 +1,51 @@
+# Backend: Security (Template)
+
+---
+**Last Updated:** 2025-01-17  
+**Phase:** Phase 0 (Planning)  
+**Status:** Draft — finalize in Phase 1  
+**Owner:** Backend Architect, Security  
+**References:**
+- `/docs/backend/architecture.md`
+- `/docs/backend/payment-flow.md`
+- `/docs/backend/api-design.md`
+---
+
+## 1. Goals
+- Protect sensitive data and ensure tenant isolation.
+- Secure integrations (webhooks/OAuth) and billing.
+- Maintain auditability for all automated and manual actions.
+
+## 2. Authentication & Authorization
+- Use managed auth (Clerk/Auth.js or equivalent) with secure sessions/tokens.
+- Enforce tenant-scoped RBAC; validate tenant context on every request.
+- Rate limit auth endpoints; protect refresh flows.
+
+## 3. Data Protection
+- TLS everywhere; secure headers.
+- Least-privilege DB roles; encrypt secrets at rest; rotate keys.
+- Avoid logging sensitive payloads (bank data, webhook bodies, LLM prompts/responses beyond trace references).
+- Store `reasoning_trace` JSONB with care; avoid PII in traces.
+
+## 4. Integrations & Webhooks
+- Verify signatures for all inbound webhooks (external providers, payment provider); reject invalid; log with trace IDs.
+- Idempotent processing with event ID dedupe; dead-letter queue for failures.
+- Expose webhook URLs only over HTTPS; regenerate secrets on rotation.
+
+## 5. Payments (provider‑agnostic)
+- Use provider‑hosted Checkout/Portal; never handle raw card data.
+- Store minimal billing identifiers (customer/subscription IDs, status, timestamps, plan/price).
+- Enforce access based on subscription state; deny actions when inactive.
+
+## 6. LLM Safety
+- All LLM calls go through a single helper; centralize redaction, logging, and parameter control.
+- Strip/obfuscate sensitive fields before sending to LLM; log only references in traces.
+
+## 7. Audit & Events
+- Log domain events to `EventLog` with `source_agent`; include user ID, tenant, timestamps, and relevant context.
+- Provide read-only `/api/events` with pagination and filtering; protect by tenant/role.
+
+## 8. Common Controls
+- OWASP Top 10 coverage (SQLi, XSS, CSRF, IDOR, SSRF, etc.).
+- Input validation on all external inputs; use allowlists for redirects/URLs.
+- Backup/restore plan and monitoring/alerting for infra and queues.

docs/content-structure.md

@@ -0,0 +1,63 @@
+# App & Content Structure (Template)
+
+---
+**Last Updated:** 2025-01-17  
+**Phase:** Phase 0 (Planning)  
+**Status:** Draft  
+**Owner:** Product, UX/UI  
+**References:**
+- `/docs/project-overview.md` (product vision)
+- `/docs/frontend/ui-ux-guidelines.md` (UX patterns)
+- `/docs/backend/api-design.md` (API resources)
+---
+
+Structure of key screens/flows for a generic AI‑assisted product. Use this as a template and adapt to your domain.
+
+## General Principles
+- Web-first (desktop + mobile web); clear, concise copy for target users in your domain.
+- Emphasize trust: audit trail, optional reasoning traces, secure webhooks, role-based access, provider-hosted billing.
+- Keep flows short; surface provider states (webhook-driven) and recovery steps.
+
+## 1. Marketing / Landing (lightweight)
+- Hero: what the product does (ingestion, processing/classification, approvals, reporting), security/billing note, CTA to start.
+- How it works: 3–4 steps (connect, ingest, process, approve/report).
+- Integrations: external providers (OAuth2/webhooks), LLM helper.
+- Pricing: plans via provider-hosted billing (if applicable), trial info.
+- FAQ and compliance/audit cues.
+- CTA: “Start” → signup flow.
+
+## 2. Onboarding & Tenant Setup
+- Create account/tenant; select plan (provider-hosted checkout/portal); invite teammates.
+- Connect data sources: OAuth2 to external providers, webhook URL display.
+- Confirm webhooks/health; show status and retry guidance.
+
+## 3. Records & Processing
+- Records list with filters (date, source, status: ingested, processed, needs_approval, approved, failed).
+- Detail drawer: raw fields, matched rule/embedding score, LLM `reasoning_trace`, history, related attachments.
+- Bulk actions: reprocess, send to approval, archive (if allowed).
+
+## 4. Approvals & Rules
+- Approval queue: items requiring human review; assign/reassign; batch approve.
+- Override outcome with optional rule creation (scope, conditions, action); preview impact/safety notes.
+- Event log snippet (who/what/when, `source_agent`).
+
+## 5. Rules Management
+- Rules list (name, priority, hit rate, last updated, enabled/disabled).
+- Rule editor: conditions (source fields, ranges, text, embedding similarity tag), actions (labels/categories/tags), evaluation order.
+- Test/preview on a sample set before saving.
+
+## 6. Reports & Exports
+- Dashboards and summaries; time range + tenant/source filters.
+- Export (CSV/PDF) with clear timezone/currency notes where relevant.
+- Status and history of generated reports; link to underlying events.
+
+## 7. Billing & Settings
+- Subscription status (provider), plan details, payment method update via portal.
+- Tenant/team management: roles, invites, revocations.
+- Integrations: connection health, webhook secrets, rotate keys.
+- Audit log (`EventLog`) with `source_agent` and filters.
+
+## 8. Support & Logs
+- Surface recent events (`/api/events` feed) for downstream agents and debugging.
+- Troubleshooting tips (webhook mismatch, ingestion failures, LLM fallback errors), retry buttons where safe.
+- Links/contact for support.

docs/frontend/FRONTEND_ARCHITECTURE_PLAN.md

@@ -0,0 +1,82 @@
+# Frontend Architecture Plan — Accounting AI Agent
+
+> **Status:** Phase 0 (Planning) — recommendations to finalize in Phase 1  
+> **Scope:** Next.js (App Router, TS) + Tailwind + React Query/SWR for ingestion → categorization → approvals → reporting → billing  
+> **Sources:** Next.js App Router best practices (per latest docs), product/domain docs in `/docs`
+
+## 0. Goals & Non-Goals
+- Ship a clear, predictable frontend for finance users: fast tables, reliable status, explainability (rule hit, embedding score, LLM reasoning trace).
+- Optimize for multi-tenant, webhook-driven states, and Stripe-hosted billing; 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: `/`, `/transactions`, `/transactions/review`, `/rules`, `/reports`, `/settings/billing`, `/settings/accounts`, `/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/              # onboarding, transactions, approvals, rules, reports, billing, settings
+  entities/              # tenant, user, transaction, rule, report, event, integration
+  shared/                # ui kit, hooks, api client, lib (formatting, currency), 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 (`/transactions`, `/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
+- **Transactions:** table with status chips (ingested/categorized/needs_approval/approved/error), drawer: raw payload, rule hit, embedding score, `reasoning_trace`, receipts, 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, currency/timezone indicators; async export with status chips and download links.  
+- **Billing:** Stripe-hosted Checkout/Portal; post-return state from backend; recovery CTAs.  
+- **Integrations:** QuickBooks/bank 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: transactions table/drawer, approvals flow, rule editor, billing/status banners.  
+- E2E: onboarding + source connect, transaction 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 `/transactions` (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.

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.

docs/frontend/overview.md

@@ -0,0 +1,40 @@
+# Frontend: Overview
+
+---
+**Last Updated:** 2025-01-17  
+**Phase:** Phase 0 (Planning)  
+**Status:** Approved  
+**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 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).
+
+## 2. Core Screens & Flows
+- 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`.
+
+## 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 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.
+
+## 5. I18n
+- Primary UI in English; other locales optional. Keep copy concise and finance-friendly.

docs/frontend/seo-performance.md

@@ -0,0 +1,38 @@
+# Frontend: SEO & Performance
+
+---
+**Last Updated:** 2025-01-17  
+**Phase:** Phase 0 (Planning)  
+**Status:** Draft  
+**Owner:** Frontend Architect, SEO  
+**References:**
+- `/docs/content-structure.md`
+- `/docs/frontend/architecture.md`
+- `/docs/project-overview.md`
+---
+
+## 1. Goals
+- Ensure good indexation for marketing/landing pages; keep the app fast for data-heavy views.
+- Hit Core Web Vitals targets where applicable; design for fast perceived performance in app flows.
+
+## 2. SEO (marketing pages)
+- Use SSR/SSG for landing/pricing/FAQ pages.
+- Semantic markup; clean URLs; Open Graph/Twitter cards.
+- sitemap/robots via backend/infra; keep URL ownership on frontend.
+
+## 3. Core Web Vitals (targets)
+- LCP < 2.5 s, CLS < 0.1, INP < 200 ms on marketing pages.
+
+## 4. Asset & JS Optimization
+- Modern image formats (WebP/AVIF) with `srcset/picture`; lazy-load non-critical blocks.
+- Code splitting by route/feature; dynamically load heavy components (tables with virtualization, charts, diff/trace viewers).
+- Minimize global state; prefer streaming data in RSC where possible.
+
+## 5. Data-Heavy Views
+- Virtualize large tables (transactions, events); paginate server-side.
+- Background refetch for webhook-driven updates; avoid full-page reloads.
+- Show skeletons and incremental data rather than blank states.
+
+## 6. Analytics & Events
+- Track funnel: onboarding steps, connection success/failure, categorization actions, approvals, billing changes, report exports.
+- Respect consent/privacy; avoid sending PII in analytics events; provide trace IDs for support paths.

docs/frontend/ui-ux-guidelines.md

@@ -0,0 +1,49 @@
+# Frontend: UX/UI Guidelines
+
+---
+**Last Updated:** 2025-01-17  
+**Phase:** Phase 0 (Planning)  
+**Status:** Draft  
+**Owner:** UX/UI Team  
+**References:**
+- `/docs/content-structure.md`
+- `/docs/frontend/architecture.md`
+- `/docs/backend/payment-flow.md`
+---
+
+## 1. Tone & Clarity
+- Professional, concise, finance-friendly. Emphasize trust (audit log, reasoning traces, secure billing and webhooks).
+- Avoid jargon without tooltips; show why a decision was made (rule hit, similarity, LLM reasoning).
+
+## 2. Responsiveness
+- Mobile-friendly for quick approvals; ensure tables/lists are scrollable and readable on small screens.
+- Keep primary actions within easy reach; preserve context when opening drawers/modals.
+
+## 3. Accessibility
+- WCAG 2.2 AA: contrasts, focus states, keyboard navigation.
+- Semantic HTML and ARIA for complex components (tables with controls, dialogs, toasts, dropdowns).
+
+## 4. Key UX Flows
+### Categorization & Approvals
+- Show status per row (ingested/categorized/needs approval/approved/error).
+- Detail drawer: raw data, matched rule, scores, `reasoning_trace`, history; clear “Approve/Override” CTAs.
+- Prevent double actions; show optimistic state carefully; always provide “undo” or clear revert guidance.
+
+### Rules
+- Rule creation/edit with preview/test on sample set; highlight impact and conflicts.
+- Require confirmation when enabling a high-priority rule; surface last editor and timestamp.
+
+### Onboarding & Integrations
+- Display connection status/health for QuickBooks/bank webhooks; guide recovery/retry.
+- Stripe plan selection and post-checkout status must be clear and recoverable.
+
+### Reports & Exports
+- Show date range, currency, timezone; indicate processing state and download links when ready.
+
+## 5. Payments & Billing UX
+- Use provider trust markers (Stripe) and keep users on provider-hosted flows.
+- Post-return states: success, pending, failed; include retry/contact support options.
+
+## 6. Support & Errors
+- For webhook/ingestion errors, show actionable next steps (retry, rotate secret, re-connect).
+- Keep errors human-readable; include trace IDs for support.

docs/phases-plan.md

@@ -0,0 +1,114 @@
+# Phased Plan (Starter Template)
+
+---
+**Last Updated:** 2025-01-17  
+**Phase:** Phase 0 (Planning)  
+**Status:** Approved — update as phases complete  
+**Owner:** Product Team  
+**References:**
+- `/docs/project-overview.md` (project goals and requirements)
+- `/docs/backend/architecture.md` (technical implementation plan)
+- `/docs/frontend/architecture.md` (frontend implementation plan)
+---
+
+This document describes a phased approach you can reuse for building AI‑assisted products. Phases structure the work, assign responsibilities, and track progress.
+
+## Phase Summary
+- **Phase 0 — Discovery & Requirements**
+- **Phase 1 — Architecture & Design**
+- **Phase 2 — MVP Implementation**
+- **Phase 3 — Improvements & Scaling**
+- **Phase 4 — Support & Evolution**
+
+---
+
+## Phase 0 — Discovery & Requirements
+
+### Goals
+- Clarify user pain points, target roles, and success metrics for your domain.
+- Fix the stack choices: Next.js (TS) + Tailwind + React Query/SWR; Node.js (TS) + Express/Fastify + BullMQ + Prisma/Drizzle; Postgres + `pgvector`; billing provider (if needed); Auth provider; single LLM helper.
+- Capture functional and non‑functional requirements for ingestion, processing/classification, approvals, reporting, billing, auditability.
+
+### Key Deliverables
+- Updated `project-overview.md` with domain scope and model (e.g., Tenant, User, Record, Rule, Attachment, Report, EventLog, Embedding; `source_agent`, `reasoning_trace`).
+- Initial feature list and prioritization (MVP vs later).
+- Draft app/screen structure: `content-structure.md`.
+- Risks/assumptions (provider limits, webhook SLAs, LLM latency/costs).
+
+### Typical Tasks
+- Product/Business: competitive scan (target domain), user interviews, pricing model via subscriptions (if needed).
+- UX/Content: map journeys (onboarding, connect sources, process/classify, approve/override, create rule, report/export, billing settings) and reflect them in `content-structure.md`.
+- Tech: estimate ingestion volume/latency; plan queues/backoff/idempotency; list integrations (external providers via OAuth2/webhooks), LLM.
+
+---
+
+## Phase 1 — Architecture & Design
+
+### Goals
+- Finalize architecture (modular monolith), module boundaries, and data flows.
+- Design API surface (core entities, rules, approvals, reports, billing, events feed).
+- Prepare UX prototypes for onboarding, approvals, reports, billing.
+
+### Key Deliverables
+- `frontend/architecture.md` and `frontend/FRONTEND_ARCHITECTURE_PLAN.md` (feature-first Next.js plan, data fetching, layouts, auth handling).
+- `backend/architecture.md` with modules (ingestion, processing/classification, approvals, reporting, billing), queues, DB schema notes (JSONB traces, `pgvector`).
+- `backend/api-design.md` with resources/endpoints and event feed.
+- UX prototypes for key flows.
+
+### Typical Tasks
+- Frontend: lock App Router + Tailwind; define shell/navigation; design loading/error patterns for lists, approvals, reports.
+- Backend: draft schema (tenants, users, records, rules, attachments, reports, event logs, embeddings) with `source_agent` and `reasoning_trace`; plan ingestion/webhook handling and retries; subscription flow if applicable.
+- UX/UI: prototype onboarding, processing review, override + rule creation, reports dashboard, billing UI.
+
+---
+
+## Phase 2 — MVP Implementation
+
+### Goals
+- Deliver ingestion + processing/classification (rules → embeddings → LLM fallback) with auditability.
+- Ship approvals UI, reporting basics, and subscription billing (if applicable).
+
+### Key Deliverables
+- Onboarding/auth, source connection (external providers), tenant setup.
+- Ingestion pipeline (webhooks + workers) writing normalized records and `INGESTED` events.
+- Processing pipeline with `reasoning_trace`, `PROCESSED` events; rule management.
+- Approvals UI with override + optional rule creation; log `APPROVED`, `RULE_CREATED`.
+- Reporting (dashboards, exports) and subscription billing (provider-hosted) with webhooks.
+
+### Typical Tasks
+- Frontend: build onboarding, record lists/filters, processing review, approvals, reports, billing settings; ensure responsiveness/accessibility.
+- Backend: implement auth/tenant management; records, rules, approvals, reports, events feed; ingestion receivers with idempotency; BullMQ workers; billing webhooks.
+- Infra/DevOps: environments (dev/stage/prod), secrets, logging/metrics/tracing, CI/CD.
+
+---
+
+## Phase 3 — Improvements & Scaling
+
+### Goals
+- Increase accuracy, performance, and explainability; handle higher ingestion volume.
+
+### Key Deliverables
+- Improved processing quality (rules/embeddings tuning, prompt improvements); fewer manual approvals.
+- Performance tuning (DB indexes/partitioning, queue tuning, backoff policies).
+- Enhanced auditing/observability and cost controls.
+- Additional providers/integrations as prioritized.
+
+### Typical Tasks
+- Frontend: optimize list rendering, filters, and optimistic UX for approvals.
+- Backend: optimize queries/queues; add evaluator datasets; extend event feed for downstream agents.
+- Security/Reliability: rate limiting, alerting, rotation, resilient webhook handling.
+
+---
+
+## Phase 4 — Support & Evolution
+
+### Goals
+- Maintain stability; evolve features based on feedback and usage analytics.
+
+### Key Deliverables
+- Regular releases; updated documentation; roadmap for next 6–12 months.
+- Expanded reporting, new providers/integrations, potential extensions as demand grows.
+
+### Typical Tasks
+- Support: incident response, billing/support workflows, ingestion failure handling.
+- Evolution: provider additions, deeper analytics, UX refinements, potential mobile/webview shells if needed.

docs/project-overview.md

@@ -0,0 +1,82 @@
+# Project Overview: Starter Template (Provider‑agnostic)
+
+---
+**Last Updated:** 2025-01-17  
+**Phase:** Phase 0 (Planning)  
+**Status:** Approved  
+**Owner:** Product Team  
+**References:**  
+- `/docs/phases-plan.md` (development roadmap)  
+- `/docs/content-structure.md` (app/screen structure)
+---
+
+## 1. Project Goal
+
+Provide a universal starting point for new products that leverage AI assistance. The template outlines how to structure documentation and technical decisions for projects that may include data ingestion, processing/classification (rules + embeddings + LLM), human approvals, reporting, and optional billing.
+
+Emphasis areas: trust (auditability, optional reasoning traces), speed (near‑real‑time processing), and clarity (human approvals and transparent reporting), adaptable to your domain.
+
+## 2. Target Audience
+
+- Define your primary users and stakeholders for the target domain.
+- Typical teams value:
+  - automation with explainability (reasoning traces and event logs);
+  - reliability (idempotent ingestion, safe retries);
+  - compliance (audit trail, role‑based access).
+
+## 3. Unique Value Proposition
+
+1. **Automated processing with explainability**  
+   Rules + embeddings (`pgvector`) first, LLM fallback via a single helper, with optional `reasoning_trace` per record.
+2. **Human‑in‑the‑loop approvals**  
+   Review/override UI with optional rule creation; every action is logged (e.g., `source_agent`).
+3. **Reliable ingestion**  
+   OAuth2/webhooks for external providers; idempotent event handling; queue workers for retries.
+4. **Reporting & optional billing**  
+   Dashboards/exports per tenant; subscription management with tenant‑scoped access control.
+5. **Multi‑tenant and secure by design**  
+   Tenant isolation, RBAC, webhook verification, audit log (`EventLog`).
+
+## 4. Key Features (example template)
+
+### 4.1. Onboarding & Integrations
+- Tenant signup/login (Clerk/Auth.js or equivalent).
+- Connect external data sources (OAuth2, webhooks, file uploads, etc.).
+- Configure subscription/billing if applicable.
+- Example domain model (multi‑tenant): `Tenant`, `User`, `Record`, `Rule`, `Attachment`, `Report`, `EventLog`, `Embedding`; `EventLog.source_agent` (e.g., default value), `Record.reasoning_trace` JSONB.
+
+### 4.2. Ingestion
+- Webhooks/workers normalize provider payloads into a unified schema.
+- Idempotent writes; deduplication; `INGESTED` events with `source_agent`.
+
+### 4.3. Classification/Processing
+- Rule engine first; embeddings similarity next; LLM fallback via `callLLM()`.
+- Optionally persist `reasoning_trace` JSONB on records; log `PROCESSED` (or similar).
+
+### 4.4. Approval & Rules
+- UI for reviewing/overriding outcomes; optional rule creation from overrides.
+- Log `APPROVED`, `RULE_CREATED`; track who/when/why.
+
+### 4.5. Reporting & Events
+- Dashboards and exports per tenant.
+- Read‑only `/api/events` for downstream agents and observability.
+
+### 4.6. Billing & Access
+- Subscriptions via a payment provider; tenant‑scoped roles.
+- Audit log (`EventLog`) with `source_agent`.
+
+## 5. Non‑Functional Requirements (High‑Level)
+
+- **Reliability:** idempotent ingestion/webhooks, durable queues, retries, monitoring.
+- **Security:** RBAC per tenant, webhook signature verification, secret management, audit/event logging; no raw card data stored.
+- **Performance:** near real‑time processing and acceptable latency for human approvals; fast UI for lists/filters.
+- **Explainability:** every automated decision includes `reasoning_trace`; events logged with `source_agent`.
+- **Localization:** primary UI in English; other locales optional.
+- **Operational tooling:** queue-based pipelines (BullMQ + Redis) with observability and dead-letter handling for ingestion/categorization/reporting jobs.
+
+## 6. Constraints and Assumptions
+
+- Web-first product (desktop + mobile web). Native apps not in scope for V1.
+- Payments via a provider; exact choice is project‑specific.
+- LLM calls should go through a single abstraction to swap models easily.
+- Multi‑agent readiness: consider `EventLog.source_agent` and optional `reasoning_trace`.