munch-ease-backend/README.md

Meal planner backend

## Quickstart

First time setup:
```bash
make install
```

Run the development server:
```bash
make dev
```

Run tests:
```bash
make test
```

Run all quality checks (lint, typecheck, test, format check, OpenAPI export):
```bash
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:
```bash
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
```

Install packages:
```bash
pip install -r ./requirements.txt
pip install -r ./dev-requirements.txt
```

Install pre-commit hooks:
```bash
pip install pre-commit
pre-commit install
```

### Running the application

Run API (dev):
```bash
make dev
# or: uvicorn main:app --reload
```

Run tests:
```bash
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):
```bash
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.