# EKG Tutor

Educational PWA for learning 12-lead EKG interpretation through guided
case-based Socratic practice.

**Not a medical device. Not for clinical diagnostic use under any circumstance.**

Lives as a subsystem under `adampowell.pro/apps/ekg-tutor/`. Served at
`https://adampowell.pro/ekg-tutor/` behind the parent site's auth gate.

## Layout

```
ekg-tutor/
├── contracts/   shared Zod + JSON-Schema definitions (single source of truth)
├── web/         PWA frontend (Vite + React 19 + TypeScript)
├── api/         Application API (Node + Fastify + TypeScript + Drizzle + Postgres)
├── tutor/       Tutor service (Node + Fastify + Anthropic TS SDK)
├── interpret/   Interpretation service (Python 3.12 + FastAPI + Anthropic Python SDK)
├── docs/        Blueprint, rubric, concept taxonomy, deploy notes
└── infra/       systemd unit files, nginx snippet, deploy scripts
```

## Ports

| Service          | Port  | Bind        |
|------------------|-------|-------------|
| ekg-tutor-api    | 3110  | 127.0.0.1   |
| ekg-tutor-tutor  | 3111  | 127.0.0.1   |
| ekg-tutor-interp | 3112  | 127.0.0.1   |

Postgres uses the existing instance on the droplet (the one `sharedtodo` already
talks to). New database: `ekg_tutor`.

## Auth

URL is gated by the parent `adampowell.pro` `/login` page. The API reads the
session username from the parent auth subrequest and maps it to a row in the
local `users` table. No second password.

## Quick start

```bash
cd apps/ekg-tutor
pnpm install
pnpm build            # builds contracts → web → api → tutor in dependency order
```

See `docs/DEPLOY.md` for the droplet-side setup (Postgres database, systemd
units, nginx snippet, symlink). See `docs/BLUEPRINT.md` for the full design.
See `docs/PHASE1_STATUS.md` for current implementation progress.