ADR-064: Master Inventory Management and Deployment Synchronization
| Field | Value |
|---|---|
| Status | Accepted |
| Date | 2026-01-10 |
| Author | Hal Casteel |
| Reviewers | Claude Opus 4.5 |
| Category | Infrastructure & Operations |
| Tags | inventory, deployment, synchronization, infrastructure, multi-repo |
1. Executive Summary
This ADR establishes the architecture for maintaining a centralized CODITECT Deployment Inventory - a single source of truth (SSOT) document that catalogs all repositories, Docker images, Kubernetes resources, GCP services, and deployment dependencies. The system ensures inventory accuracy through automated validation and manual curation processes.
2. Context
2.1 Problem Statement
CODITECT's distributed architecture spans:
- 74 git submodules across 12 categories
- Multiple GCP projects (coditect-cloud-infra, coditect-citus-prod)
- Multiple deployment targets (GKE, Cloud Run, Cloud Workstations)
- Multiple environments (dev, staging, production)
- Multiple domains (api.coditect.ai, docs.coditect.ai, auth.coditect.ai, etc.)
Without a centralized inventory:
- Teams lack visibility into what components exist and their relationships
- Deployment verification becomes manual and error-prone
- New contributors struggle to understand system scope
- Disaster recovery planning is incomplete
- Audit compliance requires manual evidence gathering
2.2 Requirements
| Requirement | Priority | Description |
|---|---|---|
| Centralized SSOT | P0 | Single document for all deployment components |
| Multi-repo coverage | P0 | Cover all 74 submodules with categorization |
| GCP resource mapping | P0 | Map all GCP projects, services, and resources |
| Docker image tracking | P0 | Track all container images and registries |
| Kubernetes manifest coverage | P0 | Document all K8s resources by namespace |
| Dependency mapping | P1 | Show inter-component relationships |
| Version tracking | P1 | Track deployed versions per environment |
| Automated validation | P2 | CI/CD checks for inventory drift |
3. Decision
3.1 Master Inventory Document
Maintain a comprehensive inventory document at:
docs/internal/CODITECT-DEPLOYMENT-INVENTORY.md
Document Structure:
CODITECT-DEPLOYMENT-INVENTORY.md
├── 1. Production Domains & Endpoints
├── 2. Repository Inventory (74 submodules)
│ ├── 2.1 Core Repositories (Pilot Critical)
│ ├── 2.2 Supporting Repositories
│ ├── 2.3 Operations Repositories
│ ├── 2.4 Integration Repositories
│ └── 2.5 Documentation Repositories
├── 3. GCP Project Structure
├── 4. Docker Images & Registries
├── 5. Kubernetes Resources
│ ├── 5.1 Namespaces
│ ├── 5.2 Deployments
│ ├── 5.3 Services
│ └── 5.4 ConfigMaps & Secrets
├── 6. OpenTofu Infrastructure Modules
├── 7. Cloud Run Services
├── 8. Backend API Components
├── 9. Email Infrastructure
├── 10. Secret Management
├── 11. CI/CD Pipelines
├── 12. Monitoring & Observability
├── 13. Component Dependencies
└── 14. Pilot Launch Checklist
3.2 Architecture
┌─────────────────────────────────────────────────────────────────────────────┐
│ CODITECT Inventory System │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
│ │ Git Repos │ │ GCP Console │ │ Kubernetes │ │
│ │ (74 Submodules)│ │ (2 Projects) │ │ (GKE Cluster)│ │
│ └───────┬────────┘ └───────┬────────┘ └───────┬────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Inventory Collection Layer │ │
│ │ • git submodule foreach │ │
│ │ • gcloud projects/services list │ │
│ │ • kubectl get all --all-namespaces │ │
│ │ • docker images / Artifact Registry │ │
│ └─────────────────────────────┬───────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ CODITECT-DEPLOYMENT-INVENTORY.md (SSOT) │ │
│ │ │ │
│ │ • Production Domains • Docker Images │ │
│ │ • Repository Inventory • Kubernetes Resources │ │
│ │ • GCP Project Structure • CI/CD Pipelines │ │
│ │ • Infrastructure Modules • Component Dependencies │ │
│ └─────────────────────────────┬───────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────┼───────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Deployment │ │ Disaster │ │ Compliance │ │
│ │ Verification │ │ Recovery │ │ Auditing │ │
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
3.3 Submodule Categorization
| Category | Count | Purpose |
|---|---|---|
core/ | 8 | Framework, CLI, architecture, extensions |
cloud/ | 5 | Backend, frontend, IDE, infra, GCP services |
dev/ | 4 | Development tools, templates, generative UI |
docs/ | 7 | Main docs, blog, training, samples, setup |
gtm/ | 5 | Brand, marketing, launch, sales |
integrations/ | 17 | Third-party integrations (Stripe, GitHub, Google, etc.) |
labs/ | 5 | Archive, experiments, V4 legacy |
ops/ | 9 | Distribution, license, compliance, DMS |
compliance/ | 3 | Regulatory compliance frameworks |
investors/ | 3 | Pitch decks, financials |
products/ | 5 | Product repositories |
r-and-d/ | 3 | Research and development |
3.4 GCP Project Mapping
GCP Projects
├── coditect-cloud-infra (374018874256)
│ ├── Cloud Run (docs-coditect, auth-coditect)
│ ├── Artifact Registry (coditect-docs, coditect-dms)
│ ├── Secret Manager
│ └── Cloud Build
│
└── coditect-citus-prod
├── GKE Cluster (coditect-gke)
├── Cloud SQL (PostgreSQL 16)
├── Redis Memorystore
├── Artifact Registry (coditect-docker)
└── Cloud KMS (Phase 2)
3.5 Inventory Update Workflow
┌─────────────────────────────────────────────────────────────────┐
│ Inventory Update Triggers │
├─────────────────────────────────────────────────────────────────┤
│ │
│ AUTOMATIC MANUAL │
│ ───────── ────── │
│ • New submodule added • Infrastructure changes │
│ • Dockerfile created/modified • GCP service additions │
│ • K8s manifest changes • Domain configuration │
│ • CI/CD pipeline updates • Architecture decisions │
│ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Update Inventory Document │ │
│ │ │ │
│ │ 1. Identify affected section(s) │ │
│ │ 2. Update tables/lists with new entries │ │
│ │ 3. Update version and timestamp │ │
│ │ 4. Verify cross-references │ │
│ │ 5. Commit with descriptive message │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
4. Consequences
4.1 Benefits
| Benefit | Impact |
|---|---|
| Single Source of Truth | Eliminates conflicting documentation about deployments |
| Faster Onboarding | New team members understand system scope immediately |
| Deployment Verification | Checklist-based verification for production releases |
| Disaster Recovery | Complete component list for rebuild scenarios |
| Audit Compliance | Evidence document for SOC 2, ISO 27001 audits |
| Dependency Visibility | Clear understanding of inter-component relationships |
4.2 Costs
| Cost | Mitigation |
|---|---|
| Manual Maintenance | Establish update triggers and review cadence |
| Staleness Risk | Add inventory verification to deployment checklist |
| Document Size | Use collapsible sections and linking |
4.3 Risks
| Risk | Probability | Impact | Mitigation |
|---|---|---|---|
| Inventory drift | Medium | High | Automated validation in CI/CD |
| Missing components | Low | Medium | Periodic full audit (monthly) |
| Incorrect relationships | Low | Medium | Dependency graph validation |
5. Implementation
5.1 Inventory Document Location
Primary: docs/internal/CODITECT-DEPLOYMENT-INVENTORY.md
Rationale: Located in rollout-master (the orchestration repo) rather than any single submodule, since it spans all repositories.
5.2 Required Sections
| Section | Content | Update Frequency |
|---|---|---|
| Production Domains | All public/internal endpoints | On domain changes |
| Repository Inventory | All 74 submodules by category | On submodule add/remove |
| GCP Projects | Project IDs, services, IAM | On infra changes |
| Docker Images | All images, registries, tags | On image creation |
| Kubernetes Resources | Namespaces, deployments, services | On K8s changes |
| OpenTofu Modules | All IaC modules | On infra changes |
| Cloud Run Services | All Cloud Run deployments | On service changes |
| Backend Components | API endpoints, models | On backend changes |
| CI/CD Pipelines | All GitHub Actions workflows | On workflow changes |
| Dependencies | Component relationship map | On architecture changes |
5.3 Validation Commands
# Verify submodule count matches inventory
git submodule status | wc -l # Should match documented count
# List all Dockerfiles
find . -name "Dockerfile*" -type f | wc -l
# List all K8s resources
kubectl get all --all-namespaces -o custom-columns=KIND:.kind,NAMESPACE:.metadata.namespace,NAME:.metadata.name
# List GCP services
gcloud services list --project coditect-cloud-infra --enabled
gcloud services list --project coditect-citus-prod --enabled
# List Artifact Registry images
gcloud artifacts docker images list us-central1-docker.pkg.dev/coditect-citus-prod/coditect-docker
6. Alternatives Considered
6.1 Automated Inventory Generation
Approach: Script that generates inventory from live infrastructure.
Rejected because:
- Cannot capture intent, purpose, and relationships
- Misses planned but not-yet-deployed components
- Cannot distinguish between active and deprecated resources
- Requires complex parsing of multiple APIs
6.2 Database-backed Inventory
Approach: Store inventory in SQLite or PostgreSQL.
Rejected because:
- Adds infrastructure complexity
- Harder to review in PRs
- Requires custom tooling for access
- Markdown provides sufficient structure with Git versioning
6.3 Spreadsheet-based Tracking
Approach: Use Google Sheets for inventory management.
Rejected because:
- Not version controlled
- Difficult to review changes
- No integration with deployment pipelines
- External dependency
7. Related Documents
| Document | Relationship |
|---|---|
| CODITECT-DEPLOYMENT-INVENTORY.md | Implementation of this ADR |
| ADR-053: Cloud Context Sync Architecture | Task tracking integration |
| ADR-054: Track Nomenclature Standard | Task ID format |
| PILOT-PARALLEL-EXECUTION-PLAN.md | Deployment tasks |
| GCP-INFRASTRUCTURE-INVENTORY.md | GCP-specific inventory |
8. Review and Updates
8.1 Review Cadence
| Review Type | Frequency | Reviewer |
|---|---|---|
| Quick verification | Per deployment | DevOps engineer |
| Section audit | Bi-weekly | Track owner |
| Full inventory audit | Monthly | Architect |
| Annual compliance review | Yearly | Security + Compliance |
8.2 Update Process
- Identify change - Infrastructure, repo, or service change detected
- Locate section - Find relevant section in inventory document
- Update content - Add, modify, or deprecate entry
- Update metadata - Version and timestamp in frontmatter
- Commit - Include task ID in commit message
- Verify - Run validation commands
9. Appendix
9.1 Inventory Document Template
---
title: CODITECT Deployment Inventory
type: reference
version: X.Y.Z
updated: 'YYYY-MM-DD'
status: active
---
# CODITECT Deployment Inventory
## 1. Production Domains & Endpoints
| Domain | Purpose | Service Type | Status |
|--------|---------|--------------|--------|
| ... | ... | ... | ... |
## 2. Repository Inventory
### 2.1 Core Repositories
| Repository | Path | Purpose | Pilot Required |
|------------|------|---------|----------------|
| ... | ... | ... | ... |
[Continue for all sections...]
9.2 Glossary
| Term | Definition |
|---|---|
| SSOT | Single Source of Truth |
| Submodule | Git submodule within rollout-master |
| Artifact Registry | GCP Docker image registry |
| GKE | Google Kubernetes Engine |
| OpenTofu | Open-source Terraform fork (MPL 2.0) |
Compliance: CODITECT ADR Standard v1.0.0
Co-Authored-By: Claude Opus 4.5 noreply@anthropic.com