Meal planner backend

Quickstart

First time setup:

make install

Run the development server:

make dev

Run tests:

make test

Run all quality checks (lint, typecheck, test, format check, OpenAPI export):

make all-checks

Structure

• main.py: FastAPI app with all HTTP endpoints.
• db.py: aiosqlite connection + schema bootstrap across subpackages (calls each feature's repository.create).
• Domain packages with models and persistence:
  • products/ (models.py, repository.py, scrapers for Woolworths/Coles)
  • ingredients/ (models.py, repository.py)
  • recipes/ (models.py, repository.py, scraping.py)
  • meals/ (models.py, repository.py, service.py)
  • persons/ (models.py, repository.py)
  • shopping/ (models.py, repository.py)
• tests/: unit and API tests with sample HTTP fixtures.

Getting started

Manual setup (alternative to make install)

Create and activate virtual environment:

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install packages:

pip install -r ./requirements.txt
pip install -r ./dev-requirements.txt

Install pre-commit hooks:

pip install pre-commit
pre-commit install

Running the application

Run API (dev):

make dev
# or: uvicorn main:app --reload

Run tests:

make test
# or: pytest -q

Available Make targets

• make install - Create venv and install all dependencies
• make dev - Run development server
• make test - Run tests
• make format - Format code with ruff
• make lint - Lint code with ruff
• make typecheck - Type check with mypy
• make openapi - Export OpenAPI schema
• make all-checks - Run all quality checks
• make clean - Remove venv and caches

Tooling

This repo includes baseline configs in pyproject.toml:

• ruff (format and lint)
• mypy (type check)

Pre-commit hooks are configured to run:

• ruff (lint + format)
• mypy
• trailing whitespace fixer
• end-of-file fixer

Quality checks (run locally):

make format      # Format code
make lint        # Lint code
make typecheck   # Type check
make all-checks  # Run all checks

Environment variables

Copy .env.example to .env and customize as needed:

• DOOF_DB: Path to sqlite database (default: ./data/doof.sqlite)
• DOOF_PROD: Set to true in production (default: false)
• FRONTEND_DEV_URL: Frontend dev server URL for reverse proxy (default: http://localhost:8080/)
• DOOF_PORT: Port the server listens on when containerized; align Dockerfile EXPOSE accordingly.

OpenAPI schema

• Generate the schema artifact used by the frontend and CI checks:

python scripts/export_openapi.py

This writes openapi.json to the repo root. Versioned endpoints live under /api/v1, legacy under /api (deprecated with Deprecation header).

Schema lint/diff (manual)

Optionally, lint and compare schemas locally using Node tools:

npx -y @stoplight/spectral-cli lint openapi.json
npx -y openapi-diff --fail-on-changed --fail-on-incompatible path/to/baseline.json openapi.json

Keep a baseline.json on release branches to detect breaking changes.