jableader
7b6f4e2a3b
commit 21a17b771743b23ee41d11a90ed8fdc3433468ce
Author: jableader <jacobdunk@gmail.com>
Date: Mon Oct 20 00:12:02 2025 +1100
Completed tooling improvements, fixed remaining errors
commit 7db48e222e3aa1065c326197c33ba6439720f65a
Author: jableader <jacobdunk@gmail.com>
Date: Sun Oct 19 22:05:37 2025 +1100
autoformat
commit 5705ce24b64c2aa6f0b9426730a479165fa97e2a
Author: jableader <jacobdunk@gmail.com>
Date: Sun Oct 19 22:05:29 2025 +1100
tooling changes
commit f0a6b2fd147bb86b484927afd57b9ba0ac07bf47
Author: jableader <jacobdunk@gmail.com>
Date: Sun Oct 19 21:25:49 2025 +1100
Plan
132 lines
3.1 KiB
Markdown
132 lines
3.1 KiB
Markdown
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.
|