# Phased Plan (Starter Template)

---
**Phase:** Phase 0 (Planning)
**Status:** Draft — 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.

> Phases and tasks are **modular**. After choosing an archetype in `/docs/archetypes.md`, delete or ignore tasks that don’t apply to your product.

## 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.
- Initial **ADR set** in `docs/adr/` for all locked decisions.
- Initial **repo skeleton** (`apps/web`, `apps/api`, `packages/shared`) and `docs/dev-setup.md` ready for Phase 2 coding.

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