AI_template/docs/phases-plan.md

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.