microservice-patterns
CLAUDE.md331 starsChanged 18 months agoMITView on GitHub
A collection of focused, production-inspired demos showing how to implement complex microservice patterns on .NET 10 using .NET Aspire 13. The goal is pattern clarity over domain realism — keep it teachable and minimal. Prerequisites: .NET SDK (10.0+), .NET Aspire workloads, Docker (for PostgreSQL, Kafka, Redis, etc. — all managed by Aspire). Typical service layout: Aspire wiring: All services call builder.AddServiceDefaults() (from MicroservicePatterns.ServiceDefaults) which configures OpenTelemetry, health checks, and service discovery. External resources (databases, Kafka, Redis) are declared in AppHost/Program.cs…
In this repositoryOne other file it gives its agents.
- .github/copilot-instructions.mdCopilot instructions
The file
We split this CLAUDE.md into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 68
Aspire wiring: All services call builder.AddServiceDefaults() (from MicroservicePatterns.ServiceDefaults) which configures OpenTelemetry, …
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
What this repo is
A collection of focused, production-inspired demos showing how to implement complex microservice patterns on .NET 10 using .NET Aspire 13. The goal is pattern clarity over domain realism — keep it teachable and minimal.
Build & run
dotnet restore
dotnet build
# Run all services via Aspire orchestration
dotnet run --project MicroservicePatterns.AppHost
# Run tests
dotnet test tests/IntegrationTests/IntegrationTests.csproj
dotnet test tests/Saga.UnitTests/Saga.UnitTests.csproj
# Run a single test
dotnet test tests/Saga.UnitTests/Saga.UnitTests.csproj --filter "FullyQualifiedName~MyTestName"Prerequisites: .NET SDK (10.0+), .NET Aspire workloads, Docker (for PostgreSQL, Kafka, Redis, etc. — all managed by Aspire).
Solution structure
MicroservicePatterns.AppHost/— Aspire AppHost: orchestrates all services, provisions containers (PostgreSQL, Kafka, Redis, Prometheus, Grafana, OpenTelemetry Collector)patterns/— One folder per pattern (see below)EventBus/,EventBus.Kafka/— Integration event publishing infrastructureMediator/— Custom mediator (replaces MediatR after its license change); supports commands, queries, and pipeline behaviorsMicroservicePatterns.ServiceDefaults/— Common OpenTelemetry, health check, and service discovery wiring applied to all servicesMicroservicePatterns.Shared/— Shared abstractions used across patternsMicroservicePatterns.DatabaseMigrationHelpers/— EF Core migration helpersmcp/— Model Context Protocol servers exposing pattern services as LLM toolstests/— Integration and unit tests
Patterns implemented
| Pattern | Directory | Key services |
| CQRS | patterns/CQRS | BookService, BorrowerService, BorrowingService, BorrowingHistoryService (read model), Blazor frontend |
| Event Sourcing | patterns/EventSourcing | AccountService (banking), NotificationService |
| Saga – Orchestration | patterns/Saga/TripPlanner | Central orchestrator coordinates steps |
| Saga – Choreography | patterns/Saga/OnlineStore | Services react to events without a central coordinator |
| Transactional Outbox | patterns/TransactionalOutbox | Polling + CDC/Debezium variants |
| Webhook / CloudEvents | patterns/Webhook | DeliveryService, DispatchService, EventConsumer |
| BFF | patterns/BFF | ProductCatalogService, SearchService (Elasticsearch), BackendForPOS |
| Identity | patterns/Identity | OpenIddict + ASP.NET Core Identity; Authorization Code + PKCE, Client Credentials, Refresh Token |
| Idempotent Consumer | patterns/IdempotentConsumer | CatalogService tracks callId header; DB constraint prevents duplicates |
| Resilience | patterns/Resilience | Circuit Breaker (Closed → Open → Half-Open) |
Architecture conventions
Typical service layout:
[Pattern]/[ServiceName]/
├── Program.cs # DI registration and Aspire integration
├── Api/ or Endpoints/ # Minimal API route handlers
├── Services/ or Handlers/ # Business logic, command/query handlers
├── Models/ or Dtos/ # Domain models and data transfer objects
├── Infrastructure/ # EF DbContext, event bus adapters
└── Migrations/ # EF Core migrationsAspire wiring: All services call builder.AddServiceDefaults() (from MicroservicePatterns.ServiceDefaults) which configures OpenTelemetry, health checks, and service discovery. External resources (databases, Kafka, Redis) are declared in AppHost/Program.cs and injected via Aspire resource references.
Event bus: Services publish integration events via IEventBus (in-memory default) or IKafkaEventBus (Kafka). Subscribers implement IIntegrationEventHandler<T>.
Mediator: Commands implement ICommand / ICommand<TResult>, queries implement IQuery<TResult>. Handlers are registered via DI. Pipeline behaviors wrap handlers for cross-cutting concerns.
Database: PostgreSQL everywhere. EF Core with migrations. The Idempotent Consumer pattern uses a unique DB constraint on the processed-message ID rather than application-level locking.
C# coding style
From .github/copilot-instructions.md — follow these in all C# code:
- C# 13 features preferred
- File-scoped namespace declarations; single-line
usingdirectives - Newline before opening
{of any block (if,for,using,try, etc.) - Pattern matching and switch expressions over chains of
if/else nameof(...)instead of string literals for member names- Nullable reference types: declare non-nullable by default, check
nullat entry points only; useis null/is not null(never== null) - XML doc comments on all public APIs; include
<example>and<code>where applicable - Tests: xUnit SDK v3 + Moq; no "Arrange/Act/Assert" comments; match capitalization style of nearby test files
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

