Governments need digital services that are careful about trust boundaries: country data must stay isolated (Zambia’s systems and secrets must not mix with another country’s); citizen login must never be interchangeable with developer login; and third-party apps must prove they are allowed to call a service (for example, vehicle road-tax / compliance checks) before they get an answer. Most “one big shared backend” designs fail those rules. The hard part is building a reusable platform that still deploys as per-country cells, with real auth, quotas, and audit, not a demo that only works on one laptop.

Boma is a global control plane (contracts, tooling, reusable services) plus country cells (each country gets its own identity realms, edge gateway, bindings, keys, and audit). Sign in with Boma provides Keycloak-backed identity with two separate realms (citizens vs developers). The edge gateway verifies bearer tokens, enforces jurisdiction/quota, meters usage, then forwards OpenAI-compatible requests to a serving engine. Developers register country-scoped API / MCP OAuth clients through the developer control plane. Core contracts use a protobuf service catalog and adapters (e.g. Zambia vehicle compliance via RTSA bindings). I worked primarily on bringing this stack up locally, understanding failure modes (identity ↔ edge dependency, cluster resource pressure), and documenting a reliable startup path so other engineers can run Identity, portals, and Core without tribal knowledge.

• Country cells

  Zambia (ZM) as the first registered cell; no global shared citizen database.

• Dual identity planes

  Citizen realm vs developer realm, separate users, issuers, keys, and scopes.

• Authenticated edge

  Offline JWT verify against cached JWKS; refuses to start without verification keys.

• Usage accounting

  Request-path Postgres writes for quota and ledger consistency.

• Developer self-service

  Register apps that may call Boma APIs / MCP.

• Citizen consent demo

  Approve / decline sharing a basic Boma profile.

• Local full stack

  tilt up deploys Keycloak Operator, Postgres, edge, inference, and portals into minikube.

• Edge crash-looping on JWKS

  Identity down or realm not ready caused connection refused / 404 on certs endpoint; edge refuses to start without keys. Treated identity readiness as a hard dependency, wait for Keycloak + realm import before relying on edge; restart edge after identity stabilizes.

• Cluster resource starvation

  Probe timeouts, Postgres statement timeouts, and Keycloak Operator blocked threads / API timeouts under memory pressure. Tuned Docker Desktop / minikube memory; avoided over-allocating; bounced hot workloads after recovery.

• minikube start vs Docker RAM

  Requesting 8GB when Docker only had ~7.8GB left the cluster stopped and broke kubectl context. Started with a memory size under Docker’s limit; fixed kube context (boma-identity) before rollout commands.

• Onboarding complexity

  Bazel + Tilt + Keycloak + multi-service k8s is hard for new contributors. Wrote practical local startup / walkthrough docs: ports, mental model, cold start vs day-to-day.

Local Identity + Edge + Inference + portals running as a coherent Tilt-managed stack. Clear diagnosis path for the most common production-like failures (auth bootstrap, resource pressure, wrong kube context). Contributor-facing documentation that turns tribal knowledge into a repeatable checklist. Working end-to-end mental model: portals → Sign in with Boma → tokens → edge → serving plane / Core services. Public metrics and production traffic are not available for this portfolio write-up.

1. 1.Auth is a dependency graph, not a checkbox, a gateway that verifies JWTs is only as healthy as the issuer and realm import path behind it.
2. 2.Local k8s fidelity cuts both ways, you catch real probe/timeout/operator issues early, but you must size Docker/minikube honestly or the whole stack thrashes.
3. 3.Country isolation is an architecture choice, cells, separate realms, and per-jurisdiction bindings beat one shared DB with careful queries.
4. 4.Docs are part of the product for platform teams, a short cheat sheet often unblocks more people than another feature branch.

Live project

www.bomalabs.ai/

Demo

bomalabsai-website-main.vercel.app/