50abd2137f
Add 12 new sprint files (Integrations, Graph, JobEngine, FE, Router, AdvisoryAI), archive completed scheduler UI sprint, update module architecture docs (router, graph, jobengine, web, integrations), and add Gitea entrypoint script for local dev. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
StellaOps Database Documentation
This directory contains all documentation related to the StellaOps database architecture. The MongoDB to PostgreSQL conversion was completed in Sprint 4400; historical conversion docs remain for reference.
ADR Reference: See ADR-0001: PostgreSQL for Control-Plane Storage for the architectural decision rationale.
Document Index
| Document | Purpose |
|---|---|
| SPECIFICATION.md | PostgreSQL schema design specification, data types, naming conventions |
| RULES.md | Database coding rules, patterns, and constraints for all developers |
| CONVERSION_PLAN.md | Strategic plan for MongoDB to PostgreSQL conversion |
| VERIFICATION.md | Testing and verification requirements for database changes |
| MIGRATION_STRATEGY.md | Canonical migration strategy and category semantics |
| MIGRATION_CONVENTIONS.md | Migration naming, numbering, and runner conventions |
| MIGRATION_INVENTORY.md | Current-state service migration matrix (DAL, locations, counts, runner) |
| MIGRATION_CONSOLIDATION_PLAN.md | Runner consolidation waves and legacy compatibility mapping for on-prem upgrades |
Task Definitions
Sprint-level task definitions for the conversion project:
| Phase | Document | Status |
|---|---|---|
| Phase 0 | tasks/PHASE_0_FOUNDATIONS.md | TODO |
| Phase 1 | tasks/PHASE_1_AUTHORITY.md | DONE |
| Phase 2 | tasks/PHASE_2_SCHEDULER.md | TODO |
| Phase 3 | tasks/PHASE_3_NOTIFY.md | DONE |
| Phase 4 | tasks/PHASE_4_POLICY.md | TODO |
| Phase 5 | tasks/PHASE_5_VULNERABILITIES.md | TODO |
| Phase 6 | tasks/PHASE_6_VEX_GRAPH.md | TODO |
| Phase 7 | tasks/PHASE_7_CLEANUP.md | TODO |
Schema Reference
Schema DDL files (generated from specifications):
| Schema | File | Tables |
|---|---|---|
| authority | schemas/authority.sql | 12 |
| vuln | schemas/vuln.sql | 12 |
| vex | schemas/vex.sql | 13 |
| scheduler | schemas/scheduler.sql | 10 |
| notify | schemas/notify.sql | 17 |
| policy | schemas/policy.sql | 8 |
| packs | Included in policy schema | — |
| issuer | schemas/issuer.sql | PROPOSED |
| audit (shared) | schemas/audit.sql | PROPOSED |
Notes:
- Authority, vuln, vex, scheduler DDLs have been exported from SPECIFICATION.md. Notify, policy, packs, issuer, and audit remain to be exported (placeholders present).
- Persistence configuration template:
docs/db/persistence-config-template.yaml(replace hosts/creds per environment). - Cluster provisioning inputs template:
docs/db/cluster-provisioning.md.
Quick Links
- For developers: Start with RULES.md for coding conventions
- For architects: Review SPECIFICATION.md for design rationale
- For project managers: See CONVERSION_PLAN.md for timeline and phases
- For QA: Check VERIFICATION.md for testing requirements
Key Principles
- Determinism First: All database operations must produce reproducible, stable outputs
- Tenant Isolation: Multi-tenancy via
tenant_idcolumn with row-level security - Strangler Fig Pattern: Gradual conversion with rollback capability per module
- JSONB for Flexibility: Semi-structured data stays as JSONB, relational data normalizes