Core application code lives under project/. Use project/core/ for app setup, settings, database wiring, and service endpoints such as health and metrics. Feature code belongs in project/apps/; the current example is project/apps/user/ with models.py, serializers.py, and views.py. Static assets and templates are served from project/static/, project/media/, and project/templates/. Alembic migrations live in migrations/. Tests mirror the runtime structure under tests/ (tests/test_core/, tests/test_utils/).
Install dependencies with make activate or poetry install --no-root. Run the app locally with make run; this starts uvicorn project.asgi:app --reload with PYTHONPATH=$(pwd)/project. Run the full test suite with make test. Run lint and format checks with make linter (ruff check . plus ruff format --check .), and apply automatic fixes with make format. Create and apply schema changes with make makemigrations and make migrate. Build the container with make build.
Target Python 3.11+ and follow Ruff formatting defaults: 4-space indentation, double quotes, and imports grouped by standard library, third-party, then local modules. Keep module names lowercase with underscores, class names in PascalCase, and functions, variables, and route handlers in snake_case. Follow the existing app layout when adding features: models.py, serializers.py, views.py, then register routes in project/apps/routes.py.
Tests use pytest, pytest-asyncio, and pytest-cov. Name files test_*.py and keep test classes and functions descriptive, for example TestApplication.test_ping. make test runs coverage for project/ and emits terminal plus XML reports. The shared client fixture in tests/conftest.py migrates the database up and down per test, so keep PostgreSQL available locally before running tests.
Recent history favors short, imperative commit subjects such as update, deps, and lock; more descriptive messages are better when changing behavior, for example Add user delete validation. Keep commits focused and avoid mixing dependency locks with feature work unless required. PRs should include a short summary, note any migration or config changes, link the issue when applicable, and include request/response examples or screenshots when API or UI behavior changes.
Settings are defined in project/core/settings.py and loaded from project/.env. Set DB_DSN explicitly if you are not using the default local Postgres connection. Most commands rely on PYTHONPATH=$(pwd)/project; use the Make targets rather than invoking tools manually unless you need custom arguments.