diff --git a/CLAUDE.md b/CLAUDE.md
index cb9cfe8..828d5b0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -411,3 +411,13 @@ The codebase currently compiles without warnings on C# 14.
 - Dynamic query endpoints: `Svrnty.CQRS.DynamicQuery.MinimalApi/EndpointRouteBuilderExtensions.cs`
 - gRPC support: `Svrnty.CQRS.Grpc/` runtime, `Svrnty.CQRS.Grpc.Generators/` source generators
 - Sample application: `Svrnty.Sample/` - demonstrates both HTTP and gRPC integration
+
+## GRAPH.md Maintenance
+
+This repo contains a `GRAPH.md` file with unicode cascade diagrams showing the
+architecture. **You MUST update GRAPH.md whenever you**:
+- Add, remove, or rename modules, directories, or major components
+- Change data flow, dependencies, or integration points
+- Modify the public API surface or protocol contracts
+
+Keep the diagrams accurate. They are read by non-technical stakeholders.
diff --git a/GRAPH.md b/GRAPH.md
new file mode 100644
index 0000000..6d86b3d
--- /dev/null
+++ b/GRAPH.md
@@ -0,0 +1,57 @@
+╔══════════════════════════════════════════════════════════╗
+║                  dotnet-cqrs Architecture                ║
+╚══════════════════════════════════════════════════════════╝
+
+ PACKAGE LAYERS
+ ══════════════
+
+ ┌─────────────────────────────────────────────────────┐
+ │              Abstractions (Interfaces)               │
+ │  ICommandHandler<T>  IQueryHandler<T,R>             │
+ │  ICommandDiscovery   IQueryDiscovery                │
+ │  IDynamicQuery<S,D>  IQueryableProvider<S>          │
+ └─────────────────────────┬───────────────────────────┘
+                           │ implements
+ ┌─────────────────────────▼───────────────────────────┐
+ │            Core Implementation                       │
+ │  CQRS (discovery + dispatch)                        │
+ │  DynamicQuery (OData-like filter/sort/group)        │
+ │  FluentValidation (validators → RFC 7807 errors)    │
+ └─────────────────────────┬───────────────────────────┘
+                           │ exposes via
+ ┌─────────────────────────▼───────────────────────────┐
+ │           Protocol / Transport                       │
+ │  MinimalApi ─── HTTP endpoints (auto-mapped)        │
+ │  Grpc ───────── gRPC endpoints (source-generated)   │
+ │  Grpc.Generators ── compile-time codegen            │
+ └─────────────────────────┬───────────────────────────┘
+                           │ optional
+ ┌─────────────────────────▼───────────────────────────┐
+ │           Extended Features                          │
+ │  Events + Events.RabbitMQ ── event sourcing         │
+ │  Sagas + Sagas.RabbitMQ ─── long-running txns       │
+ │  DynamicQuery.EF ────────── Entity Framework        │
+ │  Notifications ──────────── real-time push          │
+ └─────────────────────────────────────────────────────┘
+
+
+ METADATA-DRIVEN ENDPOINT FLOW
+ ══════════════════════════════
+
+ Developer writes handler:
+      ICommandHandler<CreatePersonCommand, PersonResult>
+      │
+      ▼
+ DI registration (AddSvrntyCqrs)
+      │
+      ▼
+ Discovery auto-enumerates all handlers
+      │
+      ▼
+ ┌────┴────────────────────┐
+ │                         │
+ ▼                         ▼
+ HTTP: MapSvrntyCommands()  gRPC: Source Generator
+ POST /api/command/         CommandServiceImpl
+     createPerson           QueryServiceImpl
+                            (compile-time generated)