Worker
Worker Documentation
Source of Truth
When documentation conflicts with code, code wins. These are the canonical sources:
| What | Source of Truth |
|---|---|
| API request/response schema | apps/api/src/routes/*/*.schema.ts or /openapi.json |
| Worker envelope format | apps/worker/src/api/responses.py (ok() / fail()) |
| Worker route behavior | apps/worker/src/sites/*/routes.py + schemas.py |
| Environment variables | apps/worker/src/settings.py + site config.py files |
| Architecture | architecture.md (update only when module boundaries change) |
Docs Layout
docs/
├── README.md # This file — source of truth + governance
├── architecture.md # Architecture, module map, request flow
├── env.md # All environment variables
└── sites/
├── facebook.md # Public logged-out Facebook worker-internal routes
├── instagram.md # Instagram worker-internal routes
└── meta.md # Meta Ad Library worker-internal routessrc/sites/ has 11 site adapters (ads_transparency, ebay, facebook,
instagram, linkedin, linktree, meta, threads, tiktok_ads,
tiktok_shop, walmart). Only the three listed above have a doc page — see
architecture.md's "Sites without a doc page" note for the rest.
Governance
- API docs: Generated from OpenAPI. No manually maintained route response tables for public endpoints.
- Worker site docs: Worker-internal routes only. Clearly separated from public API routes.
- Architecture doc: Updated only when module boundaries change (new packages, removed packages, major refactors).
- Env var doc: Updated when settings change in code.
- No legacy references: Remove references to deleted files, old envelope formats, or deprecated endpoints.