- 07 · Reference
Repository map
Where each layer lives. Every directory below is linked to its source; the ones with their own page here are linked to that instead.
Layout #
production-infra-blueprint/
├── Makefile the single entrypoint — every target
├── README.md .env.example .pre-commit-config.yaml
│
├── services/ Gradle multi-project, one Dockerfile for both services
│ ├── platform/ correlation ids, problem details, event contracts, drain, span filter
│ ├── api/ REST, schema owner, cache-aside, outbox writer and relay, reconciler
│ └── worker/ Kafka consumer: idempotency guard, bounded retry, dead-letter topic
│
├── deploy/
│ ├── compose/ the local stack, observability overlay, podman overlay
│ └── k8s/ base, config, data, migrations, overlays, restore, infrastructure
├── clusters/prod/ what Flux reconciles, and in what order
│
├── infra/
│ ├── terraform/ modules: network, firewall, node, storage, dns · envs/prod
│ └── ansible/ roles: base, hardening, storage, k3s
│
├── observability/ prometheus, alertmanager, loki, alloy, tempo, grafana — one set, two environments
├── load/k6/ steady and rollout profiles
├── scripts/ bootstrap, smoke test, both drills, render and verify helpers
├── .github/workflows/ ci, security, build, drills — delivery pipeline
├── .semgrep/ rules specific to this repository
│
├── docs/
│ ├── architecture.md security.md operations.md slo.md cost-analysis.md
│ ├── adr/ 0001 – 0010
│ └── runbooks/ written for whoever is on call
│
└── site/ this site, rendered from the files above
What to look at first #
docs/cost-analysis.md
Every footprint with its method, and the monthly bill against two AWS builds, line by line.
docs/operations.md
What fits on the node, the connection budget, schedules, and what has not yet run live.
docs/security.md
Controls layer by layer, the admission test results, and the known gaps.
docs/adr/
The close calls, including the ones that cost something — ADR 0004 on Kafka above all.
services/api/src/main/java/dev/tahir/blueprint/outbox/
The transactional outbox and its relay: why a broker outage cannot corrupt state or take the API down.
scripts/zero-downtime-drill.sh
The zero-downtime claim, tested by causing a rollout under load. Weekly in CI.
scripts/restore-drill.sh
The point-in-time restore claim, tested by destroying the database. Weekly in CI.
observability/prometheus/tests/
Unit tests showing when every alert fires, and when it stays quiet.
.semgrep/blueprint.yml
Five rules encoding invariants this system depends on.