How Neo runs

Process roles

PROCESS_ROLE=all serves HTTP and polls the durable worker. web serves HTTP without worker polling. worker runs the worker without accepting the normal application surface. The current deployment may use one all instance; PostgreSQL claims and advisory locks provide the foundation for later separation.

flowchart LR
  Proxy[HTTPS proxy] --> Web[web or all process]
  Web --> DB[(PostgreSQL)]
  Worker[worker or all process] --> DB
  DB --> Worker
  Worker --> Providers[Meta, PSP, courier]
  Web --> Pages[Public and protected pages]

Host routing

All origins can route to one container. In production, specialized origins are derived from the public origin when a deployment console leaves them equal. Explicit distinct origins win. The legacy shopwithneo.com host permanently redirects only after the candidate route, DNS, and certificate are healthy. Local development remains one-origin and exposes documentation under /docs.

Health and graceful shutdown

/health reports liveness and a deliberately limited beta summary. /ready executes a database query. Queue and provider health have separate endpoints. The Docker health check uses readiness.

On termination, the server stops accepting new work, clears the worker timer, waits for an in-flight worker pass, closes the HTTP listener, and then closes the database. Readiness is the correct deployment gate because a live process without database access cannot serve the system safely.

Evidence and tests

• src/dev-server.ts
• src/env.ts
• Dockerfile
• docs/DEPLOY_COOLIFY.md
• test/web.test.ts
• test/env.test.ts
• test/phase2-postgres-runtime.test.ts