docs: Postgres data model reference + stale schema doc cleanup

[bjcoombs]

Summary

Adds docs/architecture/data-model.md as the consolidated reference for how Meridian stores data in Postgres, and tidies schema docs that drifted after the recent tenant-isolation merges.

New doc - docs/architecture/data-model.md

End-to-end reference covering:

• Topology - database-per-service plus schema-per-tenant (org_<id>), with meridian_platform as the single platform DB for control-plane and tenant services
• Tenant isolation mechanism - how services/tenant/provisioner/postgres_provisioner.go provisions org_<id> schemas, and how shared/platform/db/gorm_tenant_scope.go routes requests via SET LOCAL search_path
• Reference data replication - the seeder pipeline registered in cmd/meridian/wire_services.go (InstrumentSeeder, SagaSeeder, AccountTypeSeeder, ValuationSeeder, IdentityBootstrap) that replicates platform reference data into each tenant schema on provisioning
• Service inventory - one-row-per-service table mapping service → database → schema location → BIAN domain
• Table ownership - what each of the ~85 tables across 19 services stores, organised by platform tier vs BIAN domain tier
• Cross-tenant access - the only cross-tenant pattern in the codebase (public.tenant_data_entitlements in market-information) and why
• Shared patterns - outbox, immutable audit, bi-temporal data, append-only positions, FK-stops-at-service-boundary

Doc tidy-up

Recent merges that made existing docs partially stale:

• Remove public from search_path - replicate reference data per-tenant #2125 - Removed public from search_path, replicating reference data per-tenant
• feat: self-service sign-up to tenant creation end-to-end flow #2126 - Self-service signup to tenant creation end-to-end flow
• Earlier - Database migration target moved from CockroachDB to Postgres 16

Changes:

1. docs/adr/0003-database-schema-migrations.md - Added a note marking the CockroachDB Compatibility Considerations section as historical (constraints are retained for migration authoring consistency but the runtime is Postgres). Updated the schema-per-org description to reflect the transactional SET LOCAL search_path mechanism and PR Remove public from search_path - replicate reference data per-tenant #2125's removal of public from the search_path. Cross-linked to the new data-model doc.
2. docs/runbooks/database-per-service-migration.md → docs/archive/ - This runbook documented a one-time migration that is now complete. Moved to archive with an updated frontmatter note pointing to the current topology doc.

Other stale files (docs/archive/ARCHITECTURE.md, docs/reports/cockroachdb-migration-audit.md) were already archived or correctly labelled as historical audits, so they are out of scope here.

Test plan

• Markdown lint passes (pre-commit hook - passed)
• Cross-links resolve
• Table of services matches services/ directory
• Claims about tenant provisioning match services/tenant/provisioner/postgres_provisioner.go and shared/platform/db/gorm_tenant_scope.go
• Claims about PR Remove public from search_path - replicate reference data per-tenant #2125 search_path change match git show 007371ee

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 4b194e5b-eef1-4209-aa6a-99b752651c2d

📥 Commits

Reviewing files that changed from the base of the PR and between a8daa33 and 00e489f.

📒 Files selected for processing (1)

• docs/archive/database-per-service-migration.md

✅ Files skipped from review due to trivial changes (1)

• docs/archive/database-per-service-migration.md

---

📝 Walkthrough

Walkthrough

Updated tenant routing to use transaction-scoped SET LOCAL search_path TO org_<id> (removing public fallback), added a comprehensive Postgres data-model reference, archived the database-per-service migration runbook, updated cross-references, and applied minor markdown formatting edits across many docs.

Changes

Cohort / File(s)	Summary
ADR / Tenant routing docs/adr/0003-database-schema-migrations.md	Rewrote tenant schema routing to describe transaction-scoped SET LOCAL search_path TO org_<id>, noted public removed from search_path, documented reference-data replication into tenant schemas, and marked CockroachDB guidance as historical.
Platform DB tenant scope (code) shared/platform/db/gorm_tenant_scope.go	Implemented/updated transaction-scoped tenant routing using SET LOCAL search_path (documented in ADR).
New data model reference docs/architecture/data-model.md	Added end-to-end Postgres data model reference: topology (database-per-service, schema-per-tenant), provisioning sequence and fail-hard behavior, transactional tenant scoping, reference-data replication, cross-tenant/shared-data patterns, and Atlas-based migrations.
Runbook archival docs/archive/database-per-service-migration.md, docs/runbooks/README.md	Converted migration runbook to archived status, rewrote frontmatter/instructions to reference the new data model doc, and removed/redirected index links.
Cross-reference updates docs/adr/0002-microservices-per-bian-domain.md, docs/guides/new-bian-service-checklist.md, docs/runbooks/internal-account-operations.md	Replaced links to the active migration runbook with links to the Data Model Reference or the archived runbook.
Whitespace / formatting edits (multiple docs) docs/..., docs/prd/*, docs/runbooks/*, docs/saga-service-catalog.md, shared/README.md	Minor Markdown formatting: added/removed blank lines and separators; no semantic changes.
Large add / documentation-only docs/architecture/data-model.md (new, +281 lines)	Large new documentation content; no changes to exported/public code entities.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the two main changes: adding a new Postgres data model reference document and cleaning up stale schema documentation.
Description check	✅ Passed	The description is clearly related to the changeset, providing detailed context about the new data model documentation and the stale doc cleanup efforts.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs-data-model-overview

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

Documentation-only PR, well-verified against the codebase. One non-blocking issue: docs/archive/database-per-service-migration.md has broken relative links to ./incident-response.md and ./disaster-recovery.md (lines 393-394). These files exist in docs/runbooks/ but the file was moved to docs/archive/. Update to ../runbooks/incident-response.md and ../runbooks/disaster-recovery.md. This is what is failing the Link Integrity CI check. Otherwise the PR is solid - all factual claims in the new data-model.md were verified against source code.

[claude]

Claude Code Review

Commit: 00e489f | CI: Markdown Lint, Link Integrity, Service Conventions passing; CodeQL, security scanners still running
Well-executed documentation PR. The new data-model.md is a thorough, accurate reference for the Postgres data model. All factual claims verified against the codebase (tenant provisioning, request routing, seeders, cross-tenant access, service count). ADR-0003 updates correctly mark CockroachDB constraints as historical. Link fixes in commit 3 resolved broken references from the previous review.
Risk: Low across all dimensions - documentation only, safely revertible, no runtime impact.
Findings:

• Note data-model.md 146-156: Seeders table lists 5 but wire_services.go registers a 6th NewSelfRegisteredAdminHook from PR 2126. Consider adding for completeness.
• Note data-model.md 261: Quality ladder ESTIMATE ACTUAL VERIFIED matches code in quality_level.go but broader project docs reference a 4-level ladder. Worth noting for future alignment.
  Previously Flagged:
• Improvement database-per-service-migration.md 393-394: Broken relative links after file move to archive - Resolved commit 3
  Bot Review Notes: No unresolved bot threads found on this PR.

[claude]

Documentation-only PR with verified factual accuracy. Two informational notes in the summary comment (missing 6th seeder, quality ladder terminology). No correctness issues. See summary comment for details.