Production Folder Organization Guide

Standard directory structures for production-ready CODITECT projects.

---

Prerequisites

Before organizing your project structure, ensure you have:

• Project repository initialized - Git repository with .git directory
• CODITECT framework linked - .coditect symlink to coditect-core
• Basic project plan - Understanding of project type (backend/frontend/monorepo)
• Write permissions - Ability to create directories and files

Verify your setup:

git status          # Verify git repository
ls -la .coditect    # Verify CODITECT link

---

Quick Start

Set up production folder structure in 5 minutes:

Step 1: Identify Your Project Type

Determine which structure applies:

• Backend - API, services, databases
• Frontend - React/Vue/Svelte applications
• Monorepo - Multi-package repositories

Step 2: Create Base Structure

# Create essential directories
mkdir -p docs/{getting-started,guides,reference}
mkdir -p internal/{architecture,project}
mkdir -p scripts config

# Create required files
touch CLAUDE.md README.md .gitignore

Step 3: Link CODITECT Framework

# Link to coditect-core (adjust path as needed)
ln -s ../coditect-core .coditect
ln -s .coditect .claude

# Verify
ls -la .coditect .claude

---

Universal Project Structure

All CODITECT projects follow this base structure:

project-root/
├── .coditect/              # CODITECT framework link
├── .claude/                # Claude Code compatibility (symlink to .coditect)
├── CLAUDE.md               # AI agent instructions
├── README.md               # Project documentation
├── LICENSE                 # License file
├── .gitignore              # Git ignore patterns
├── docs/                   # Documentation
├── scripts/                # Automation scripts
├── config/                 # Configuration files
└── internal/               # Internal/contributor docs

---

Backend Project Structure

For Python/Node.js/Rust backend services:

backend-project/
├── .coditect/ → coditect-core
├── CLAUDE.md
├── README.md
├── src/                    # Source code
│   ├── api/                # API endpoints
│   ├── services/           # Business logic
│   ├── repositories/       # Data access
│   ├── models/             # Data models
│   ├── middleware/         # HTTP middleware
│   └── utils/              # Utilities
├── tests/                  # Test files
│   ├── unit/
│   ├── integration/
│   └── fixtures/
├── config/                 # Configuration
│   ├── default.json
│   ├── development.json
│   └── production.json
├── scripts/                # Automation
├── docs/                   # Documentation
│   ├── api/                # API documentation
│   └── guides/             # Usage guides
├── internal/               # Internal docs
│   └── architecture/       # ADRs, design docs
├── migrations/             # Database migrations
├── .env.example            # Environment template
├── Dockerfile              # Container definition
├── docker-compose.yml      # Local development
├── requirements.txt        # Python deps
└── package.json            # Node.js deps

See: CODITECT-STANDARD-PRODUCTION-FOLDERS-BACKEND.md

---

Frontend Project Structure

For React/Vue/Svelte applications:

frontend-project/
├── .coditect/ → coditect-core
├── CLAUDE.md
├── README.md
├── src/
│   ├── components/         # UI components
│   │   ├── common/         # Shared components
│   │   ├── layout/         # Layout components
│   │   └── features/       # Feature components
│   ├── pages/              # Page components
│   ├── hooks/              # Custom hooks
│   ├── services/           # API services
│   ├── store/              # State management
│   ├── utils/              # Utilities
│   ├── types/              # TypeScript types
│   └── styles/             # Global styles
├── public/                 # Static assets
├── tests/                  # Test files
├── config/                 # Build configuration
├── docs/                   # Documentation
├── .env.example
├── package.json
├── tsconfig.json
├── vite.config.ts
└── Dockerfile

See: CODITECT-STANDARD-PRODUCTION-FOLDERS-FRONTEND.md

---

Monorepo Structure

For multi-package repositories:

monorepo/
├── .coditect/ → coditect-core
├── CLAUDE.md
├── README.md
├── packages/               # Shared packages
│   ├── shared/             # Shared utilities
│   ├── ui-components/      # Component library
│   └── api-client/         # API client
├── apps/                   # Applications
│   ├── web/                # Web application
│   ├── api/                # API server
│   └── worker/             # Background worker
├── tools/                  # Build tools
├── config/                 # Shared config
├── docs/                   # Documentation
├── internal/               # Internal docs
├── scripts/                # Automation
├── package.json            # Root package
├── pnpm-workspace.yaml     # Workspace config
└── turbo.json              # Turbo config

See: CODITECT-STANDARD-PRODUCTION-FOLDERS-MONOREPO.md

---

Documentation Structure

Standard documentation organization:

docs/
├── getting-started/        # Onboarding docs
│   ├── QUICK-START.md
│   └── INSTALLATION.md
├── guides/                 # User guides
│   ├── USAGE-GUIDE.md
│   └── BEST-PRACTICES.md
├── reference/              # Technical reference
│   ├── API-REFERENCE.md
│   └── ARCHITECTURE.md
├── training/               # Training materials
└── workflows/              # Workflow definitions

---

Internal Documentation

Contributor-focused documentation:

internal/
├── architecture/           # Architecture docs
│   ├── adrs/               # Decision records
│   ├── c4-diagrams/        # C4 diagrams
│   ├── system-design/      # SDDs, TDDs
│   └── README.md
├── deployment/             # Deployment docs
├── project/                # Project management
│   ├── plans/
│   ├── sprints/
│   └── status/
├── research/               # Research notes
└── testing/                # Test documentation

---

Key File Requirements

Required Files

File	Purpose	Template
CLAUDE.md	AI agent instructions	Required
README.md	Project documentation	Required
.gitignore	Git ignore patterns	Required
LICENSE	License file	Required for public

Recommended Files

File	Purpose
.env.example	Environment template
Dockerfile	Container definition
docker-compose.yml	Local development
Makefile	Common commands

---

Symlink Setup

Connect your project to CODITECT framework:

# From project root (if coditect-core is a sibling)
ln -s ../coditect-core .coditect
ln -s .coditect .claude

# Or if coditect-core is in a known location
ln -s /path/to/coditect-core .coditect
ln -s .coditect .claude

Verify setup:

ls -la .coditect .claude
# Should show symlinks pointing to coditect-core

---

Directory Naming Conventions

Convention	Example	Use For
lowercase	components/	Most directories
kebab-case	api-client/	Multi-word directories
UPPERCASE	TEMPLATES/	Important reference dirs
Numbered	01-getting-started/	Ordered content

---

Anti-Patterns to Avoid

1. Don't mix customer and internal docs - Keep docs/ and internal/ separate
2. Don't nest too deeply - Max 4 levels recommended
3. Don't duplicate config - Use environment-specific overrides
4. Don't commit secrets - Use .env files and .gitignore
5. Don't mix concerns - Keep src/ for code only

---

Related Standards

• CODITECT-STANDARD-PRODUCTION-FOLDERS-UNIVERSAL.md
• CODITECT-STANDARD-DOCUMENTATION.md
• project-organizer agent

---

Troubleshooting

Common Organization Issues

Symlink not working:

# Check if target exists
ls -la ../coditect-core

# Use absolute path instead
ln -sf /absolute/path/to/coditect-core .coditect
ln -sf .coditect .claude

Missing required files:

# Generate missing structure
python3 scripts/generate-missing-folders.py . --type PROJECT_TYPE

# Validate result
python3 scripts/validate-folder-organization.py . --type PROJECT_TYPE

Score below target:

# Run gap analysis
python3 scripts/folder-gap-analysis.py . --type PROJECT_TYPE --output gaps.json

# Generate missing items
python3 scripts/generate-missing-folders.py . --gaps-file gaps.json

# Re-validate
python3 scripts/calculate-folder-score.py . --type PROJECT_TYPE

Permission denied:

# Check ownership
ls -la

# Fix permissions if needed
chmod +w . && chmod +w docs/ internal/

---

Next Steps

After organizing your project:

1. Validate structure - Run python3 scripts/validate-folder-organization.py .
2. Set up CI/CD - Add structure validation to your pipeline
3. Configure CLAUDE.md - Customize AI agent instructions for your project
4. Add documentation - Populate docs/ with project-specific guides
5. Review best practices - USER-BEST-PRACTICES.md

---

Last Updated: 2025-12-22 Owner: AZ1.AI INC