# StellaOps Database Documentation

This directory contains all documentation related to the StellaOps database architecture, including the MongoDB to PostgreSQL conversion project.

> **ADR Reference:** See [ADR-0001: PostgreSQL for Control-Plane Storage](../adr/0001-postgresql-for-control-plane.md) for the architectural decision rationale.

## Document Index

| Document | Purpose |
|----------|---------|
| [SPECIFICATION.md](./SPECIFICATION.md) | PostgreSQL schema design specification, data types, naming conventions |
| [RULES.md](./RULES.md) | Database coding rules, patterns, and constraints for all developers |
| [CONVERSION_PLAN.md](./CONVERSION_PLAN.md) | Strategic plan for MongoDB to PostgreSQL conversion |
| [VERIFICATION.md](./VERIFICATION.md) | Testing and verification requirements for database changes |

## Task Definitions

Sprint-level task definitions for the conversion project:

| Phase | Document | Status |
|-------|----------|--------|
| Phase 0 | [tasks/PHASE_0_FOUNDATIONS.md](./tasks/PHASE_0_FOUNDATIONS.md) | TODO |
| Phase 1 | [tasks/PHASE_1_AUTHORITY.md](./tasks/PHASE_1_AUTHORITY.md) | DONE |
| Phase 2 | [tasks/PHASE_2_SCHEDULER.md](./tasks/PHASE_2_SCHEDULER.md) | TODO |
| Phase 3 | [tasks/PHASE_3_NOTIFY.md](./tasks/PHASE_3_NOTIFY.md) | DONE |
| Phase 4 | [tasks/PHASE_4_POLICY.md](./tasks/PHASE_4_POLICY.md) | TODO |
| Phase 5 | [tasks/PHASE_5_VULNERABILITIES.md](./tasks/PHASE_5_VULNERABILITIES.md) | TODO |
| Phase 6 | [tasks/PHASE_6_VEX_GRAPH.md](./tasks/PHASE_6_VEX_GRAPH.md) | TODO |
| Phase 7 | [tasks/PHASE_7_CLEANUP.md](./tasks/PHASE_7_CLEANUP.md) | TODO |

## Schema Reference

Schema DDL files (generated from specifications):

| Schema | File | Tables |
|--------|------|--------|
| authority | [schemas/authority.sql](./schemas/authority.sql) | 12 |
| vuln | [schemas/vuln.sql](./schemas/vuln.sql) | 12 |
| vex | [schemas/vex.sql](./schemas/vex.sql) | 13 |
| scheduler | [schemas/scheduler.sql](./schemas/scheduler.sql) | 10 |
| notify | [schemas/notify.sql](./schemas/notify.sql) | 17 |
| policy | [schemas/policy.sql](./schemas/policy.sql) | 8 |
| packs | Included in policy schema | — |
| issuer | [schemas/issuer.sql](./schemas/issuer.sql) | PROPOSED |
| audit (shared) | [schemas/audit.sql](./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](./RULES.md) for coding conventions
- **For architects**: Review [SPECIFICATION.md](./SPECIFICATION.md) for design rationale
- **For project managers**: See [CONVERSION_PLAN.md](./CONVERSION_PLAN.md) for timeline and phases
- **For QA**: Check [VERIFICATION.md](./VERIFICATION.md) for testing requirements

## Key Principles

1. **Determinism First**: All database operations must produce reproducible, stable outputs
2. **Tenant Isolation**: Multi-tenancy via `tenant_id` column with row-level security
3. **Strangler Fig Pattern**: Gradual conversion with rollback capability per module
4. **JSONB for Flexibility**: Semi-structured data stays as JSONB, relational data normalizes

## Related Documentation

- [Architecture Overview](../07_HIGH_LEVEL_ARCHITECTURE.md)
- [Module Dossiers](../modules/)
- [Air-Gap Operations](../24_OFFLINE_KIT.md)