https://swbanga.com/ Designing and building secure, scalable, cloud-native platforms — multi-cloud architectures (Azure & GCP), immutable financial systems (.NET 10), and Zero-Trust healthcare APIs (FastAPI). en Fri, 28 Aug 2026 18:26:46 GMT generate-llms-txt.mjs (sprint 08) super@swbanga.com (Super Washington Banga) https://swbanga.com/blog/deploying-fastapi-azure-container-apps/ https://swbanga.com/blog/deploying-fastapi-azure-container-apps/ Tue, 04 Aug 2026 00:00:00 GMT How Med-Core's FastAPI API ships to Azure Container Apps: a Terraform module with min-replicas zero, KEDA-driven scale-up, and the cold-start budget that makes scale-to-zero the default deployment posture. fastapi azure-container-apps terraform scale-to-zero postgresql az containerapp update --name med-core-api --resource-group med-core-rg --image $REGISTRY/$IMAGE:${{ github.sha }} ``` The short SHA is the revision tag, so every commit maps to a reproducible image and the container app's revision history doubles as a deploy ledger. ## Database migrations at startup The API owns its schema. Running migrations as part of the startup path removes a whole class of "migrated in prod, not in the deploy" drift, but it has to be safe against the scale-to-zero lifecycle: a cold start can hit a revision that has been sleeping since before the last migration shipped. ```python import asyncio import asyncpg async def wait_for_database(url: str, attempts: int = 10, delay: float = 2.0) -> None: """Block startup until Postgres is reachable, then let Alembic catch up.""" for attempt in range(attempts): try: conn = await asyncpg.connect(url, timeout=5) await conn.close() break except (OSError, asyncpg.PostgresError): if attempt == attempts - 1: raise await asyncio.sleep(delay) ``` The retry loop exists because on a cold start the database container can still be coming up — PostgreSQL on the same Container Apps environment does not inherit the API's zero-replica sleep schedule. After the loop succeeds, `alembic upgrade head` runs synchronously before uvicorn binds the port, so the readiness probe only ever sees a migrated service. ## Verifying scale-to-zero Scale-to-zero is only real when it is observed. The deployment log records the first verified run: zero replicas through the overnight window, KEDA scaling up within one polling interval of the first morning request, and a cost graph with zero compute hours for the idle period. ```bash az containerapp show \ --name med-core-api \ --resource-group med-core-rg \ --query "properties.template.scale.minReplicas" # 0 ``` The `az` query is now part of the deploy checklist — a revision is not considered shipped until the console confirms the posture stuck. ## The cold-start budget The first request after idle took 8.4s versus 320ms warm. The JWT key cache had dropped with the replica, adding a Key Vault round trip to startup. Scale-to-zero buys the cost line; the tax is latency on the first request after sleep. The fix is not to abandon scale-to-zero — it is to budget for it. The cold start is tracked as a first-class deploy metric, and the warm-up strategy changed so health probes prime the JWT cache instead of waiting for request traffic. An 8.4s first request is acceptable for an intake API behind a queue; it would not be for a user-facing page, and the budget should be set per workload, not globally. ## What to watch next The full timeline — the deploy, the 02:00 zero-replica confirmation, and the 09:12 KEDA warm-up — is in the scale-to-zero deployment log in the journal, and the platform trade-off analysis lives in the architecture vault's Azure Container Apps decision record. The next revision's open question is whether the worker's scale-in delay should linger longer than the API's, so the cold-start budget stays a queue-latency concern and never becomes an API-latency one.]]> https://swbanga.com/journal/aca-scale-to-zero-deployment-log/ https://swbanga.com/journal/aca-scale-to-zero-deployment-log/ Mon, 03 Aug 2026 00:00:00 GMT Deployment log for the first verified scale-to-zero run on Azure Container Apps: zero replicas overnight, KEDA-triggered warm-up on the first request, and the cold-start latency budget observed before and after. deployment-log Scale-to-zero works as the standard posture: zero idle cost, bounded cold-start budget, and a reproducible warm-up path. The cold-start metric is now part of the deploy checklist for every revision. ## Follow-ups - Prime caches with a health-probe warm-up instead of waiting for request traffic. - Tune the scale-in delay per workload; the worker wants a longer linger than the API. - Distinguish cold-start latency from regressions in the dashboards (ADR-003 open question).]]> https://swbanga.com/architecture/adr-003/ https://swbanga.com/architecture/adr-003/ Sat, 01 Aug 2026 00:00:00 GMT Adopt Azure Container Apps scale-to-zero as the standard deployment posture for background workers and non-critical APIs: minimum replicas of zero, HTTP-triggered scaling for APIs, and event-driven KEDA triggers for queue workers. med-core ledger-core azure container-apps scale-to-zero First request after idle pays for dropped in-memory caches — the JWT key cache adds a Key Vault round trip on startup. Warm-up probes and cache priming must be part of the same change, or the latency budget moves. ## Open questions - Scale-in delay: how long should idle replicas linger before the KEDA trigger releases them, and how is that tuned per workload? - Which paths are latency-critical enough to opt out of scale-to-zero? Ledger settlement is the early candidate. - What monitoring signal distinguishes a cold start from a regression, given that first-request latency is now a first-class metric?]]> https://swbanga.com/journal/redis-idempotency-tuning/ https://swbanga.com/journal/redis-idempotency-tuning/ Sat, 01 Aug 2026 00:00:00 GMT Post-mortem on a retry storm that pushed 12 duplicate outbox deliveries through Redis: the TTL mismatch, the idempotency-key fix, and the monitoring gap that hid it for three hours. postmortem Duplicate-key rejections are now a first-class alert metric. The storm was visible in the event log, but nobody was watching the log. ]]> https://swbanga.com/journal/med-core-jwt-race-condition/ https://swbanga.com/journal/med-core-jwt-race-condition/ Thu, 30 Jul 2026 00:00:00 GMT Post-mortem on a race condition where concurrent requests replayed an un-scoped JWT through the middleware, and the fix that moved scope validation into the request pipeline where it belongs. postmortem Receipt: ... ``` The regression test uses an `asyncio.Barrier` to line up both requests inside the middleware, so the race fails deterministically if it ever returns: ```python await asyncio.gather(issue_request(token, barrier), issue_request(token, barrier)) ``` The scope-in-middleware gap was flagged in the sprint review but never filed, so the fix shipped a sprint late. Review findings now get a ticket before the sprint closes — no exceptions. ]]> https://swbanga.com/journal/med-core-sprint-01/ https://swbanga.com/journal/med-core-sprint-01/ Tue, 28 Jul 2026 00:00:00 GMT Retrospective on the first sprint of Med-Core: the PHI boundary, what the OAuth2/JWT flow taught us, and the three lessons that will shape Sprint 02. retrospective Reviewing the Terraform diff in the same PR as the app code caught a public egress rule before it ever reached Azure. ## What broke The first deployment to Azure Container Apps missed the scale-to-zero configuration, so the intake worker stayed hot overnight. Worse, JWT scope validation was enforced in the calling client instead of the request middleware — a client could mint scoped tokens the API never re-checked. Both were fixed in the same week, but only the container fix had a ticket.]]> https://swbanga.com/architecture/adr-002/ https://swbanga.com/architecture/adr-002/ Sat, 25 Jul 2026 00:00:00 GMT Build Med-Core on FastAPI with async request handlers. Pydantic models validate payloads before encryption, dependency injection enforces scope authorization in the pipeline, and the async runtime keeps PHI payloads out of blocking I/O paths. med-core fastapi python phi Receipt: await limiter.acquire("intake", key=payload.patient_id) encrypted = encrypt_phi(payload.model_dump()) return await store.record(encrypted) ``` Plaintext PHI exists only inside the request handler. Anything that leaves the handler — queue messages, audit events, logs — carries the encrypted payload, never the model. ## Async under load Synthetic intake bursts previously serialized on thread-pool scheduling. Async handlers keep the event loop free during Redis round trips and Postgres commits, and the rate limiter throttles per patient instead of per connection, which is what the burst tests actually exercise.]]> https://swbanga.com/journal/ledger-core-sprint-01/ https://swbanga.com/journal/ledger-core-sprint-01/ Thu, 23 Jul 2026 00:00:00 GMT Retrospective on the first sprint of Ledger-Core: what shipped, what broke, and the three lessons that will shape Sprint 02. retrospective Writing the integration test before the engine kept every step of the sprint anchored to a measurable target. ## What broke The CSV importer assumed one currency per account. Three accounts in the legacy data violated that, and the failure surfaced only at the boundary tests. The fix was a schema guard — the same lesson as this site's content pipeline.]]> https://swbanga.com/architecture/adr-001/ https://swbanga.com/architecture/adr-001/ Tue, 21 Jul 2026 00:00:00 GMT Adopt PostgreSQL 16 as the Ledger-Core immutable store. Rows are never updated or deleted after settlement; mutations append versioned records, and the write path is wrapped in serializable transactions so reconciliation can replay the ledger from a single snapshot. ledger-core postgresql database immutability Superseded at Ledger-Core v1.0: the ledger store and outbox run on Azure SQL Edge / SQL Server with EF Core 10 — the PostgreSQL prototypes were replaced after managed-SQL Edge parity testing. See the related Ledger-Core case study for the current architecture; this record documents the superseded decision. ## Why not SQL Server SQL Server is a strong operational database, but the Ledger-Core constraints worked against it: the engine must run on Linux containers without a licensing surface, the append-only write pattern maps poorly to row-level locking and page-fill habits, and the reconciliation pipeline needs raw visibility into transaction and WAL semantics. The legacy-license argument lost to the container-first deployment posture. ## The immutable write path Rows are versioned, never overwritten. A check constraint guards the version sequence so a concurrent writer cannot silently clobber a settled entry: ```sql CREATE TABLE ledger_entries ( id BIGSERIAL PRIMARY KEY, version INT NOT NULL CHECK (version > 0), account_id UUID NOT NULL, amount NUMERIC(19, 4) NOT NULL, settled_at TIMESTAMPTZ, audit_json JSONB, UNIQUE (account_id, version) ); ``` Reconciliation replays the ledger from a single snapshot: every mutation appends a new version instead of touching prior rows, so the replay is a linear scan with no history table to maintain. ## Replay and audit Because the store is append-only, the auditor's view is a pure function of the WAL and the versioned table — no temporal extensions, no triggers, no shadow tables. The cost is that all replay logic is application-owned: the serializable-transaction write path is the sole writer, and anything that bypasses it breaks the audit chain.]]> https://swbanga.com/blog/build-time-validation/ https://swbanga.com/blog/build-time-validation/ Tue, 21 Jul 2026 00:00:00 GMT Frontmatter validation at build time catches authoring errors before they reach production — here is the pattern and its guarantees. ssg nextjs Build-time validation protects *frontmatter*, not the rendered page. It only runs during `next build` — nothing is validated at runtime in a static site. ## What you get - A build that fails loudly with the file path and the offending field - A single canonical field contract for every content type - No runtime cost: the validator executes once, at build time]]> https://swbanga.com/architecture/adr-000/ https://swbanga.com/architecture/adr-000/ Sat, 18 Jul 2026 00:00:00 GMT Store all content as MDX files under /content with YAML frontmatter validated by strict Zod schemas at build time. Invalid or missing fields fail the static export with an explicit error naming the file and field. mdx zod static-export The FastAPI backend and dynamic AI APIs are deferred to V2. Everything in V1 compiles to static HTML at build time. Adopt `next-mdx-remote` for MDX compilation and `zod` for frontmatter validation. The parser lives in `src/lib/mdx.ts`: ```ts const parsed = CONTENT_SCHEMAS[contentType].safeParse(file.data); if (!parsed.success) { throw new Error( `Invalid frontmatter in ${filePath}:\n${formatZodIssues(parsed.error)}`, ); } ``` ## Enforcement The build becomes the enforcement point: a missing `summary` or a mistyped `publishedat` aborts the export before it reaches Cloudflare.]]>