Skip to main content

CODITECT Production Folder Standard - Universal (All Projects)

Version: 1.0.0 Last Updated: 2025-12-04 Applies To: ALL CODITECT projects (Frontend, Backend, Monorepo, Tools, Libraries) Status: Production Standard

Overview​

This standard defines the universal folder structure requirements that apply to ALL CODITECT projects, regardless of type. Every project MUST follow this standard in addition to its project-type-specific standard (Frontend/Backend/Monorepo).

Key Principles:

  • Clean root directory - Only essential files at top level
  • Documentation hierarchy - Organized by category, not chronology
  • Standard file names - Consistent across all projects
  • Git-friendly - Comprehensive .gitignore
  • Production-ready - All essential documentation present

Required Root Documentation Files​

✅ Every Project MUST Have​

project-root/
├── README.md                    # User documentation (REQUIRED)
├── CLAUDE.md                    # AI agent context (REQUIRED)
├── CONTRIBUTING.md              # Contribution guidelines (REQUIRED)
├── CHANGELOG.md                 # Version history (REQUIRED)
├── LICENSE                      # License file (REQUIRED)
├── SECURITY.md                  # Security policy (REQUIRED)
└── .gitignore                   # Git ignore rules (REQUIRED)

README.md Template​

# Project Name

[Brief description]

## Quick Start
## Features
## Installation
## Usage
## Documentation
## Contributing
## License

Minimum: 50 lines, Quick Start section mandatory

CLAUDE.md Template​

# CLAUDE.md - Project Name

## Project Overview
## Current Status
## Essential Documentation
## Directory Structure
## Development Workflow
## AI Agent Guidance

Minimum: 100 lines, must include project status and essential doc links

CONTRIBUTING.md​

# Contributing

## Development Workflow
## Code Standards
## Testing Requirements
## Pull Request Process
## Code Review Guidelines

Minimum: 80 lines

CHANGELOG.md​

# Changelog

## [Unreleased]
## [1.0.0] - 2025-12-04
### Added
### Changed
### Fixed

Format: Keep a Changelog standard

LICENSE​

Use: CODITECT proprietary template from CODITECT-CORE-STANDARDS/TEMPLATES/LICENSE-TEMPLATE

SECURITY.md​

# Security Policy

## Supported Versions
## Reporting a Vulnerability
## Security Best Practices

Minimum: 60 lines, must include vulnerability reporting process

Universal Documentation Hierarchy​

docs/ Directory (REQUIRED)​

docs/
├── api/                         # API documentation (if applicable)
│   ├── endpoints.md
│   ├── authentication.md
│   └── examples.md
│
├── architecture/                # Architecture documentation (REQUIRED)
│   ├── adrs/                    # Architecture Decision Records
│   │   ├── README.md
│   │   ├── ADR-001-*.md
│   │   ├── ADR-002-*.md
│   │   └── template.md
│   ├── C4-context.md            # C4 Level 1
│   ├── C4-container.md          # C4 Level 2
│   ├── C4-component.md          # C4 Level 3
│   ├── SOFTWARE-DESIGN-DOCUMENT.md
│   └── database-schema.md       # If applicable
│
├── deployment/                  # Deployment guides (REQUIRED)
│   ├── docker.md
│   ├── local-development.md
│   ├── production.md
│   ├── ci-cd.md
│   └── troubleshooting.md
│
├── diagrams/                    # Architecture diagrams
│   ├── dataflow-diagrams.md
│   ├── sequence-diagrams.md
│   └── workflow-diagrams.md
│
├── project-management/          # Project planning (REQUIRED)
│   ├── PROJECT-PLAN.md          # Master project plan
│   ├── TASKLIST-WITH-CHECKBOXES.md
│   ├── IMPLEMENTATION-ROADMAP.md
│   └── checkpoints/             # Session checkpoints
│       ├── 2025-12-04-checkpoint.md
│       └── README.md
│
├── testing/                     # Testing documentation
│   ├── TEST-DRIVEN-DEVELOPMENT.md
│   ├── test-strategy.md
│   └── test-coverage-report.md
│
└── user-guides/                 # User documentation
    ├── getting-started.md
    ├── tutorials/
    └── faq.md

Scripts Organization (REQUIRED)​

scripts/
├── build.sh                     # Production build
├── test-all.sh                  # Run all tests
├── start-dev.sh                 # Start development server
├── deploy.sh                    # Deploy to production
├── lint.sh                      # Run linters
└── clean.sh                     # Clean build artifacts

Requirements:

  • All scripts executable (chmod +x)
  • All scripts have usage comments
  • All scripts exit on error (set -e)
  • All scripts have description header

Examples Organization​

examples/
├── basic-usage/                 # Simple examples
│   ├── example-1/
│   │   ├── README.md
│   │   └── [files]
│   └── example-2/
├── advanced-patterns/           # Advanced examples
│   └── pattern-1/
└── README.md                    # Examples index

Tests Organization​

tests/
├── unit/                        # Unit tests
├── integration/                 # Integration tests
├── e2e/                         # End-to-end tests
├── fixtures/                    # Test fixtures
├── mocks/                       # Mock objects
└── conftest.py / setup.js       # Test configuration

OR (for frontend with colocation):

src/
└── components/
    └── Button/
        ├── Button.tsx
        └── Button.test.tsx      # Co-located

Build Artifacts (MUST be Gitignored)​

dist/                            # Build output
build/                           # Build output
out/                             # Build output
.next/                           # Next.js output
target/                          # Rust output
__pycache__/                     # Python bytecode
*.pyc                            # Python compiled
node_modules/                    # Dependencies
coverage/                        # Coverage reports
.pytest_cache/                   # Pytest cache
.mypy_cache/                     # Type check cache
.cache/                          # General cache
.turbo/                          # Turborepo cache
*.log                            # Log files
.env                             # Local environment (secrets)
.DS_Store                        # macOS files

Configuration Files (Root Only)​

Version Control​

.gitignore                       # REQUIRED - comprehensive
.gitattributes                   # Line ending handling

Code Quality​

.eslintrc.js                     # ESLint (JavaScript/TypeScript)
.prettierrc                      # Prettier (formatting)
.editorconfig                    # Editor consistency
pylint.rc                        # Pylint (Python)
.flake8                          # Flake8 (Python)
rustfmt.toml                     # Rustfmt (Rust)
clippy.toml                      # Clippy (Rust)

Environment​

.env.example                     # Environment template (REQUIRED)
.env.development                 # Dev environment (gitignored)
.env.test                        # Test environment (gitignored)
.env.production                  # Production (gitignored, NEVER commit)

Testing​

pytest.ini                       # Pytest config (Python)
vitest.config.ts                 # Vitest config (JavaScript)
jest.config.js                   # Jest config (JavaScript)
playwright.config.ts             # Playwright config (E2E)
.coveragerc                      # Coverage config

Build Tools​

package.json                     # Node.js dependencies
package-lock.json                # Locked versions
tsconfig.json                    # TypeScript config
requirements.txt                 # Python dependencies
Cargo.toml                       # Rust dependencies
Makefile                         # Build automation

Root Directory Organization Rules​

✅ ALLOWED in Root​

✅ Documentation (README, CLAUDE, CONTRIBUTING, CHANGELOG, LICENSE, SECURITY)
✅ Configuration files (.gitignore, .eslintrc, package.json, etc.)
✅ Build configuration (vite.config.ts, webpack.config.js, etc.)
✅ Environment templates (.env.example)
✅ Docker files (Dockerfile, docker-compose.yml)
✅ CI/CD configuration (.github/, .gitlab-ci.yml)
✅ Entry points (index.html, main.py, src/main.rs)

❌ NOT ALLOWED in Root​

❌ Source code files (*.tsx, *.py, *.rs) - belongs in src/
❌ Component files (Button.tsx) - belongs in src/components/
❌ Test files (*.test.ts) - belongs in tests/ or co-located
❌ Documentation beyond the 6 required files
❌ Research documents (RESEARCH-*.md) - belongs in docs/
❌ Session exports (EXPORT-*.txt) - belongs in docs/project-management/checkpoints/
❌ Analysis documents (ANALYSIS-*.md) - belongs in docs/
❌ Implementation plans (PLAN-*.md) - belongs in docs/project-management/
❌ Build artifacts (dist/, __pycache__/) - should be gitignored
❌ Temporary files (*.tmp, *.bak, *.swp)

Maximum Root Items​

Guideline: Maximum 25 items in root directory (excluding directories)

File Naming Conventions​

Documentation Files​

README.md                        # Not readme.md or Readme.md
CLAUDE.md                        # Not claude.md or Claude.md
CONTRIBUTING.md                  # Not Contributing.md
CHANGELOG.md                     # Not ChangeLog.md
LICENSE                          # Not License or LICENSE.txt
SECURITY.md                      # Not Security.md

Architecture Decision Records​

docs/architecture/adrs/
├── ADR-001-database-choice.md   # Not adr-001 or 001-database
├── ADR-002-api-framework.md
└── ADR-003-auth-strategy.md

Format: ADR-NNN-kebab-case-title.md

Checkpoints​

docs/project-management/checkpoints/
├── 2025-12-04-sprint-1-complete.md
├── 2025-12-11-sprint-2-complete.md
└── README.md

Format: YYYY-MM-DD-description.md

Project Type Detection​

How to determine which specific standard applies:

  1. Check for workspace config → Monorepo

    • pnpm-workspace.yaml, nx.json, turbo.json, lerna.json

  2. Check for frontend indicators → Frontend

    • src/components/, app/, public/
    • React/Vue/Svelte dependencies
    • index.html, next.config.js, vite.config.ts

  3. Check for backend indicators → Backend

    • src/routes/, src/api/, src/handlers/
    • src/models/, database migrations
    • FastAPI, Express, Django dependencies

  4. Default → Apply Universal standard only

Production Readiness Checklist (Universal)​

Documentation (30 points)​

  • 5 pts: README.md present and comprehensive (>50 lines)
  • 5 pts: CLAUDE.md present and detailed (>100 lines)
  • 5 pts: CONTRIBUTING.md present
  • 5 pts: CHANGELOG.md present with version history
  • 5 pts: LICENSE present (CODITECT template)
  • 5 pts: SECURITY.md present

Documentation Hierarchy (30 points)​

  • 5 pts: docs/ directory exists
  • 5 pts: docs/architecture/ with ADRs
  • 5 pts: docs/deployment/ with guides
  • 5 pts: docs/project-management/ with PROJECT-PLAN and TASKLIST
  • 5 pts: docs/testing/ with test documentation
  • 5 pts: docs/user-guides/ for users

Scripts & Infrastructure (20 points)​

  • 5 pts: scripts/ directory with production scripts
  • 5 pts: All scripts executable and documented
  • 5 pts: examples/ directory with usage examples
  • 5 pts: tests/ directory or co-located tests

Configuration (20 points)​

  • 5 pts: .gitignore comprehensive and correct
  • 5 pts: .env.example present
  • 5 pts: Code quality tools configured
  • 5 pts: Build tools configured

Total Score: 100 points Production Ready: 90+ points Needs Improvement: 70-89 points Not Ready: <70 points

Migration Guide​

To bring existing project to universal standard:

  1. Create required docs - README, CLAUDE, CONTRIBUTING, CHANGELOG, LICENSE, SECURITY
  2. Create docs/ hierarchy - architecture/, deployment/, project-management/, testing/, user-guides/
  3. Move misplaced files - Use git mv to preserve history
  4. Create scripts/ - Extract build/test/deploy scripts
  5. Update .gitignore - Comprehensive build artifact exclusion
  6. Clean root - Move non-essential files to proper subdirectories
  7. Verify - Run /organize-production to validate

Anti-Patterns to Avoid​

❌ Common Mistakes​

❌ Cluttered root directory (50+ files)
❌ Missing required documentation files
❌ Documentation scattered without hierarchy
❌ Session exports and research docs in root
❌ No CLAUDE.md for AI agent context
❌ Incomplete .gitignore (build artifacts committed)
❌ No PROJECT-PLAN.md or TASKLIST.md
❌ ADRs missing or not in docs/architecture/adrs/
❌ No scripts/ directory
❌ Configuration files scattered

✅ Best Practices​

✅ Clean root (<25 items)
✅ All 6 required docs present and complete
✅ Clear docs/ hierarchy by category
✅ Checkpoints in docs/project-management/checkpoints/
✅ Comprehensive CLAUDE.md (>100 lines)
✅ Complete .gitignore
✅ PROJECT-PLAN.md and TASKLIST.md with checkbox tracking
✅ ADRs numbered and in docs/architecture/adrs/
✅ scripts/ directory with all operational scripts
✅ Configuration organized at root level

Relationship to Other Standards​

This Universal standard is the BASE for all projects:

Universal Standard (this document)
    ├── Frontend Standard (extends Universal)
    ├── Backend Standard (extends Universal)
    └── Monorepo Standard (extends Universal)

Every project MUST:

  1. Follow Universal standard completely
  2. THEN apply project-type-specific standard

Validation​

To validate compliance:

# Run validation command
/organize-production --validate

# Or use script
python3 scripts/organize_production.py --validate

# Or use skill
# AI agent will use production-folder-structure skill

References​

Status: Production Standard ✅ Version: 1.0.0 Last Updated: 2025-12-04 Applies To: ALL CODITECT projects