CODITECT Cloud Infrastructure - Project Structure

Production-Ready Directory Organization

Last Updated: November 23, 2025

📂 Directory Structure Overview

coditect-cloud-infra/
├── .coditect/                      # Symlink to distributed intelligence
├── .claude/                        # Symlink for Claude Code compatibility
├── .github/                        # GitHub Actions workflows
│   ├── workflows/
│   │   ├── tofu-plan.yml      # PR validation
│   │   └── tofu-apply.yml     # Deployment automation
│   └── ISSUE_TEMPLATE/
├── docs/                           # Comprehensive documentation
│   ├── README.md                   # Documentation index ⭐ START HERE
│   ├── architecture/               # C1-C3 architecture diagrams
│   │   ├── c1-system-context.md
│   │   └── c2-container-diagram.md
│   ├── workflows/                  # Sequence diagrams (5 files)
│   │   ├── user-registration-flow.md
│   │   ├── license-acquisition-workflow.md
│   │   ├── heartbeat-mechanism.md
│   │   ├── zombie-session-cleanup.md
│   │   └── graceful-license-release.md
│   ├── project-management/         # Project planning documents
│   │   └── checkpoints/
│   │       ├── P1-T01-COMPLETION-SUMMARY.md
│   │       ├── P1-T02-COMPLETION-SUMMARY.md
│   │       └── PHASE-0-COMPLETION-SUMMARY.md
│   ├── critical-path-analysis.md   # 6-7 day roadmap to MVP
│   ├── gap-analysis.md             # Current vs target state
│   ├── implementation-roadmap.md   # 5-phase development plan
│   ├── gcp-infrastructure-inventory.md  # Deployed resources
│   ├── gcp-setup.md                # Initial GCP configuration
│   ├── security-advisory-2025-11-23.md  # Security best practices
│   └── coditect-application-integration.md  # End-to-end system docs
├── diagrams/                       # Visual diagrams (future)
├── kubernetes/                     # Kubernetes manifests
│   ├── base/
│   ├── overlays/
│   │   ├── dev/
│   │   ├── staging/
│   │   └── prod/
│   └── helm/
├── opentofu/                       # Infrastructure as Code (OpenTofu/OpenTofu)
│   ├── modules/                    # Reusable OpenTofu modules
│   │   ├── networking/
│   │   ├── gke/
│   │   ├── database/
│   │   └── redis/
│   └── environments/               # Environment configurations
│       ├── dev/
│       ├── staging/
│       └── prod/
├── research/                       # Research documents and planning
├── scripts/                        # Utility scripts
│   ├── bootstrap.sh
│   ├── deploy.sh
│   ├── update_tasklist.py
│   └── teardown.sh
├── tests/                          # Infrastructure tests (Terratest)
├── .env.example                    # Environment variable template
├── .gitignore                      # Git ignore patterns
├── .gitmessage                     # Git commit message template
├── .pre-commit-config.yaml         # Pre-commit hooks
├── CLAUDE.md                       # AI agent configuration
├── CODE_OF_CONDUCT.md              # Community guidelines
├── CODEOWNERS                      # GitHub code ownership
├── CONTRIBUTING.md                 # Contribution guidelines
├── docker-compose.yml              # Local development environment
├── Dockerfile                      # Container image definition
├── LICENSE                         # License file
├── project-plan.md                 # 59KB comprehensive project plan
├── pyproject.toml                  # Python project configuration
├── README.md                       # Project overview
├── requirements.txt                # Python dependencies
├── requirements-dev.txt            # Development dependencies
├── tasklist.md                     # Simplified task tracking
└── tasklist-with-checkboxes.md    # Detailed progress tracking (91KB)

📋 File Categories

Root Configuration Files

File	Purpose	Update Frequency
`.env.example`	Environment variable template	As needed
`.gitignore`	Git ignore patterns	Rarely
`.gitmessage`	Commit message template	Rarely
`.pre-commit-config.yaml`	Pre-commit hooks configuration	Monthly
`docker-compose.yml`	Local development stack	As needed
`Dockerfile`	Container image build	As needed
`pyproject.toml`	Python project metadata	As needed
`requirements.txt`	Production dependencies	Weekly
`requirements-dev.txt`	Development dependencies	Weekly

Project Management Files

File	Purpose	Size	Update Frequency
`project-plan.md`	Complete project plan & roadmap	59KB	Weekly
`tasklist.md`	Simplified task list	9KB	Daily
`tasklist-with-checkboxes.md`	Detailed progress tracking	91KB	Daily
`README.md`	Project overview	9KB	As needed

Documentation Files

Located in docs/ directory (see below)

Community & Legal

File	Purpose
`LICENSE`	Software license
`CODE_OF_CONDUCT.md`	Community guidelines
`CONTRIBUTING.md`	Contribution process
`CODEOWNERS`	GitHub code ownership

📖 Documentation Structure

Primary Entry Point

docs/README.md - Complete documentation index

Quick status overview
Documentation navigation
Getting started guides
Cross-reference table

Architecture Documentation

Level 1: System Context

docs/architecture/c1-system-context.md - System boundaries and actors

Level 2: Container Architecture

docs/architecture/c2-container-diagram.md - All containers and technology stack

Level 3: Component Diagrams (Planned)

License API components
Admin dashboard components
Database schema

Workflow Documentation

Complete end-to-end flows with code examples:

user-registration-flow.md
- Google/GitHub OAuth integration
- Tenant and license creation
- Email verification
license-acquisition-workflow.md
- Check-on-start pattern
- Hardware fingerprinting
- License signing (Cloud KMS)
heartbeat-mechanism.md
- Background thread implementation
- TTL management (5min/6min)
- Offline mode with grace period
zombie-session-cleanup.md
- Redis keyspace notifications
- Automatic seat reclamation
- Cleanup worker implementation
graceful-license-release.md
- Signal handlers (SIGINT, SIGTERM)
- Shutdown sequence
- Immediate seat reclaim

Planning Documents

Document	Purpose	Size
critical-path-analysis.md	6-7 day roadmap to MVP	Comprehensive
gap-analysis.md	Current vs target state	Detailed
implementation-roadmap.md	5-phase development plan	Detailed

Infrastructure Documents

Document	Purpose
gcp-infrastructure-inventory.md	All deployed GCP resources
gcp-setup.md	Initial GCP project setup
security-advisory-2025-11-23.md	Security best practices

Integration Documents

Document	Purpose
coditect-application-integration.md	Complete end-to-end system architecture

🏗️ Infrastructure as Code Structure

OpenTofu/OpenTofu Modules

opentofu/
├── modules/                    # Reusable modules
│   ├── networking/
│   │   ├── main.tf            # VPC, subnets, firewall
│   │   ├── variables.tf       # Input variables
│   │   └── outputs.tf         # Output values
│   ├── gke/
│   │   ├── main.tf            # GKE cluster configuration
│   │   ├── node_pools.tf      # Node pool definitions
│   │   └── addons.tf          # GKE addons
│   ├── database/
│   │   ├── main.tf            # Cloud SQL instance
│   │   └── users.tf           # Database users
│   └── redis/
│       └── main.tf            # Memorystore Redis
└── environments/              # Environment-specific configs
    ├── dev/
    │   ├── main.tf           # Dev environment
    │   ├── backend.tf        # State backend config
    │   └── tofu.tfvars  # Variable values
    ├── staging/
    └── prod/

Kubernetes Manifests

kubernetes/
├── base/                      # Base configurations
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   └── configmap.yaml
├── overlays/                  # Kustomize overlays
│   ├── dev/
│   │   └── kustomization.yaml
│   ├── staging/
│   └── prod/
└── helm/                      # Helm chart values
    ├── values-dev.yaml
    ├── values-staging.yaml
    └── values-prod.yaml

🔧 Scripts Directory

Script	Purpose
`bootstrap.sh`	Initial project setup
`deploy.sh`	Deployment automation
`teardown.sh`	Infrastructure cleanup
`update_tasklist.py`	Task list synchronization

🧪 Tests Directory

Infrastructure testing (Terratest):

tests/
├── networking_test.go
├── gke_test.go
├── database_test.go
└── redis_test.go

📊 Project Status

Current Completion

Component	Status	Completion
Infrastructure	✅ Deployed	100%
Documentation	✅ Complete	95%
Backend Application	❌ Pending	0%
Deployment	❌ Pending	0%
Client SDK	❌ Pending	0%
Overall	🔄 In Progress	35%

Next Milestones

This Week: Cloud KMS + Identity Platform (2-3 days)
Next Week: Backend development (5-7 days)
Week After: Deployment to GKE (2-3 days)
Target MVP: December 6, 2025

🎯 Directory Organization Guidelines

Keeping the Root Clean

Files that MUST stay in root:

Configuration files (.env.example, pyproject.toml, docker-compose.yml)
Documentation entry points (README.md, project-plan.md, tasklist.md)
License and community files (LICENSE, CODE_OF_CONDUCT.md, CONTRIBUTING.md)

Files that should be in subdirectories:

Architecture diagrams → docs/architecture/
Workflow diagrams → docs/workflows/
Planning documents → docs/project-management/
Completion summaries → docs/project-management/checkpoints/
Utility scripts → scripts/
Infrastructure code → opentofu/ or kubernetes/
Tests → tests/

Naming Conventions

Files:

Use UPPERCASE-WITH-DASHES.md for top-level documents
Use lowercase-with-dashes.md for subdirectory documents
Use descriptive names (not generic like doc1.md)

Directories:

Use lowercase with dashes or underscores
Be specific: project-management not docs/misc
Group related files logically

📞 Support

Questions? See docs/README.md for complete documentation index

Contributing? Read CONTRIBUTING.md for guidelines

Last Updated: November 23, 2025 Status: Production-Ready Organization Owner: AZ1.AI INC

📂 Directory Structure Overview​

📋 File Categories​

Root Configuration Files​

Project Management Files​

Documentation Files​

Community & Legal​

📖 Documentation Structure​

Primary Entry Point​

Architecture Documentation​

Workflow Documentation​

Planning Documents​

Infrastructure Documents​

Integration Documents​

🏗️ Infrastructure as Code Structure​

OpenTofu/OpenTofu Modules​

Kubernetes Manifests​

🔧 Scripts Directory​

🧪 Tests Directory​

📊 Project Status​

Current Completion​

Next Milestones​

🎯 Directory Organization Guidelines​

Keeping the Root Clean​

Naming Conventions​

📞 Support​