# Fetcha — repository guide

Fetcha (www.fetcha.co) is "Intelligent Web Access Infrastructure": one API (POST /v1/fetch) that routes web requests across upstream proxy networks (Oxylabs, Decodo, SOAX — never exposed to customers) with smart routing, retries, sticky sessions, usage metering and a full dashboard.

# Layout

• apps/web — Next.js 16 (marketing site, docs, auth, customer dashboard, admin). Port 8220. Proxies /v1/* to the API.
• apps/api — Fastify API service (public /v1/*, /health, /ready, internal /internal/* for the dashboard). Port 8221.
• packages/core — zod schemas, error codes, ids/api-key hashing, SSRF policy, geo model, plan limits.
• packages/db — Drizzle schema + migrations (drizzle/), pnpm db:generate|migrate|seed.
• packages/providers — ProxyProvider interface + adapters (oxylabs, decodo, soax, direct). Provider code lives ONLY here.
• packages/routing — circuit breaker, routing score, FetchExecutor (attempt loop, block detection, escalation).
• packages/email — Resend abstraction + React Email templates. packages/sdk (JS), sdk-python/ (Python).
• docs/AGENT-BRIEF.md — product/engineering rules used when generating UI.

# Rules

• Never expose provider names, credentials or provider error text to customers. Public debug output uses aliases (network-a/b/c).
• Every external URL goes through assertUrlAllowed() (SSRF) — including redirects.
• Business logic in server actions / apps/api / packages, not in React components.
• API keys: shown once, SHA-256 stored. Request IDs req_… on every response (X-Fetcha-Request-ID).
• Not implemented yet (say so, don't fake): browser mode, /v1/extract, Stripe checkout, teams, webhook delivery, OAuth, 2FA.

# Dev

cp .env.example .env (fill provider creds + RESEND_API_KEY), createdb fetcha, pnpm db:migrate && pnpm db:seed, pnpm dev:api + pnpm dev:web. Tests: pnpm test. Dev seed: cd scripts && npx tsx dev-seed.ts you@example.com prints an API key.

# Deploy (MacLustr)

Deployed by mld (gateway M1M32) on M3U96a: web 8220 + api 8221, Postgres 17 fetcha + Redis local, ngrok www.fetcha.co. Manifest: deploy/fetcha.mld.json → M1M32:~/dispatch/apps/fetcha.json. See deploy/README.md.