ahtishamshahzad/agent_dev_flow/backend-deployment

Backend Deployment

Purpose

Get the backend into environments safely and repeatably: chosen target, disciplined artifacts, migration ordering, health-checked rollout, and a rollback that's been thought through before it's needed. Actual deploys/publishes are outward-facing — explicit approval (../../release-planning, Gate 7).

When to Use

• When planning how/where the backend runs (staging/production) or changing the deploy pipeline.
• Not for release go/no-go itself (../../release-planning) or store/app publishing.

Inputs

• Deployment target constraints/preferences (PaaS, containers on cloud, VMs) — a stack decision needing approval.
• Env/secret model (../../environment-audit), DB migration flow (../../database/database-migrations), async surfaces (queues, scheduled-jobs).

Discovery Questions

• What target fits the team's ops capacity (managed PaaS vs orchestrated containers vs VMs)?
• How many environments, and what differs between them (config only, ideally)?
• What's the rollout policy — can the product tolerate seconds of downtime, or is zero-downtime required?
• Do workers/schedulers deploy with the API or separately (queues says separately)?

Responsibilities

• Recommend the target on requirements + ops capacity, with trade-offs, for approval.
• Artifact discipline: one immutable build (container image or equivalent) promoted across environments — never rebuilt per environment; config/secrets injected at runtime (backend-security), validated at boot (fail fast, before traffic).
• Migration ordering: migrations run as a deploy step before new code serves traffic; expand→migrate→contract for zero-downtime schema change (../../database/database-migrations owns the pattern) — old code must survive the new schema during rollout.
• Rollout: readiness-gated (only healthy instances get traffic — backend-observability checks), rolling/blue-green per target capability; graceful shutdown (drain requests, finish/release jobs — queues).
• Async surfaces: workers and schedulers as separately deployable processes; deploy order vs migrations considered for them too.
• Rollback: previous artifact redeployable in minutes; know which migrations are roll-forward-only and what that means for reverting (usually: fix forward for schema, roll back code).
• Pipeline: CI gates (tests, ../../security-review hooks) before deploy; deploy actions logged; production deploys approved per ../../../system/QUALITY_GATES.md.

Required Workflow

1. Recommend target + environment topology; get approval.
2. Define artifact build + promotion flow.
3. Define config/secret injection + boot validation.
4. Sequence migrations vs code rollout (API, workers, schedulers).
5. Define health-gated rollout + graceful shutdown + rollback runbook.
6. Wire CI gates; record the deploy/rollback procedure.

Decision Rules

• Prefer the most managed target that meets requirements — ops burden is a permanent tax.
• Same artifact in staging and production; environment differences live in config only.
• A migration that old code can't run against blocks zero-downtime rollout — split it (expand/contract) or accept and record downtime.
• Rollback plans that were never rehearsed are hopes; rehearse in staging.

Rules

• No deploy/publish without explicit approval; staging first.
• Secrets never bake into artifacts or logs.
• Every production deploy has: approver, artifact ID, migration list, rollback step — recorded.

Anti-Patterns

• Building on the production box / rebuilding per environment.
• Running migrations manually "when someone remembers."
• Deploying new code before its migration (or a contracting migration before old code is gone).
• Killing workers mid-job on deploy (no drain).
• Rollback = "restore yesterday's DB backup" as the primary plan.

Validation Checklist

• [ ] Target recommended with trade-offs; approved.
• [ ] Immutable artifact promoted across environments.
• [ ] Config validated at boot; secrets runtime-injected.
• [ ] Migration ↔ rollout ordering safe (expand/contract where needed).
• [ ] Health-gated rollout + graceful shutdown incl. workers/schedulers.
• [ ] Rollback runbook exists and was rehearsed.
• [ ] CI gates + approval flow wired.

Definition of Done

A recorded, approved deployment design — target, artifact flow, config/secret handling, safe migration ordering, health-gated rollout for API and async processes, rehearsed rollback — with production deploys gated on explicit approval.

Related Skills

../../release-planning, ../../environment-audit, ../../database/database-migrations, ../../database/backup-recovery, backend-observability, queues, scheduled-jobs, backend-security, ../../github-repository (CI/CD residence).

Related Knowledge

../../../knowledge/ (ops capacity, environment topology, downtime tolerance).

Related References

../../../references/backend/deployment/ (runbooks, when populated).

Context Loading Guidance

• Requires: target constraints, env/secret model, migration flow, async inventory.
• Does not require: application feature code, endpoint detail.
• May load: ../../database/database-migrations (ordering), ../../release-planning (gate).
• Stop when: the deploy design + rollback runbook are recorded and approvals wired.

Token Efficiency Guidance

The deploy sequence diagram (build → migrate → roll API → roll workers) plus the rollback runbook are the artifacts; skip cloud-vendor feature tours.