YPMS — Youth Program Management System

DC Department of Employment Services / Office of Youth Programs — in-house build replacing seven legacy tools (MBSYEP intake, TMS timekeeping, PF3 admin, manual payroll scripts, MicroStrategy, and two supporting apps) with a single Python / FastAPI / Postgres system on Azure Government.

Status: Pre-development. Phase 0 (foundations) in flight. System owner + ISSO + AO: Chris Tonjes, DOES CIO. Full context: OVERVIEW.md, ARCHITECTURE.md, PHASE0_PLAN.md.

Quickstart (local)

Requires Docker Desktop (or equivalent). Ports 8000 (app), 5433 (Postgres), 8081 (Adminer) must be free.

cp .env.example .env
docker compose up --build

App at http://localhost:8000. OpenAPI docs at http://localhost:8000/docs.

curl http://localhost:8000/healthz    # → {"status":"ok"}
curl http://localhost:8000/readyz     # → {"status":"ok"} once db is up

Adminer (DB explorer) at http://localhost:8081. Connect with:

• System: PostgreSQL
• Server: db
• Username / Password / Database: ypms / ypms / ypms

Stop with Ctrl+C; wipe local DB with docker compose down -v.

Tests

Local (no Docker required for the tests):

python -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'
pytest

Coverage:

pytest --cov=src/ypms --cov-report=term-missing

Tests use SQLite in-memory for speed. Postgres-specific behaviour gets its own Postgres-only fixture when a migration or query needs it (see ARCHITECTURE.md §4.8).

Repo shape

Full tree in ARCHITECTURE.md §5.1. High points:

• src/ypms/main.py — FastAPI factory
• src/ypms/settings.py — pydantic-settings config
• src/ypms/db.py — SQLAlchemy engine, session, Base
• src/ypms/logging.py — structlog + sensitive-field sanitizer
• src/ypms/middleware.py — request id
• src/ypms/framework/ — vendored from OWC, milestone 0.2
• src/ypms/security/ — auth + RBAC + column encryption, milestones 0.3–0.4
• src/ypms/youth/ — Registrant entity (vertical slice), milestone 0.5
• Other entity packages — 501 stubs, milestone 0.6
• migrations/ — Alembic, immutable-once-merged
• tests/ — pytest, SQLite by default

Adding an entity

Once the framework lands in milestone 0.2, adding a new entity follows the OWC add-entity pattern (model → schemas → router → main.py registration → migration → permissions seed entry → test → coverage doc). Full instructions land here at milestone 0.2 completion.

Contributing

See CONTRIBUTING.md for the hard rules. Highlights: migrations are immutable once merged, every state-mutating route emits an audit row, framework/security modules must not carry domain logic, no --no-verify or # type: ignore without a written reason.

Compliance

• SYSTEM_SECURITY_PLAN.md v0.3 — NIST 800-53 Moderate SSP
• NIST_800_53_CONTROL_MAPPING.md v0.2 — full control-family map
• PRIVACY_IMPACT_ASSESSMENT.md v0.1 — PIA covering minors, SSN, banking, FERPA, CFSA
• POAM.md v0.1 — POA&M with 62 items and 2 closures as of 2026-09-30

License / usage

Internal DOES system. Not for external distribution.