85 lines
3 KiB
Markdown
85 lines
3 KiB
Markdown
# Project Guide
|
|
|
|
## Project
|
|
- Python clean architecture template
|
|
- FastAPI is the current HTTP adapter
|
|
- The web layer must stay replaceable
|
|
- Repository and usecase instances are created once at startup
|
|
- Config comes from YAML plus env into one dataclass tree
|
|
- Logs metrics and traces stay behind interfaces and use OTel adapters
|
|
- Request logging middleware is used
|
|
- Metrics middleware is used
|
|
- Custom trace middleware is not used
|
|
- API versioning lives under `/api/v1`
|
|
|
|
## Structure
|
|
- `domain/` core model and domain errors
|
|
- `domain/error.py` domain errors
|
|
- `domain/user.py` example domain model
|
|
- `usecase/` interfaces and usecases
|
|
- `usecase/interface.py` repository and observability interfaces
|
|
- `usecase/user.py` example user usecase
|
|
- `repository/` repository implementations
|
|
- `repository/user.py` example in-memory repository
|
|
- `adapter/config/` config models and loader
|
|
- `adapter/otel/` logger metrics tracer and OTel setup
|
|
- `adapter/di/` container and startup wiring
|
|
- `adapter/http/fastapi/` app dependencies lifespan middleware routers
|
|
- `config/` app YAML and OTel collector config
|
|
- `docs/` ADR files
|
|
- `tasks.md` task list
|
|
- `main.py` local entrypoint
|
|
|
|
## Boundaries
|
|
- Keep dependency direction inward
|
|
- `domain` imports nothing internal
|
|
- `usecase` may import `domain`
|
|
- `repository` may import `usecase` and `domain`
|
|
- `adapter` may import `usecase` and `domain`
|
|
- Do not import FastAPI into `domain` or `usecase`
|
|
- Do not import OpenTelemetry into `domain` or `usecase`
|
|
- Keep HTTP models and middleware inside `adapter/http/fastapi/`
|
|
|
|
## Workflow
|
|
- Use `tasks.md` for planning
|
|
- Do not use Beads
|
|
- Do not use `bd`
|
|
- Use `uv` for Python commands and dependency management
|
|
- Do not create commits on your own
|
|
- Work on one task at a time
|
|
- Prefer delegation for implementation
|
|
- Delegate only one task at a time
|
|
- After one task return to the user with result verification and next options
|
|
- Wait for the user before the next task commit or fix
|
|
|
|
## Makefile
|
|
- `make install` install deps with `uv`
|
|
- `make run` start the app locally
|
|
- `make run-otel` start the app with OTel env
|
|
- `make lint` run `ruff`
|
|
- `make typecheck` run `mypy`
|
|
- `make test` run `pytest`
|
|
- `make pre-commit` run lint typecheck test
|
|
- `make compose-build` build the containers
|
|
- `make compose-up` start app and collector
|
|
- `make compose-down` stop the stack
|
|
- `make compose-logs` show app and collector logs
|
|
- `make compose-ps` show compose status
|
|
|
|
## Runtime
|
|
- Local run needs `APP_API_TOKEN` and `APP_SIGNING_KEY`
|
|
- Base config lives in `config/app.yaml`
|
|
- Env overrides come from shell vars or `.env`
|
|
- OTel collector config lives in `config/otel-collector.yaml`
|
|
|
|
## Style
|
|
- Comments are short and have no trailing period
|
|
- Error messages are short and have no trailing period
|
|
- Use single-word comments when possible
|
|
- Use single-word error messages when possible
|
|
- Keep names simple
|
|
- Keep adapters thin
|
|
- Keep `__init__.py` empty
|
|
- Prefer explicit wiring over magic
|
|
- Do not expand scope without user approval
|
|
- Do not `from __future__ import annotations`
|