# AgentForms — Project Context
## Critical Paths (DO NOT GUESS)
| What | Path | Notes |
|---|---|---|
| Source | `~/projects/agentforms/` | Flask backend + Docker. |
| App factory | `app/app.py` | `create_app()` factory. |
| Docker compose | `docker-compose.yml` | Services: `agentforms-app`, `agentforms-worker`, Redis. |
| Venv | `.venv/` | Python 3.12. |
| Tests | `tests/` | 345 pass, 8 fail (pre-existing Phase 3 UI, rate limit, webhook). |
## Docker (Production)
- **App container:** `agentforms-app` → port `5060` (gunicorn, 2 workers, 300s timeout)
- **Worker container:** `agentforms-worker` → RQ worker, async PDF generation
- **Redis:** Shared between app and worker for job queue
- **Local access:** Cloudflare Tunnel → localhost:5060
- **Volume mount:** `./app:/app/app` — edit code, restart container to reload
### Commands
```bash
# Start all services
cd ~/projects/agentforms && docker compose up -d
# Restart app (code changes)
docker compose restart agentforms-app
# Restart worker
docker compose restart agentforms-worker
# View logs
docker compose logs -f agentforms-app
docker compose logs -f agentforms-worker
```
## Database
- **SQLite files at root (`agentforms.db`, `app.db`) are 0 bytes — stale/unused.**
- Production uses the Docker volume. Check `docker compose exec agentforms-app` to inspect.
- **DO NOT** run `db.create_all()` on the local stale DB files — they're empty placeholders.
## Relay Binaries
- **Host:** `relay.agentforms.io` on Hetzner
- **Stack:** Nginx + Certbot
- **DNS:** Cloudflare API token (env vars loaded)
- **File transfer:** SCP files need `chmod 644` for nginx worker
- **Source:** `~/projects/agentforms/` → build → deploy to relay
## API
- **Version:** v2 — `POST /api/v2/documents/generate`
- **Architecture:** 4-module doc split, 3-module app split
- **Auth:** Cookie-based sessions
## Tests
```bash
cd ~/projects/agentforms && .venv/bin/python -m pytest tests/ -x
```
## Common Pitfalls
- Local SQLite files (`agentforms.db`, `app.db`) are empty — do not use them as source of truth.
- Code changes require `docker compose restart agentforms-app` — no hot reload.
- Worker heartbeat checks Redis — if stale (>180s), worker is hung.