118 lines
5.8 KiB
Markdown
118 lines
5.8 KiB
Markdown
# 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.
|