Scaffold a Python Service

Organize by concern, not by file type. Each layer has one job.

project/
├── backend/
│   ├── app/
│   │   ├── api/           # Thin route handlers — validate input, call service, return output
│   │   ├── core/          # Config, dependencies, exceptions, middleware
│   │   ├── models/        # Pydantic request/response + domain models
│   │   ├── services/      # Business logic — no HTTP, no SQL
│   │   └── db/            # Database queries — SQL only, no business logic
│   └── tests/
│       ├── unit/
│       ├── integration/
│       └── system/
├── migrations/            # Database migrations (Alembic)
├── pyproject.toml
└── .gitignore

Hard Layer Rules

• Route handlers contain no business logic — they call services
• Services contain no SQL — they call the database layer
• Database layer contains no business logic — it executes SQL
• One mutation path per aggregate — if multiple services could write the same table, define a single state manager

Initial Config

• pyproject.toml with uv, ruff, mypy, pytest config — see ceh-python-service:python-service-environment.
• Web service deps: fastapi, uvicorn[standard], pydantic-settings, asyncpg, alembic, structlog.

Agent instruction file

Claude Code reads CLAUDE.md, not AGENTS.md. If the repo already has an AGENTS.md for other coding agents, do not duplicate it — create a CLAUDE.md that imports it, so both tools read one source:

@AGENTS.md

Add any Claude-specific instructions below the import. A symlink also works, but on Windows it needs Administrator or Developer Mode, so prefer the import. If there is no AGENTS.md, just write CLAUDE.md directly.

.gitignore

.venv/
.env
.env.*
!.env.example
__pycache__/
*.pyc
*.egg-info/
.coverage
.pytest_cache/
.mypy_cache/
.ruff_cache/
dist/
build/
*.db
.DS_Store