pal-e-docs

Phase 3: Data Model + Postgres

phase-mcd-tracker-3-data-model Phase

phase
Project
Goal: SQLAlchemy models defined, Alembic migrations running, DB-backed health check, deployed to prod.
Owner: Dev agent
Repo: forgejo_admin/mcd-tracker-api
Depends on: Phase 2 (COMPLETED — FastAPI scaffold live, postgres pod running)

Scope

Add database layer to the existing FastAPI scaffold. Postgres sidecar is already deployed (Phase 1). This phase connects the app to it and defines the domain model from arch-domain-mcd-tracker.
  • Add src/mcd_tracker_api/database.py — SQLAlchemy engine, SessionLocal, Base, get_db() dependency
  • Add src/mcd_tracker_api/models.py — SQLAlchemy models per domain diagram:
  • Add SQLAlchemy + psycopg2-binary + alembic to pyproject.toml dependencies
  • Init Alembic: alembic init alembic/, configure alembic/env.py to use settings.database_url
  • Create first migration: alembic revision --autogenerate -m "initial schema"
  • Add migration-on-startup to lifespan in main.py: alembic.command.upgrade(config, "head")
  • Update /healthz to verify DB connection (SELECT 1)
  • Add integration test: verify models create tables, health endpoint shows DB connected

Architecture Touch

arch-domain-mcd-tracker — this phase implements the entity model. The domain diagram was designed for these exact models. No diagram update needed unless implementation diverges.

Verification

  • curl https://mcd-tracker.tail5b443a.ts.net/healthz shows DB connected
  • Alembic migration runs on pod startup (check logs)
  • Tables exist in postgres: location, coupon_usage
  • CI green with integration tests

  • pending
  • plan-mcd-tracker — parent plan
  • phase-mcd-tracker-2-backend-scaffold — depends on
  • arch-domain-mcd-tracker — entity model this implements