Architecture

                    ┌──────────────────────────────┐
                    │        FastAPI app           │
                    │  /docs · /redoc · /health    │
                    └──────────────┬───────────────┘
                                   │
       ┌───────────┬───────────────┼────────────┬──────────────┐
       │           │               │            │              │
 ┌───────────┐ ┌──────────┐ ┌─────────────┐ ┌─────────┐  ┌───────────────────┐
 │  /auth    │ │/categories│ │/menu-items  │ │ /prices │  │      /menus       │
 │ register  │ │   CRUD   │ │  + filters  │ │ history │  │      publish      │
 │  login    │ │          │ │             │ │ set new │  │      archive      │
 │  /me      │ │          │ │             │ │         │  │ /menus/{id}/items │
 └─────┬─────┘ └────┬─────┘ └──────┬──────┘ └────┬────┘  └─────────┬─────────┘
       │            │              │             │             │
       ▼            ▼              ▼             ▼             ▼
   ┌──────────────────────────────────────────────────────────────┐
   │     JWT dependency · require_role(admin|staff) guards        │
   └──────────────────────────┬───────────────────────────────────┘
                              │
                              ▼
            ┌──────────────────────────────────┐
            │        SQLAlchemy 2.x ORM        │
            └──────────────┬───────────────────┘
                           │
        ┌──────────────────┴──────────────────┐
        ▼                                     ▼
  ┌────────────┐   PRODUCTION            ┌────────────┐
  │ PostgreSQL │◀───────────────────────▶│   SQLite   │   LOCAL DEMO
  └────────────┘                         └────────────┘

Data model (entities, PK → relationships):

User ─── created ───▶ Price ─── for ───▶ MenuItem ─── in ───▶ Category
                        ▲                      ▲
                        │                      │
                        └── snapshot row ──────┤
                                               │
                                          MenuItemInMenu ──▶ Menu
                                              (composite PK)

Running locally

# 1. Create a virtualenv and install deps
python -m venv .venv
source .venv/bin/activate          # on Windows: .venv\Scripts\activate
pip install -e ".[dev]"

# 2. Copy environment defaults
cp .env.example .env                # edit JWT_SECRET before anything real

# 3. Apply the initial migration to a fresh SQLite DB
alembic upgrade head                # reads DATABASE_URL from your .env — no need to edit alembic.ini

# 4. Seed demo data (admin + staff user, categories, items, a published menu)
python -m scripts.seed              # pass --reset to wipe and reseed

# 5. Serve
python -m scripts.serve             # honors APP_HOST / APP_PORT / APP_DEBUG
# ...or run uvicorn directly:
uvicorn app.main:app --reload

alembic/env.py resolves sqlalchemy.url from Settings at runtime, so configuring DATABASE_URL in .env is all that's needed - alembic.ini is intentionally left blank for that field.

Then open http://localhost:8000/docs and authorize with the credentials printed by the seed script.

Switching to PostgreSQL

One environment variable - no code changes:

export DATABASE_URL="postgresql+psycopg://user:pass@localhost:5432/menu"
pip install -e ".[postgres]"
alembic upgrade head

API overview

Authentication flow

┌──────┐                       ┌───────────────┐
│Client│                       │ /auth/login   │
└───┬──┘                       └───────┬───────┘
    │  POST {email, password}          │
    │ ────────────────────────────────▶│
    │                                  │  verify bcrypt hash
    │                                  │  mint HS256 JWT
    │  { access_token, expires_in }    │
    │ ◀────────────────────────────────│
    │
    │  subsequent requests carry:
    │  Authorization: Bearer <token>
    │
    │                         ┌────────────────────────┐
    │                         │ get_current_user       │
    │ ───────protected───────▶│  decode + verify JWT   │
    │                         │  SELECT user by sub    │
    │                         │                        │
    │                         │ require_role(...)      │
    │                         │  admin ⊇ staff         │
    │                         └────────────────────────┘

Token payload: {sub: "<user_id>", role: "admin" | "staff", iat, exp}. sub is a string (the stringified user ID), following the JWT spec recommendation - clients that treat it as an integer will end up with accidental "1" != 1 bugs. Default expiry is 60 minutes; override with JWT_EXPIRE_MINUTES.

Running tests

pytest                          # run the suite
pytest --cov=app                # with coverage (pythonpath = ["src"] is set in pyproject.toml)

The test suite covers auth happy path + credential failures + expired tokens, RBAC on every mutating endpoint, price supersession, and the core archival-fidelity guarantee - changing a price after archiving a menu does not alter what the archived menu returns.

Project layout

src/app/
├── main.py               FastAPI factory, OpenAPI metadata
├── config.py             pydantic-settings
├── db.py                 engine, SessionLocal, get_db
├── auth/                 passwords, JWT, dependencies, /auth router
├── models/               SQLAlchemy 2.x declarative models
├── schemas/              Pydantic v2 request/response schemas
└── routers/              /categories /menu-items /prices /menus
alembic/                  migration env + initial schema revision
scripts/seed.py           demo data bootstrap
tests/                    pytest + in-memory SQLite fixtures

What's next

Things I'd build if this were more than a portfolio piece:

• Orders + tickets. The data model already supports "which item and which price" - adding an Order table would close the loop from menu to kitchen.
• True soft-delete for menu items. Today is_active acts as a soft-hide (filtered out of default listings) while DELETE is a hard-delete that cascades price history and is blocked by archived menus. A proper soft-delete — deleted_at timestamps plus a dedicated endpoint to browse the price history of removed items — would be a natural next step. Not a current bug; the current model is intentional and documented.
• Image uploads for items, persisted to object storage with signed URLs served through the item response.
• Per-tenant isolation. A restaurant_id column on every table plus a middleware that scopes reads/writes to the caller's tenant.
• Event log. Right now archival and price changes are inferable from row states but not auditable - an append-only events table keyed by actor would fix that.
• Caching. GET /menus/{id}/items is imm