# 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`](OVERVIEW.md), [`ARCHITECTURE.md`](ARCHITECTURE.md), [`PHASE0_PLAN.md`](PHASE0_PLAN.md).

## Quickstart (local)

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

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

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

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

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

Coverage:

```bash
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`](ARCHITECTURE.md) §4.8).

## Repo shape

Full tree in [`ARCHITECTURE.md`](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`](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`](SYSTEM_SECURITY_PLAN.md) v0.3 — NIST 800-53 Moderate SSP
- [`NIST_800_53_CONTROL_MAPPING.md`](NIST_800_53_CONTROL_MAPPING.md) v0.2 — full control-family map
- [`PRIVACY_IMPACT_ASSESSMENT.md`](PRIVACY_IMPACT_ASSESSMENT.md) v0.1 — PIA covering minors, SSN, banking, FERPA, CFSA
- [`POAM.md`](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.