38a0f0619d
Archive milestone artifacts (roadmap, requirements, audit, phase directories) to .planning/milestones/. Evolve PROJECT.md with validated requirements and decision outcomes. Create MILESTONES.md and RETROSPECTIVE.md. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
64 lines
3.0 KiB
Markdown
64 lines
3.0 KiB
Markdown
# Phase 1: Data Foundation - Context
|
|
|
|
**Gathered:** 2026-02-24
|
|
**Status:** Ready for planning
|
|
|
|
<domain>
|
|
## Phase Boundary
|
|
|
|
Create database schema (tables, indexes, migrations) and model layer for the monitoring system. Requirements: INFR-01 (tables with indexes), INFR-04 (use existing Supabase connection). No services, no API routes, no frontend work.
|
|
|
|
</domain>
|
|
|
|
<decisions>
|
|
## Implementation Decisions
|
|
|
|
### Migration approach
|
|
- Use the existing `DatabaseMigrator` class in `backend/src/models/migrate.ts`
|
|
- New `.sql` files go in `src/models/migrations/`, run with `npm run db:migrate`
|
|
- The migrator tracks applied migrations in a `migrations` table — handles idempotency
|
|
- Forward-only migrations (no rollback/down scripts). If something needs fixing, write a new migration.
|
|
- Migrations execute via `supabase.rpc('exec_sql', { sql })` — works with cloud Supabase from any environment including Firebase
|
|
|
|
### Schema details
|
|
- Status fields use TEXT with CHECK constraints (e.g., `CHECK (status IN ('healthy','degraded','down'))`) — easy to extend, no enum type management
|
|
- Table names are descriptive, matching existing style: `service_health_checks`, `alert_events` (like `processing_jobs`, `document_chunks`)
|
|
- Include JSONB `probe_details` / `details` columns for flexible metadata per service (response codes, error specifics) without future schema changes
|
|
- All tables get indexes on `created_at` (required for 30-day retention queries and dashboard time-range filters)
|
|
- Enable Row Level Security on new tables — admin-only access, matching existing security patterns
|
|
|
|
### Model layer pattern
|
|
- One model file per table: `HealthCheckModel.ts`, `AlertEventModel.ts`
|
|
- Static methods on model classes (e.g., `AlertEventModel.create()`, `AlertEventModel.findActive()`) — matches `DocumentModel.ts` pattern
|
|
- Use `getSupabaseServiceClient()` (PostgREST) for all monitoring reads/writes — monitoring is not on the critical processing path, so no need for direct PostgreSQL pool
|
|
- Input validation in the model layer before writing (defense in depth alongside DB CHECK constraints)
|
|
|
|
### Claude's Discretion
|
|
- Exact column types for non-status fields (INTEGER vs BIGINT for latency_ms, etc.)
|
|
- Whether to create a shared base model or keep models independent
|
|
- Index strategy beyond created_at (e.g., composite indexes on service_name + created_at)
|
|
- Winston logging patterns within model methods
|
|
|
|
</decisions>
|
|
|
|
<specifics>
|
|
## Specific Ideas
|
|
|
|
- The existing `performance_metrics` table already exists but nothing writes to it — verify its schema before building on it
|
|
- Research found that `uploadMonitoringService.ts` stores data in-memory only — the new persistent tables replace this pattern
|
|
- The `ProcessingJobModel.ts` uses direct PostgreSQL for critical writes as a pattern reference, but monitoring tables don't need this
|
|
|
|
</specifics>
|
|
|
|
<deferred>
|
|
## Deferred Ideas
|
|
|
|
None — discussion stayed within phase scope
|
|
|
|
</deferred>
|
|
|
|
---
|
|
|
|
*Phase: 01-data-foundation*
|
|
*Context gathered: 2026-02-24*
|