# Reference Architecture

> Use when designing a new service or judging an existing repo against the estate's architecture. The 15 numbered principles (P1-P15) and the compliance checklist: Aspire AppHost as composition root, shared kernel not shared domain, service and database per bounded context, migrated persistence, environment configuration with platform secrets, one container per service, cost-shaped Fly.io topology, degrading optional dependencies, Program.cs as a manifest, interface-plus-registration extensibility, anti-corruption at the edge, tag-driven CI/CD, testing at the layer that holds the logic, in-repo documentation, and observability as a build-time decision. Read this before re-deriving any architectural rule.

- Skill: `konradcinkusz/reference-architecture` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add konradcinkusz/reference-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/konradcinkusz/reference-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: konradcinkusz (https://skillmd.com/u/konradcinkusz)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/konradcinkusz/reference-architecture

---


# The Reference Architecture

**Read [`references/00-REFERENCE-ARCHITECTURE.md`](references/00-REFERENCE-ARCHITECTURE.md) before applying any of this.**
That file is the standard; everything below it is a summary to help you decide
whether this skill applies and to check your work afterwards.

Reference-architecture principles: P1-P15.

## What this standard covers

- How worked examples are cited
- The shape in one picture
- Principles
- Where the two repositories disagree, and who wins
- Known open deviations
- Deliberate non-goals of this blueprint

## Checklist

Any service claiming to follow this blueprint answers yes to all of these:

- [ ] Declared in the AppHost with `WithReference`, `WaitFor` and `WithHttpHealthCheck`
- [ ] Calls `AddServiceDefaults()` and `MapDefaultEndpoints()`
- [ ] Exposes `/health` and `/alive`; the platform health check points at `/health`
- [ ] Emits OTLP traces, metrics and logs
- [ ] Owns its database; no other service connects to it
- [ ] Schema applied by `MigrateAsync` from provider-specific migrations, in a hosted service
- [ ] All configuration from environment variables; no secret in source, config file, or comment, with a secret scanner in CI
- [ ] Exactly one service holds a signing key; all others validate against its JWKS endpoint
- [ ] The shared kernel holds no entity, DTO, enum, seed dataset, pricing constant or user-facing string — asserted by an architecture test and a CI size check
- [ ] Every optional integration has a working no-op or fallback
- [ ] The health endpoint reports the state of every optional integration, and the startup banner prints the same list
- [ ] Multi-stage Dockerfile; runtime image major version equals the TFM major version; listens on `:8080`; non-root where the base image allows
- [ ] One `fly.toml`; `min_machines_running = 1` if another service calls it in-request
- [ ] Outbound `HttpClient`s carry the standard resilience handler with explicit timeouts
- [ ] `Program.cs` is a manifest; wiring is in `ServiceCollectionExtensions`
- [ ] Extension points are interfaces registered in DI, not base classes
- [ ] Has a test project; the logic-bearing layer is covered. When behaviour is being *migrated*, its characterisation tests are written before the move, not after
- [ ] Built by the tag-driven workflow with path-based change detection
- [ ] Its architectural decisions are recorded in `docs/`

---

---

Generated from [`docs/architecture/00-REFERENCE-ARCHITECTURE.md`](https://github.com/konradcinkusz/architecture-standards/blob/main/docs/architecture/00-REFERENCE-ARCHITECTURE.md) by `scripts/build-marketplace.mjs`. Do not edit this file: change the source document, or its entry in `catalog/marketplace.catalog.json`, and re-run the generator.