create AI_template

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.