# AGENTS.md

## Quick Commands
```bash
pytest -q                    # Run all tests
python app.py                # Start server (requires valid .env)
```

## Testing
- Tests use `config_override` in `create_app()` to mock settings and skip the collector thread (`start_collector=False`).
- No database connection required for tests—SQLite uses temp directories.
- Test files: `tests/test_api.py` with 3 test functions.

## Required Env Vars
| Variable | Purpose |
|----------|---------|
| `SUPABASE_DB_HOST` | Connection pooler hostname |
| `SUPABASE_DB_PORT` | Pooler port (typically 6543) |
| `SUPABASE_DB_NAME` | Database name |
| `SUPABASE_DB_USER` | User in format `postgres.<project-ref>` |
| `SUPABASE_DB_PASSWORD` | Password |

## App Architecture
- **Entry**: `app.py` exports `create_app()` and `app` (FastAPI instance).
- **Config**: `load_config()` validates required vars, returns `Settings` dataclass.
- **Storage**: `RRDStore` class manages SQLite circular buffer (auto-prunes based on `max_samples`).
- **Ping**: `run_ping()` executes keep-alive query, returns `(success, latency_ms, error_message)`.
- **Collector**: `collector_loop()` runs in daemon thread, interval from `PING_INTERVAL_MINUTES`.

## API Endpoints
- `GET /` — Dashboard (SmokePing-style)
- `GET /api/status` — Latest sample
- `GET /api/history?hours=48` — Sample history (max 48h)
- `GET /docs` — Swagger UI
- `GET /openapi.json` — OpenAPI schema

## Docker
```bash
docker build -t supabase-pinger .
docker run -d --env-file .env -p 8080:8080 --restart unless-stopped supabase-pinger
```