CODITECT Directory Structure Standard

Purpose

This standard defines the canonical directory structure for all CODITECT projects, ensuring consistency, discoverability, and production readiness across all repositories.

Scope

Applies to:

• CODITECT master repository (coditect-rollout-master)
• All CODITECT submodules (74+ repositories)
• Customer projects using CODITECT framework
• New repositories created within the CODITECT ecosystem

---

1. Root Level Structure

1.1 Master/Orchestration Repository

<project-root>/
├── .claude/                    # Claude Code configuration (symlink to .coditect)
├── .coditect/                  # CODITECT framework (symlink to core)
├── .github/                    # GitHub configuration
│   ├── workflows/              # CI/CD pipelines
│   ├── ISSUE_TEMPLATE/         # Issue templates
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── CODEOWNERS
├── config/                     # Configuration files ONLY
├── docs/                       # User-facing documentation
├── scripts/                    # Automation scripts
├── submodules/                 # Git submodules (categorized)
├── .gitignore                  # Git ignore rules
├── .gitmodules                 # Submodule definitions
├── CLAUDE.md                   # AI agent context (REQUIRED)
├── LICENSE                     # License file
├── README.md                   # Project overview (REQUIRED)
└── [PROJECT-SPECIFIC].md       # e.g., WHAT-IS-CODITECT.md

1.2 Application Repository

<project-root>/
├── .claude/                    # Claude Code configuration
├── .coditect/                  # CODITECT framework (if using)
├── .github/                    # GitHub configuration
├── src/                        # Source code
│   ├── components/             # UI components (if frontend)
│   ├── services/               # Business logic
│   ├── utils/                  # Utilities
│   └── types/                  # Type definitions
├── tests/                      # Test files
│   ├── unit/
│   ├── integration/
│   └── e2e/
├── docs/                       # Documentation
├── scripts/                    # Build/automation scripts
├── config/                     # Configuration files
├── public/                     # Static assets (if frontend)
├── .gitignore
├── CLAUDE.md                   # AI agent context
├── LICENSE
├── README.md
├── package.json                # (Node.js projects)
├── Cargo.toml                  # (Rust projects)
└── pyproject.toml              # (Python projects)

1.3 Library/Package Repository

<project-root>/
├── .github/
├── src/                        # Library source
│   └── lib.rs / index.ts / __init__.py
├── tests/
├── examples/                   # Usage examples
├── docs/
├── benches/                    # Benchmarks (if applicable)
├── .gitignore
├── CLAUDE.md
├── LICENSE
├── README.md
├── CHANGELOG.md
└── [package manifest]

---

2. Documentation Structure (docs/)

2.1 Standard Documentation Hierarchy

docs/
├── README.md                   # Documentation index
├── getting-started/            # Onboarding
│   ├── README.md
│   ├── INSTALLATION.md
│   ├── QUICK-START.md
│   └── PREREQUISITES.md
├── guides/                     # How-to guides
│   ├── README.md
│   └── [GUIDE-NAME].md
├── reference/                  # API/component reference
│   ├── README.md
│   └── [REFERENCE-NAME].md
├── architecture/               # Architecture documentation
│   ├── README.md
│   ├── OVERVIEW.md
│   └── diagrams/
├── project-management/         # Planning (if applicable)
│   ├── README.md
│   ├── PROJECT-PLAN.md
│   ├── TASKLIST.md
│   └── checkpoints/
├── security/                   # Security documentation
│   └── README.md
└── archive/                    # Deprecated/old docs
    └── README.md

2.2 Internal vs External Documentation

Type	Location	Audience
User-facing	docs/	End users, customers
Contributor	internal/ or docs/contributing/	Developers
Architecture	docs/architecture/ or internal/architecture/	Technical team
ADRs	internal/architecture/adrs/	Architects, developers

---

3. Source Code Structure (src/)

3.1 Frontend (React/TypeScript)

src/
├── components/                 # React components
│   ├── common/                 # Shared components
│   ├── layout/                 # Layout components
│   └── features/               # Feature-specific components
├── hooks/                      # Custom React hooks
├── services/                   # API services
├── stores/                     # State management
├── types/                      # TypeScript types
├── utils/                      # Utility functions
├── styles/                     # Global styles
├── assets/                     # Static assets
├── App.tsx
└── index.tsx

3.2 Backend (Python/Django)

src/ or <app_name>/
├── api/                        # API endpoints
│   ├── v1/
│   └── v2/
├── models/                     # Database models
├── services/                   # Business logic
├── utils/                      # Utilities
├── middleware/                 # Custom middleware
├── tasks/                      # Background tasks
├── tests/                      # Tests (or separate tests/)
├── settings/                   # Configuration
│   ├── base.py
│   ├── development.py
│   └── production.py
├── manage.py
└── wsgi.py

3.3 Backend (Rust)

src/
├── api/                        # API handlers
├── models/                     # Data models
├── services/                   # Business logic
├── db/                         # Database layer
├── utils/                      # Utilities
├── config/                     # Configuration
├── error/                      # Error types
├── lib.rs                      # Library entry
└── main.rs                     # Binary entry

---

4. Scripts Structure (scripts/)

scripts/
├── README.md                   # Script documentation
├── core/                       # Core functionality
│   ├── __init__.py
│   └── [core-scripts].py
├── utils/                      # Utility scripts
├── deployment/                 # Deployment automation
│   ├── deploy.sh
│   └── rollback.sh
├── maintenance/                # Maintenance scripts
│   ├── backup.sh
│   └── cleanup.sh
├── ci/                         # CI/CD scripts
└── dev/                        # Development helpers

---

5. Submodule Structure (submodules/)

5.1 Category-Based Organization

submodules/
├── README.md                   # Submodule index
├── archives/                   # Archived/legacy projects
├── cloud/                      # Cloud infrastructure
│   ├── coditect-cloud-infra/
│   ├── coditect-cloud-frontend/
│   └── coditect-cloud-backend/
├── compliance/                 # Compliance & legal
├── core/                       # Core framework
│   └── coditect-core/
├── dev/                        # Development tools
├── docs/                       # Documentation repos
├── gtm/                        # Go-to-market
└── ops/                        # Operations

5.2 Submodule Naming Convention

Pattern: <organization>-<category>-<name>

Examples:

• coditect-cloud-infra
• coditect-core
• coditect-dev-generative-ui

---

6. Configuration Structure (config/)

config/
├── README.md
├── component-counts.json       # Component inventory
├── settings.json               # Default settings
├── settings.local.json         # Local overrides (gitignored)
├── settings.production.json    # Production settings
└── [feature-config].json       # Feature-specific config

---

7. Required Files

7.1 Every Repository MUST Have

File	Purpose
README.md	Project overview, setup instructions
LICENSE	License terms
.gitignore	Git ignore rules

7.2 CODITECT Repositories MUST Also Have

File	Purpose
CLAUDE.md	AI agent context
docs/README.md	Documentation index

7.3 Every Directory SHOULD Have

File	Purpose
README.md	Directory purpose and contents

---

8. Prohibited Items at Root

The following MUST NOT exist at project root:

Pattern	Reason	Action
*.log	Logs belong in logs/ or are transient	Delete or gitignore
*.tmp, *.bak	Temporary files	Delete or gitignore
CHECKPOINT-*.md	Checkpoints belong in docs/	Move to docs/project-management/checkpoints/
*.py (loose scripts)	Scripts belong in scripts/	Move to scripts/
Build artifacts	Should be gitignored	Delete and gitignore
node_modules/, venv/, .venv/	Dependencies	Gitignore
.env with secrets	Security risk	Gitignore, use Secret Manager

---

9. Depth Limits

Directory	Max Depth	Rationale
docs/	4 levels	Maintainability
src/	5 levels	Code organization
scripts/	3 levels	Discoverability
config/	2 levels	Simplicity
submodules/	2 levels (category/repo)	Git submodule limitation

---

10. Validation

10.1 Automated Validation

# Validate structure
/structure --validate

# Check compliance
python scripts/analyze-project-structure.py --check

10.2 Compliance Scoring

Score	Level	Requirements
90-100	Platinum	All standards met, automation enabled
80-89	Gold	All required files, 95% README coverage
70-79	Silver	Required files, 80% README coverage
60-69	Bronze	README at root, basic structure
<60	Non-compliant	Missing critical elements

---

11. Migration Guide

11.1 From Non-Compliant Structure

1. Audit current structure: /organize --analyze
2. Generate migration plan: /organize --plan
3. Create missing directories: Follow hierarchy above
4. Move files: Use git mv to preserve history
5. Generate READMEs: /readme-gen --recursive
6. Validate: /structure --validate

11.2 Common Migrations

From	To	Command
Loose docs at root	docs/	git mv *.md docs/
Scripts at root	scripts/	git mv *.py scripts/
Mixed config	config/	git mv *.json config/

---

References

• FILE-NAMING-CONVENTIONS.md - Naming rules
• README-STANDARD.md - README requirements
• PRODUCTION-READINESS-CHECKLIST.md - Production checklist

---

Version: 1.0.0 Status: Active Owner: CODITECT Core Team Last Updated: 2026-01-02