# Next Developer Handoff

## Project: ots-containers

CLI tool for managing OneTimeSecret containers via Podman Quadlets (systemd integration).

## Current State (2025-12-15)

**137 tests passing.** Production-ready with FHS compliance, SQLite tracking, and proper quadlet configuration.

### Implemented

1. **FHS-compliant paths** (`config.py`)
   - `/etc/onetimesecret/` - System config (config.yaml, .env template)
   - `/var/opt/onetimesecret/` - Runtime data (.env-{port}, deployments.db)

2. **SQLite deployment tracking** (`db.py`)
   - Append-only audit trail in `deployments` table
   - `image_aliases` table for CURRENT/ROLLBACK tag resolution
   - Consecutive rollback support via history walking (not env vars)

3. **Production quadlet template** (`quadlet.py`)
   - `[Service]` section with `Restart=on-failure`, `RestartSec=5`
   - Health checks: `HealthCmd`, `HealthInterval=30s`, `HealthRetries=3`, `HealthStartPeriod=10s`

4. **New commands**
   - `init` - Idempotent setup (dirs, db, permissions)
   - `image pull/list/set-current/rollback/history/aliases`

### Remaining Work (Lower Priority)

| Priority | Task |
|----------|------|
| MEDIUM | Add resource limits (`PodmanArgs=--memory=1g --cpus=2`) |
| LOW | Consider `podman secret` for sensitive env values |

### Key Files

| File | Purpose |
|------|---------|
| `src/ots_containers/config.py` | Config dataclass with FHS paths, alias resolution |
| `src/ots_containers/db.py` | SQLite operations, deployment timeline |
| `src/ots_containers/quadlet.py` | Quadlet template with [Service] section |
| `src/ots_containers/commands/init.py` | Setup command |
| `src/ots_containers/commands/image/app.py` | Image management commands |

### Naming Convention

- **Systemd unit**: `onetime@7043.service`
- **Podman container**: `systemd-onetime_7043` (underscore, not @)

### Testing

```bash
pytest tests/ --cov=ots_containers --cov-fail-under=70
```

Mock patterns: Always use `tmp_path` for file paths in mocks, never real system paths.

### Architecture Decision Records

- **Host networking**: Chosen for performance; each instance identified by port
- **Port-based instances**: `onetime@7043`, `onetime@7044`, etc.
- **SQLite over env vars**: Enables consecutive rollbacks, audit trail
- **MAX(id) ordering**: SQLite datetime has second precision; use id for ordering
