Reference Architecture

The Reference Architecture

Read 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 HttpClients 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 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.