API + DB + Worker

Use this when your stack has synchronous API calls and asynchronous background jobs sharing one database.

Baseline config

{
  "services": {
    "db": {
      "cmd": ["postgres", "-D", "./var/db"],
      "port": 5432,
      "ready": {"type": "tcp"}
    },
    "api": {
      "cmd": ["go", "run", "./cmd/api"],
      "dependsOn": ["db"],
      "port": 3000,
      "ready": {
        "type": "http",
        "url": "http://127.0.0.1:3000/health"
      }
    },
    "worker": {
      "cmd": ["go", "run", "./cmd/worker"],
      "dependsOn": ["db"]
    }
  }
}

Why it works

• DB startup is isolated and gated by TCP readiness.
• API and worker share one hard dependency (db) and can start in parallel afterward.
• API readiness prevents downstream consumers from racing an unready endpoint.

Common adjustments

• add session.bind and session.token when you need remote TUI access
• add service-specific logView.maxEntries for chatty workers
• use stopCmd for graceful job-drain before shutdown

Failure modes

• API depends on worker and worker depends on API: cycle
• DB has no readiness gate: API starts too early and fails repeatedly
• worker declared as dependency for API even when not required for API startup

For readiness and dependency details, see Readiness and Startup Waves.