CODITECT Production Folder Standard - Backend Projects
Version: 1.0.0 Last Updated: 2025-12-04 Applies To: Node.js, Python (FastAPI/Django), Rust backend API projects Status: Production Standard
Overview
This standard defines the production-ready folder structure for backend API services. It applies to REST APIs, GraphQL servers, microservices, and backend-for-frontend (BFF) applications.
Key Principles:
- Domain-driven organization - Group by business capability
- Layered architecture - Controllers → Services → Models
- Separation of concerns - Clear boundaries between layers
- Database-centric - Models, migrations, schemas explicit
- API-first - Routes and handlers are primary structure
Required Root Directory Structure
✅ Must Have in Root
project-root/
├── README.md # User documentation
├── CLAUDE.md # AI agent context
├── CONTRIBUTING.md # Contribution guidelines
├── CHANGELOG.md # Version history
├── LICENSE # License file
├── SECURITY.md # Security policy
├── requirements.txt # Python dependencies
├── package.json # Node.js dependencies
├── Cargo.toml # Rust dependencies
├── pyproject.toml # Python project config
├── .env.example # Environment template
├── .gitignore # Git ignore rules
├── Dockerfile # Docker container
├── docker-compose.yml # Local development
└── alembic.ini # Database migrations config
Must NOT Have in Root
❌ Source code files (*.py, *.js, *.rs)
❌ Database models (models.py, schemas.py)
❌ Route handlers (routes.py, controllers.js)
❌ Test files (*test.py, *spec.js)
❌ Migration files (0001_initial.py)
❌ Session exports (EXPORT-*.txt)
❌ Research documents (RESEARCH-*.md)
❌ Build artifacts (__pycache__/, target/)
❌ Temporary files (*.tmp, *.pyc)
Source Code Organization
Option 1: Python FastAPI (Domain-Driven)
src/
├── auth/ # Authentication domain
│ ├── __init__.py
│ ├── router.py # API endpoints
│ ├── controller.py # Request handlers
│ ├── service.py # Business logic
│ ├── models.py # Database models (SQLAlchemy)
│ ├── schemas.py # Request/response models (Pydantic)
│ ├── dependencies.py # Dependency injection
│ └── exceptions.py # Domain exceptions
├── users/ # User management domain
│ ├── __init__.py
│ ├── router.py
│ ├── service.py
│ ├── models.py
│ ├── schemas.py
│ └── repository.py # Database access layer
├── posts/ # Posts domain
│ └── ...
├── shared/ # Shared modules
│ ├── __init__.py
│ ├── middleware/ # Request/response middleware
│ │ ├── auth.py
│ │ ├── logging.py
│ │ └── error_handler.py
│ ├── database/ # Database connection
│ │ ├── __init__.py
│ │ ├── base.py # Base model
│ │ ├── session.py # Session management
│ │ └── connection.py # Connection pooling
│ ├── config/ # Configuration
│ │ ├── __init__.py
│ │ ├── settings.py # Environment settings
│ │ └── logging.py # Logging config
│ ├── utils/ # Utility functions
│ │ ├── __init__.py
│ │ ├── validators.py
│ │ └── formatters.py
│ └── exceptions/ # Global exceptions
│ ├── __init__.py
│ ├── base.py
│ └── http.py
├── main.py # Application entry point
└── __init__.py
migrations/ # Database migrations (Alembic)
├── versions/
│ ├── 0001_initial.py
│ └── 0002_add_users.py
├── env.py
└── script.py.mako
jobs/ # Background jobs (Celery)
├── __init__.py
├── celery_app.py # Celery configuration
├── tasks/
│ ├── email.py
│ └── notifications.py
└── schedules/
└── periodic.py
workers/ # Worker processes
├── __init__.py
├── email_worker.py
└── notification_worker.py
Option 2: Node.js Express (Layered Architecture)
src/
├── modules/ # Feature modules
│ ├── auth/
│ │ ├── auth.controller.ts # Request handlers
│ │ ├── auth.service.ts # Business logic
│ │ ├── auth.routes.ts # Route definitions
│ │ ├── auth.model.ts # Database model (Prisma/TypeORM)
│ │ ├── auth.dto.ts # Data transfer objects
│ │ ├── auth.middleware.ts # Auth-specific middleware
│ │ └── index.ts # Barrel export
│ ├── users/
│ │ ├── users.controller.ts
│ │ ├── users.service.ts
│ │ ├── users.repository.ts # Database access
│ │ ├── users.routes.ts
│ │ ├── users.model.ts
│ │ ├── users.dto.ts
│ │ └── index.ts
│ └── posts/
│ └── ...
├── shared/ # Shared modules
│ ├── middleware/ # Global middleware
│ │ ├── auth.middleware.ts
│ │ ├── error.middleware.ts
│ │ ├── logging.middleware.ts
│ │ └── validation.middleware.ts
│ ├── database/ # Database setup
│ │ ├── database.ts # Connection
│ │ ├── migrations/ # Migration files
│ │ └── seeds/ # Seed data
│ ├── config/ # Configuration
│ │ ├── env.ts # Environment variables
│ │ ├── database.ts # DB config
│ │ └── server.ts # Server config
│ ├── utils/ # Utilities
│ │ ├── validators.ts
│ │ ├── transformers.ts
│ │ └── helpers.ts
│ ├── types/ # Shared TypeScript types
│ │ ├── express.d.ts
│ │ └── models.ts
│ └── exceptions/ # Custom exceptions
│ ├── base.exception.ts
│ └── http.exception.ts
├── app.ts # Express app setup
└── server.ts # Server entry point
jobs/ # Background jobs (Bull)
├── queues/
│ ├── email.queue.ts
│ └── notification.queue.ts
├── workers/
│ ├── email.worker.ts
│ └── notification.worker.ts
└── index.ts
scripts/ # Utility scripts
├── migrate.ts # Run migrations
├── seed.ts # Seed database
└── generate-types.ts # Generate TypeScript types
Option 3: Rust Actix-Web (Module-Based)
src/
├── modules/ # Feature modules
│ ├── auth/
│ │ ├── mod.rs # Module root
│ │ ├── handlers.rs # HTTP handlers
│ │ ├── service.rs # Business logic
│ │ ├── models.rs # Database models
│ │ ├── dto.rs # Data transfer objects
│ │ ├── routes.rs # Route configuration
│ │ └── repository.rs # Database access
│ ├── users/
│ │ ├── mod.rs
│ │ ├── handlers.rs
│ │ ├── service.rs
│ │ ├── models.rs
│ │ ├── dto.rs
│ │ └── repository.rs
│ └── posts/
│ └── ...
├── shared/ # Shared modules
│ ├── mod.rs
│ ├── middleware/ # Actix middleware
│ │ ├── mod.rs
│ │ ├── auth.rs
│ │ ├── logging.rs
│ │ └── error.rs
│ ├── database/ # Database connection
│ │ ├── mod.rs
│ │ ├── pool.rs # Connection pool
│ │ └── migrations.rs # Migration runner
│ ├── config/ # Configuration
│ │ ├── mod.rs
│ │ └── settings.rs # App settings
│ ├── utils/ # Utilities
│ │ ├── mod.rs
│ │ ├── validators.rs
│ │ └── formatters.rs
│ └── errors/ # Error handling
│ ├── mod.rs
│ ├── app_error.rs
│ └── error_response.rs
├── lib.rs # Library root
└── main.rs # Binary entry point
migrations/ # Database migrations
├── 20250101_initial.sql
└── 20250102_add_users.sql
target/ # Build artifacts (gitignored)
Documentation Organization
docs/
├── api/ # API documentation
│ ├── openapi.yaml # OpenAPI/Swagger spec
│ ├── endpoints.md # Endpoint documentation
│ ├── authentication.md # Auth guide
│ └── rate-limiting.md # Rate limit docs
├── architecture/ # Architecture docs
│ ├── adrs/ # Architecture Decision Records
│ │ ├── README.md
│ │ ├── ADR-001-fastapi.md
│ │ ├── ADR-002-postgresql.md
│ │ └── ADR-003-redis-cache.md
│ ├── C4-context.md
│ ├── C4-container.md
│ ├── SOFTWARE-DESIGN-DOCUMENT.md
│ └── database-schema.md
├── deployment/ # Deployment guides
│ ├── docker.md
│ ├── kubernetes.md
│ ├── github-actions.md
│ └── production.md
├── diagrams/ # Architecture diagrams
│ ├── dataflow-diagrams.md
│ ├── sequence-diagrams.md
│ └── erd.md # Entity relationship diagram
├── project-management/ # Project planning
│ ├── PROJECT-PLAN.md
│ ├── TASKLIST-WITH-CHECKBOXES.md
│ └── checkpoints/ # Session checkpoints
│ └── 2025-12-04-checkpoint.md
├── testing/ # Testing documentation
│ ├── TEST-DRIVEN-DEVELOPMENT.md
│ ├── test-strategy.md
│ └── load-testing.md
└── user-guides/ # User documentation
├── getting-started.md
└── api-reference.md
Testing Organization (Mirror Structure)
tests/
├── unit/ # Unit tests (mirrors src/)
│ ├── auth/
│ │ ├── test_service.py
│ │ └── test_models.py
│ ├── users/
│ │ ├── test_service.py
│ │ ├── test_repository.py
│ │ └── test_models.py
│ └── shared/
│ └── test_utils.py
├── integration/ # Integration tests
│ ├── test_auth_flow.py
│ ├── test_user_crud.py
│ └── test_database.py
├── e2e/ # End-to-end tests
│ ├── test_api_endpoints.py
│ └── test_complete_flows.py
├── load/ # Load/performance tests
│ ├── test_concurrent_users.py
│ └── test_high_throughput.py
├── fixtures/ # Test fixtures
│ ├── database.py # Database fixtures
│ ├── users.py # User fixtures
│ └── auth.py # Auth fixtures
├── mocks/ # Mock objects
│ ├── external_apis.py
│ └── services.py
└── conftest.py # Pytest configuration
Configuration Files Organization
Root Level Only
.env.example # Environment template
.env.development # Development environment
.env.test # Test environment
.env.production # Production environment (gitignored)
requirements.txt # Python dependencies
requirements-dev.txt # Development dependencies
pyproject.toml # Python project config
setup.py # Python package setup
package.json # Node.js dependencies
tsconfig.json # TypeScript config
Cargo.toml # Rust dependencies
alembic.ini # Database migration config
pytest.ini # Pytest configuration
.coveragerc # Coverage configuration
mypy.ini # Type checking config
.flake8 # Python linter config
.pylintrc # Pylint config
.eslintrc.js # ESLint config (Node.js)
.prettierrc # Prettier config (Node.js)
rustfmt.toml # Rust formatter config
clippy.toml # Rust linter config
Database Organization
migrations/ # Database migrations
├── versions/ # Alembic versions
│ ├── 0001_initial.py
│ ├── 0002_add_users.py
│ └── 0003_add_posts.py
├── env.py # Alembic environment
└── script.py.mako # Migration template
seeds/ # Seed data
├── development/ # Dev seeds
│ ├── users.json
│ └── posts.json
├── test/ # Test seeds
│ └── fixtures.json
└── production/ # Production seeds
└── initial_data.json
schemas/ # Database schemas
├── schema.sql # Schema definition
└── indexes.sql # Index definitions
Background Jobs Organization
jobs/ # Background job definitions
├── __init__.py
├── celery_app.py # Celery configuration (Python)
├── queue.ts # Bull queue setup (Node.js)
├── tasks/ # Task definitions
│ ├── email/
│ │ ├── send_welcome.py
│ │ └── send_notification.py
│ ├── data/
│ │ ├── sync_data.py
│ │ └── process_batch.py
│ └── cleanup/
│ └── expire_sessions.py
├── schedules/ # Scheduled tasks
│ ├── hourly.py
│ ├── daily.py
│ └── weekly.py
└── workers/ # Worker configurations
├── email_worker.py
└── data_worker.py
Scripts Organization
scripts/
├── build.sh # Production build
├── test-all.sh # Run all tests
├── start-dev.sh # Start dev server
├── deploy.sh # Deploy to production
├── db/ # Database scripts
│ ├── migrate.sh # Run migrations
│ ├── seed.sh # Seed database
│ ├── backup.sh # Backup database
│ └── restore.sh # Restore database
├── docker/ # Docker scripts
│ ├── build.sh
│ ├── push.sh
│ └── run.sh
└── maintenance/ # Maintenance scripts
├── cleanup-logs.sh
└── health-check.sh
Build Output (Gitignored)
__pycache__/ # Python bytecode
*.pyc # Compiled Python
.pytest_cache/ # Pytest cache
.coverage # Coverage data
htmlcov/ # Coverage reports
.mypy_cache/ # Type checking cache
dist/ # Python distribution
build/ # Build artifacts
node_modules/ # Node.js dependencies
target/ # Rust build output
.env # Local environment (secrets)
*.log # Log files
*.db # SQLite databases
Project Type Detection Rules
Detect as Backend if:
- Has
src/routes/,src/api/, orsrc/handlers/ - Has
src/models/orsrc/schemas/(database) - Has database migration files
- Has API-related dependencies (FastAPI, Express, Actix-web)
- No
public/directory or component files
Framework Detection:
- FastAPI: Has
from fastapi importorFastAPI()in main.py - Django: Has
manage.pyordjangoin requirements.txt - Express: Has
expressin package.json dependencies - NestJS: Has
@nestjs/packages in package.json - Actix-web: Has
actix-webin Cargo.toml
Language Detection:
- Python: Has
requirements.txtorpyproject.toml - Node.js: Has
package.json - Rust: Has
Cargo.toml
Production Readiness Checklist
Root Directory (25 points)
- 5 pts: Only essential files in root (max 25 items)
- 5 pts: All documentation files present (README, CLAUDE, CONTRIBUTING, CHANGELOG, LICENSE, SECURITY)
- 5 pts: All configuration files present
- 5 pts: Docker configuration (Dockerfile, docker-compose.yml)
- 5 pts: Comprehensive .gitignore
Source Organization (25 points)
- 5 pts: Clear domain/module structure
- 5 pts: Layered architecture (controllers, services, models)
- 5 pts: Proper separation of concerns
- 5 pts: Shared modules for cross-cutting concerns
- 5 pts: Database migrations organized
Documentation (25 points)
- 5 pts: docs/ directory with proper hierarchy
- 5 pts: API documentation (OpenAPI/Swagger)
- 5 pts: Architecture documentation (ADRs, diagrams)
- 5 pts: Database schema documentation
- 5 pts: Deployment guides
Infrastructure (25 points)
- 5 pts: scripts/ directory with operational scripts
- 5 pts: tests/ directory with proper organization (unit, integration, e2e)
- 5 pts: Background jobs organized
- 5 pts: Database migrations and seeds
- 5 pts: CI/CD configuration
Total Score: 100 points Production Ready: 90+ points Needs Improvement: 70-89 points Not Ready: <70 points
Common Anti-Patterns to Avoid
❌ Don't Do This
❌ Flat structure (all files in src/)
❌ Mixed layers (controllers + models in same file)
❌ No separation between domains
❌ Database logic in controllers
❌ Business logic in models
❌ Hardcoded configuration
❌ No error handling
❌ No input validation
✅ Do This Instead
✅ Domain-driven structure (src/auth/, src/users/)
✅ Clear layering (controllers → services → models)
✅ Separation of concerns
✅ Repository pattern for database access
✅ Business logic in service layer
✅ Environment-based configuration
✅ Comprehensive error handling
✅ Input validation at entry points
Framework-Specific Variations
FastAPI
- Use Pydantic schemas for validation
- Dependency injection with
Depends() - Async/await patterns
- OpenAPI auto-generation
Django
- App-based structure (
python manage.py startapp) - Models, views, templates separation
- Django ORM for database
- Admin panel configuration
Express/NestJS
- Module-based structure
- Middleware pipeline
- TypeScript for type safety
- Dependency injection (NestJS)
Actix-web (Rust)
- Actor-based patterns
- Type-safe routing
- Async handlers
- Middleware extractor pattern
Migration Guide
If your project doesn't match this standard:
- Create target structure - Create domain directories
- Identify domains - Group related functionality
- Separate layers - Extract controllers, services, models
- Move database - Organize models and migrations
- Update imports - Fix all import paths
- Test thoroughly - Verify all endpoints work
- Commit atomically - One domain per commit
Use: /organize-production command for automated migration
References
Status: Production Standard ✅ Version: 1.0.0 Last Updated: 2025-12-04 Applies To: Node.js, Python, Rust backend API projects