---
name: reference-architecture
description: >-
  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.
---

# 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.