0004: Host the API on Vercel
Status: accepted by the owner (Oct 15, 2026). Includes known risks, listed below.
Context
The PRD originally assumed Docker on AWS. The candidates were Vercel and DigitalOcean. Vercel now supports backend workloads: NestJS deploys as a Vercel Function with no configuration, and Daemons run long-lived worker containers, with BullMQ named as a supported use.
Decision
- The HTTP API runs as a Vercel Function (Fluid compute). The entrypoint is
src/main.ts. - Queue workers (milestone 6) run as Vercel Daemons, pulling jobs from Redis through BullMQ.
- The web app stays on Vercel. One platform for both keeps deploys, logs and rollbacks together.
- Redis and PostgreSQL are external services (Neon for PostgreSQL).
Risks we are accepting
| Risk | Why it matters | Mitigation |
|---|---|---|
| Daemons are in public beta | The PRD targets 99.5% monthly availability, and workers send reminders and process captures | Make every job idempotent and retryable. Keep the Dockerfile so the same worker image can move to another host. Re-evaluate before launch |
Daemons run in production only (no preview deployments, no vercel dev) | Worker changes cannot be previewed | Run workers locally with Docker against the docker-compose services. Test the queue logic with automated tests |
| No autoscaling for Daemons | A burst of captures queues up instead of scaling out | Set the replica count deliberately. Track queue depth |
| Many instances, each with a connection pool | Can exhaust the database’s connection limit | DB_POOL_MAX defaults to 5. Use the pooled connection string |
| Function limits (duration, bundle size) apply to the API | Long requests are cut off | Slow work goes on the queue by design. Prisma 7 with the pg adapter keeps the bundle small |
| Region | Users are in Nigeria; no Vercel region is nearby | Choose the closest region and measure the 300 ms p95 target early |
Consequences
- Deploying the API needs no Docker. The Dockerfile in the API repo is for local use and for the worker image.
- WebSockets are not used anywhere in the design, so their absence from Vercel’s docs does not matter.
- If the beta limits prove too tight, the workers can move to a container host without changing the code, because they only need Redis and PostgreSQL.
Last updated on