agentleFS
daohainamdaohainam/microservice-patterns/CLAUDE.md

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…

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
  1. Very specific:

    Aspire wiring: All services call builder.AddServiceDefaults() (from MicroservicePatterns.ServiceDefaults) which configures OpenTelemetry, …

    line 68

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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 infrastructure
  • Mediator/ — Custom mediator (replaces MediatR after its license change); supports commands, queries, and pipeline behaviors
  • MicroservicePatterns.ServiceDefaults/ — Common OpenTelemetry, health check, and service discovery wiring applied to all services
  • MicroservicePatterns.Shared/ — Shared abstractions used across patterns
  • MicroservicePatterns.DatabaseMigrationHelpers/ — EF Core migration helpers
  • mcp/ — Model Context Protocol servers exposing pattern services as LLM tools
  • tests/ — Integration and unit tests

Patterns implemented

PatternDirectoryKey services
CQRSpatterns/CQRSBookService, BorrowerService, BorrowingService, BorrowingHistoryService (read model), Blazor frontend
Event Sourcingpatterns/EventSourcingAccountService (banking), NotificationService
Saga – Orchestrationpatterns/Saga/TripPlannerCentral orchestrator coordinates steps
Saga – Choreographypatterns/Saga/OnlineStoreServices react to events without a central coordinator
Transactional Outboxpatterns/TransactionalOutboxPolling + CDC/Debezium variants
Webhook / CloudEventspatterns/WebhookDeliveryService, DispatchService, EventConsumer
BFFpatterns/BFFProductCatalogService, SearchService (Elasticsearch), BackendForPOS
Identitypatterns/IdentityOpenIddict + ASP.NET Core Identity; Authorization Code + PKCE, Client Credentials, Refresh Token
Idempotent Consumerpatterns/IdempotentConsumerCatalogService tracks callId header; DB constraint prevents duplicates
Resiliencepatterns/ResilienceCircuit 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 migrations

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 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 using directives
  • 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 null at entry points only; use is 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.