development.md

Development Guide

Recommended workflow

1. Create a focused branch for the change.
2. Update or add an Alembic migration when the database schema changes.
3. Keep HTTP concerns in routers and business rules in services.
4. Reuse repositories for database access instead of adding queries to route handlers.
5. Update the API or frontend documentation when behavior changes.
6. Run the validation commands below before opening a pull request.

Backend commands

# Install dependencies
poetry install

# Start the API with reload
poetry run uvicorn app.core.main:app --reload --host 0.0.0.0 --port 8888

# Apply migrations
poetry run alembic upgrade head

# Inspect migration state
poetry run alembic current
poetry run alembic history

# Check Python syntax
python -m compileall app

Frontend commands

cd frontend
yarn install
yarn dev
yarn lint
yarn build

Adding a backend feature

For a new resource or use case, use this sequence:

1. Add or update SQLAlchemy models under app/db/models/.
2. Generate and review an Alembic revision.
3. Add Pydantic schemas under app/schemas/.
4. Implement persistence methods in a repository.
5. Implement business logic in a service.
6. Expose the feature through a router and register it in app/core/main.py.
7. Add the corresponding frontend service, types, page, or admin component.
8. Document the endpoints in docs/api.md.

Migrations

poetry run alembic revision --autogenerate -m "describe the schema change"
poetry run alembic upgrade head

Autogenerated migrations must be reviewed manually, especially enum changes, nullable constraints, foreign keys, indexes, and data migrations. Do not edit an already-applied migration; create a new revision instead.

Validation checklist

• The API starts successfully with the documented environment variables.
• GET /health reports a healthy database connection.
• poetry run alembic upgrade head succeeds on a clean database.
• Protected routes reject unauthenticated requests.
• Admin routes reject regular users.
• python -m compileall app completes without errors.
• yarn lint completes without errors.
• yarn build completes without errors.
• Documentation contains no local secrets or machine-specific URLs.

Current project limitations

• The repository does not currently include an automated backend test suite.
• Production reverse-proxy configuration is not included; the Compose nginx service expects external configuration files.
• A license file has not yet been added.

These are clear follow-up tasks before presenting the project as a production deployment or open-source package.