# SleepLab — Claude Context

## Project structure
- `importer/` — standalone Python scripts; run directly, not via the FastAPI app
- `importer/db.py` — shared Postgres helpers (`get_conn`, `upsert_session`, `session_exists`, etc.)
- `server.py` / `api/` — FastAPI backend
- `frontend/` — React frontend

## Git
- Feature work goes on named branches (`feature/<topic>`) with one PR per feature
- Ensure your `git config user.name` and `git config user.email` are set before committing

## Private files
- `.newfeatures` — local implementation notes, never commit or push

## Importer conventions
- Session IDs from EDF files: `YYYYMMDD_HHMMSS`
- Session IDs from SleepHQ: `sleephq-{record_id}` (namespaced to avoid collisions)
- Always check `session_exists()` before upsert; use `--force` / `skip_existing=False` to overwrite

## Dependencies
- `requirements.txt` uses pinned versions for PyPI packages
- Git-sourced deps use PEP 440 direct-reference syntax: `pkg @ git+https://...`

## Testing

Run the full suite before committing, pushing, or opening PRs:

**Backend:**
```bash
ruff check tests/          # lint
uv run pytest -v --tb=short  # tests (DB tests skip without Postgres)
```

**Frontend:**
```bash
cd frontend
npx tsc --noEmit -p tsconfig.app.json     # type check (root tsconfig has files:[] so --noEmit alone checks nothing)
npx vitest run       # unit tests
```

The CI workflow (`.github/workflows/ci.yml`) runs these automatically on every PR to `main`.