docs: create roadmap (4 phases)
This commit is contained in:
admin
@@ -75,27 +75,27 @@ Which phases cover which requirements. Updated during roadmap creation.
|
||||
|
||||
| Requirement | Phase | Status |
|
||||
|-------------|-------|--------|
|
||||
| HLTH-01 | — | Pending |
|
||||
| HLTH-02 | — | Pending |
|
||||
| HLTH-03 | — | Pending |
|
||||
| HLTH-04 | — | Pending |
|
||||
| ALRT-01 | — | Pending |
|
||||
| ALRT-02 | — | Pending |
|
||||
| ALRT-03 | — | Pending |
|
||||
| ALRT-04 | — | Pending |
|
||||
| ANLY-01 | — | Pending |
|
||||
| ANLY-02 | — | Pending |
|
||||
| ANLY-03 | — | Pending |
|
||||
| INFR-01 | — | Pending |
|
||||
| INFR-02 | — | Pending |
|
||||
| INFR-03 | — | Pending |
|
||||
| INFR-04 | — | Pending |
|
||||
| INFR-01 | Phase 1 | Pending |
|
||||
| INFR-04 | Phase 1 | Pending |
|
||||
| HLTH-02 | Phase 2 | Pending |
|
||||
| HLTH-03 | Phase 2 | Pending |
|
||||
| HLTH-04 | Phase 2 | Pending |
|
||||
| ALRT-01 | Phase 2 | Pending |
|
||||
| ALRT-02 | Phase 2 | Pending |
|
||||
| ALRT-04 | Phase 2 | Pending |
|
||||
| ANLY-01 | Phase 2 | Pending |
|
||||
| ANLY-03 | Phase 2 | Pending |
|
||||
| INFR-03 | Phase 2 | Pending |
|
||||
| INFR-02 | Phase 3 | Pending |
|
||||
| HLTH-01 | Phase 3 | Pending |
|
||||
| ANLY-02 | Phase 3 | Pending |
|
||||
| ALRT-03 | Phase 4 | Pending |
|
||||
|
||||
**Coverage:**
|
||||
- v1 requirements: 15 total
|
||||
- Mapped to phases: 0
|
||||
- Unmapped: 15
|
||||
- Mapped to phases: 15
|
||||
- Unmapped: 0
|
||||
|
||||
---
|
||||
*Requirements defined: 2026-02-24*
|
||||
*Last updated: 2026-02-24 after initial definition*
|
||||
*Last updated: 2026-02-24 — traceability mapped after roadmap creation*
|
||||
|
||||
78
.planning/ROADMAP.md
Normal file
78
.planning/ROADMAP.md
Normal file
@@ -0,0 +1,78 @@
|
||||
# Roadmap: CIM Summary — Analytics & Monitoring
|
||||
|
||||
## Overview
|
||||
|
||||
This milestone adds persistent analytics and service health monitoring to the existing CIM Summary application. The work proceeds in four phases that respect hard dependency constraints: database schema must exist before services can write to it, services must exist before routes can expose them, and routes must be stable before the frontend can be wired up. Each phase delivers a complete, independently testable layer.
|
||||
|
||||
## Phases
|
||||
|
||||
**Phase Numbering:**
|
||||
- Integer phases (1, 2, 3): Planned milestone work
|
||||
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
|
||||
|
||||
Decimal phases appear between their surrounding integers in numeric order.
|
||||
|
||||
- [ ] **Phase 1: Data Foundation** - Create schema, DB models, and verify existing Supabase connection wiring
|
||||
- [ ] **Phase 2: Backend Services** - Health probers, alert trigger, email sender, analytics collector, scheduler, retention cleanup
|
||||
- [ ] **Phase 3: API Layer** - Admin-gated routes exposing all services, instrumentation hooks in existing processors
|
||||
- [ ] **Phase 4: Frontend** - Admin dashboard page, health panel, processing metrics, alert notification banner
|
||||
|
||||
## Phase Details
|
||||
|
||||
### Phase 1: Data Foundation
|
||||
**Goal**: The database schema for monitoring exists and the existing Supabase connection is the only data infrastructure used
|
||||
**Depends on**: Nothing (first phase)
|
||||
**Requirements**: INFR-01, INFR-04
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. `service_health_status` and `service_alerts` tables exist in Supabase with indexes on `created_at`
|
||||
2. All new tables use the existing Supabase client from `config/supabase.ts` — no new database connections added
|
||||
3. `AlertModel.ts` exists and its CRUD methods can be called in isolation without errors
|
||||
4. Migration SQL can be run against the live Supabase instance and produces the expected schema
|
||||
**Plans**: TBD
|
||||
|
||||
### Phase 2: Backend Services
|
||||
**Goal**: All monitoring logic runs correctly — health probes make real API calls, alerts fire with deduplication, analytics events write non-blocking to Supabase, and data is cleaned up on schedule
|
||||
**Depends on**: Phase 1
|
||||
**Requirements**: HLTH-02, HLTH-03, HLTH-04, ALRT-01, ALRT-02, ALRT-04, ANLY-01, ANLY-03, INFR-03
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. Each health probe makes a real authenticated API call to its target service and returns a structured result (status, latency_ms, error_message)
|
||||
2. Health probe results are written to Supabase and survive a simulated cold start (data present after function restart)
|
||||
3. An alert email is sent when a service probe returns degraded or down, and a second probe failure within the cooldown period does not send a duplicate email
|
||||
4. Alert recipient is read from configuration (environment variable or Supabase config row), not hardcoded in source
|
||||
5. Analytics events fire as fire-and-forget calls — a deliberately introduced 500ms Supabase delay does not increase processing pipeline duration
|
||||
6. A scheduled probe function and a weekly retention cleanup function exist as separate Firebase Cloud Function exports
|
||||
**Plans**: TBD
|
||||
|
||||
### Phase 3: API Layer
|
||||
**Goal**: Admin-authenticated HTTP endpoints expose health status, alerts, and processing analytics; existing service processors emit analytics instrumentation
|
||||
**Depends on**: Phase 2
|
||||
**Requirements**: INFR-02, HLTH-01, ANLY-02
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. `GET /admin/health` returns current health status for all four services; a request with a non-admin Firebase token receives 403
|
||||
2. `GET /admin/analytics` returns processing summary (upload counts, success/failure rates, avg processing time) sourced from Supabase, not in-memory state
|
||||
3. `GET /admin/alerts` and `POST /admin/alerts/:id/acknowledge` function correctly and are blocked to non-admin users
|
||||
4. Document processing in `jobProcessorService.ts` and `llmService.ts` emits analytics events at stage transitions without any change to existing processing behavior
|
||||
**Plans**: TBD
|
||||
|
||||
### Phase 4: Frontend
|
||||
**Goal**: The admin can see live service health, processing metrics, and active alerts directly in the application UI
|
||||
**Depends on**: Phase 3
|
||||
**Requirements**: ALRT-03, ANLY-02 (UI delivery), HLTH-01 (UI delivery)
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. An alert banner appears at the top of the admin UI when there is at least one unacknowledged critical alert, and disappears after the admin acknowledges it
|
||||
2. The admin dashboard shows health status indicators (green/yellow/red) for all four services, with the last-checked timestamp visible
|
||||
3. The admin dashboard shows processing metrics (upload counts, success/failure rates, average processing time) sourced from the persistent Supabase backend
|
||||
4. A non-admin user visiting the admin route is redirected or shown an access-denied state
|
||||
**Plans**: TBD
|
||||
|
||||
## Progress
|
||||
|
||||
**Execution Order:**
|
||||
Phases execute in numeric order: 1 → 2 → 3 → 4
|
||||
|
||||
| Phase | Plans Complete | Status | Completed |
|
||||
|-------|----------------|--------|-----------|
|
||||
| 1. Data Foundation | 0/TBD | Not started | - |
|
||||
| 2. Backend Services | 0/TBD | Not started | - |
|
||||
| 3. API Layer | 0/TBD | Not started | - |
|
||||
| 4. Frontend | 0/TBD | Not started | - |
|
||||
64
.planning/STATE.md
Normal file
64
.planning/STATE.md
Normal file
@@ -0,0 +1,64 @@
|
||||
# Project State
|
||||
|
||||
## Project Reference
|
||||
|
||||
See: .planning/PROJECT.md (updated 2026-02-24)
|
||||
|
||||
**Core value:** When something breaks — an API key expires, a service goes down, a credential needs reauthorization — the admin knows immediately and knows exactly what to fix.
|
||||
**Current focus:** Phase 1 — Data Foundation
|
||||
|
||||
## Current Position
|
||||
|
||||
Phase: 1 of 4 (Data Foundation)
|
||||
Plan: 0 of TBD in current phase
|
||||
Status: Ready to plan
|
||||
Last activity: 2026-02-24 — Roadmap created
|
||||
|
||||
Progress: [░░░░░░░░░░] 0%
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
**Velocity:**
|
||||
- Total plans completed: 0
|
||||
- Average duration: —
|
||||
- Total execution time: 0 hours
|
||||
|
||||
**By Phase:**
|
||||
|
||||
| Phase | Plans | Total | Avg/Plan |
|
||||
|-------|-------|-------|----------|
|
||||
| - | - | - | - |
|
||||
|
||||
**Recent Trend:**
|
||||
- Last 5 plans: —
|
||||
- Trend: —
|
||||
|
||||
*Updated after each plan completion*
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
### Decisions
|
||||
|
||||
Decisions are logged in PROJECT.md Key Decisions table.
|
||||
Recent decisions affecting current work:
|
||||
|
||||
- Roadmap: 4 phases following data layer → services → API → frontend dependency order
|
||||
- Architecture: Health probes decoupled from document processing as separate Cloud Function export
|
||||
- Architecture: Analytics writes are always fire-and-forget (never await on critical path)
|
||||
- Architecture: Alert recipient stored in config, not hardcoded (PITFALL-8 prevention)
|
||||
|
||||
### Pending Todos
|
||||
|
||||
None yet.
|
||||
|
||||
### Blockers/Concerns
|
||||
|
||||
- PITFALL-2: Health probe scheduler must be a separate named Cloud Function export, not piggybacked on `processDocumentJobs`
|
||||
- PITFALL-6: Each analytics instrumentation point must be void/fire-and-forget — reviewer must check this in Phase 3
|
||||
- PITFALL-10: All new tables need `created_at` indexes in Phase 1 migrations — query performance depends on this from day one
|
||||
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-02-24
|
||||
Stopped at: Roadmap created, STATE.md initialized. Ready to plan Phase 1.
|
||||
Resume file: None
|
||||
Reference in New Issue
Block a user