Place this in the root of your project. This file gives Claude the exact blueprint of your stack, commands, and strict behavioral rules to minimize token usage

memory.md

Project Memory

🎯 Current State

Building a highly decoupled, production-ready FastAPI backend. Using punq for IoC/Dependency Injection, asyncpg for database performance, and a multi-stage Docker build for deployment.

🧠 Core Technical Decisions (ADRs)

• Dependency Injection: Shifted from FastAPI's native Depends() to punq. This allows strict separation between the web framework and the domain logic.
• Execution: Utilizing the official fastapi-cli (fastapi dev / fastapi run) for standardized server execution and automatic worker management.
• Package Management: uv is strictly enforced for dependency resolution and building the Docker image.

⚠️ Known Issues / TODOs

• Need to write the base app/core/di.py to initialize the punq.Container and register the database session factory.
• Need to draft the Dockerfile optimized for uv caching and multi-stage builds.

Python Fast API

# Project: FastAPI AsyncPG (Punq DI + Docker Core)
**Tech Stack:** Python 3.12+, FastAPI, SQLAlchemy 2.0 (async), asyncpg, Alembic, Pydantic V2, Pytest, `uv`, `punq`.

## 🤖 AI Behavioral Rules (TOKEN SAVING)
- **Zero Fluff:** Output only requested code. No summaries, no conversational filler.
- **Diffs Only:** Provide only modified functions/classes, not full files.
- **No Redundant Comments:** Skip docstrings for basic routes/CRUD. Comment only complex business rules.

## 🏗 Architecture & Dependency Injection (`punq`)
- **DI Container:** All Services and Repositories are registered in a `punq` container (e.g., `app/core/di.py`).
- **Router Integration:** FastAPI routers resolve dependencies from `punq` via a custom callable, e.g., `service: UserService = Depends(get_service(UserService))`.
- **Layered Design:** Routers (HTTP) -> Services (Business Logic) -> Repositories (asyncpg/SQLAlchemy). Services do NOT depend on FastAPI.

## 🐳 Docker & Production Standards
- **Multi-stage Dockerfile:** Build dependencies in a builder stage using `uv`, then copy the virtual environment (`.venv`) to a distroless or `python:3.12-slim` runner image.
- **Rootless:** The production container must run as a non-root user.
- **Workers:** Use Gunicorn with Uvicorn workers (or `fastapi run` which scales workers per CPU core) to handle high concurrency in production.

## 🔒 Security Best Practices
- **Auth:** OAuth2 with Bearer token (JWT).
- **Secrets:** Pydantic `BaseSettings`. Never hardcode secrets.
- **SQL Injection:** Strict use of parameterized SQLAlchemy 2.0 expressions.

## 🛠 `uv` & Execution Commands
- **Run Dev:** `uv run fastapi dev app/main.py`
- **Run Prod:** `uv run fastapi run app/main.py` (CLI handles workers natively) OR `uv run gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000`
- **Add Dep:** `uv add <pkg>` (Use `--dev` for dev deps)
- **Migrations:** `uv run alembic revision --autogenerate -m "msg"` | `uv run alembic upgrade head`
- **Tests:** `uv run pytest --asyncio-mode=auto`

work_summary.md

Work Summary Log

Format: [YYYY-MM-DD HH:MM:SS TZ] | Task | Modified Files | Status

---

[2026-03-27 09:01:10 CET] - Task: Initialized project blueprint and AI context files.

• Files: CLAUDE.md, memory.md, work_summary.md.
• Status: Done.

[2026-03-27 09:03:52 CET] - Task: Refactored architectural guidelines to integrate punq for DI, updated dev/prod CLI commands, and defined Docker multi-stage constraints.

• Files: CLAUDE.md, memory.md, work_summary.md.
• Status: Done.
• Next Step: Generate the optimized Dockerfile and the app/core/di.py container setup.

[YYYY-MM-DD HH:MM:SS TZ]

• Task: - Files: - Status: - Next Step: ```

---

Would you like me to write the highly optimized, multi-stage Dockerfile using uv and the app/core/di.py file to establish your punq container?