Compendium

A pragmatic .NET framework for building event-sourced, multi-tenant SaaS applications.

Compendium is the framework that powers Nexus, Sassy Solutions' multi-tenant platform engineering product. It distills years of building event-sourced SaaS into a small set of focused packages: DDD primitives, CQRS handlers, an event store, multi-tenancy, and ready-to-use adapters for PostgreSQL, Redis, Zitadel, and more.

Why Compendium?

• Zero-dependency Core — Pure DDD primitives (AggregateRoot<TId>, ValueObject, Result<T>, Error) with no external dependencies beyond the .NET BCL.
• CQRS + Event Sourcing built-in — Command/query dispatchers, event store interfaces, and a PostgreSQL adapter wired out of the box.
• Sagas, two flavors — ProcessManager<TState> for DDD-style orchestration sagas and IHandle<TEvent> for event-driven choreography sagas, each clearly named so you don't have to guess which pattern you're using. See docs/sagas.md.
• Multi-tenancy native — Tenant context, resolution, and scoping baked into the primitives — not bolted on.
• Result pattern everywhere — No control-flow exceptions. Every fallible operation returns Result<T> with structured Error values.
• Modular adapters — Pick only what you need: twenty-two production adapters across persistence (Postgres, Redis, pgvector, Qdrant, Pinecone, S3-compatible), identity (Zitadel), billing (Stripe, LemonSqueezy), email (Listmonk), and AI (OpenRouter, OpenAI, Anthropic, Gemini, Mistral, DeepSeek, Mercury, Hugging Face, Azure OpenAI, AWS Bedrock, LiteLLM, Ollama). See Adapters. Each ships its own repo, NuGet package, and release cadence per ADR-0006.
• Battle-tested in production — Powers Nexus, a multi-tenant platform engineering product.

Architecture

Compendium lets you adopt CQRS and event sourcing without marrying an infrastructure: a zero-dependency core holds the domain primitives, narrow port packages define every integration surface, and vendor adapters live outside the framework — chosen, and replaceable, at composition time. Dependency direction is enforced by architecture tests, and every package ships on its own release train through provenance-gated CI.

• Architecture overview — the problem, the central principle, the boundaries, and the known limits (stated, not hidden).
• C4 diagrams — context, containers, and components, faithful to the code as it is.
• Architecture Decision Records — 13 MADR records, from the Result pattern and the zero-dependency core to release trains and event serialization.

Adapters

Each public adapter lives in its own repository under sassy-solutions/compendium-adapter-* and is released independently per ADR-0006. The framework defines the ports (IEventStore, IAIProvider, IVectorStore, IBillingProvider, …); adapters provide concrete implementations.

Official adapters

Domain	Adapter	Repo	NuGet
Persistence — event store	PostgreSQL	compendium-adapter-postgresql
Persistence — cache & idempotency	Redis	compendium-adapter-redis
Persistence — vector store	pgvector	compendium-adapter-pgvector
Persistence — vector store	Qdrant	compendium-adapter-qdrant
Persistence — vector store	Pinecone (managed)	compendium-adapter-pinecone
Persistence — object storage	S3-compatible (AWS / R2 / MinIO / B2 / Wasabi)	compendium-adapter-s3
Identity	Zitadel	compendium-adapter-zitadel
Billing	Stripe	compendium-adapter-stripe
Billing	LemonSqueezy	compendium-adapter-lemonsqueezy
Email	Listmonk	compendium-adapter-listmonk
AI — gateway	OpenRouter	compendium-adapter-openrouter
AI — direct provider	OpenAI	compendium-adapter-openai
AI — direct provider	Anthropic	compendium-adapter-anthropic
AI — direct provider	Gemini (Google)	compendium-adapter-gemini
AI — direct provider (EU)	Mistral AI (Large / Codestral / Pixtral)	compendium-adapter-mistral
AI — direct provider	DeepSeek (V3 / R1 reasoning)	compendium-adapter-deepseek
AI — direct provider	Mercury (Inception Labs, diffusion)	compendium-adapter-mercury
AI — open models hosting	Hugging Face Inference Endpoints	compendium-adapter-huggingface
AI — Azure-hosted	Azure OpenAI (Entra ID)	compendium-adapter-azure-openai
AI — AWS gateway	Bedrock (Claude / Llama / Mistral / Nova)	compendium-adapter-bedrock
AI — gateway	LiteLLM (self-hostable)	compendium-adapter-litellm
AI — local	Ollama	compendium-adapter-ollama

The thin ASP.NET Core glue (Compendium.Adapters.AspNetCore — middleware, ProblemDetails, multi-tenancy HTTP resolution) stays in the framework monorepo since it has no external SDK and evolves lock-step with Compendium.Application.

Verified third-party adapters

None yet. Maintainers of community adapters that pass a security & convention review (namespacing, tenancy, Result-pattern, test coverage) can open a PR adding a row here.

Writing your own adapter

Use the template-compendium-adapter-dotnet GitHub template — it ships with the test stack, CI gate, MinVer versioning, and NuGet publishing wired in. See docs/adapters/external.md for the writing guide.

Quick start

Install the packages you need:

dotnet add package Compendium.Core
dotnet add package Compendium.Application
dotnet add package Compendium.Adapters.PostgreSQL

Define an event-sourced aggregate:

usingCompendium.Core.Domain.Primitives;usingCompendium.Core.Results;publicsealedclassOrderAggregate:AggregateRoot<OrderId>{privateOrderStatus_status;privatedecimal_amount;privateOrderAggregate(OrderIdid):base(id){}publicstaticResult<OrderAggregate>Create(CustomerIdcustomerId,decimalamount){if(amount<=0)returnResult.Failure<OrderAggregate>(Error.Validation("Order.Amount.Invalid","Amount must be positive"));varorder=newOrderAggregate(OrderId.New());order.AddDomainEvent(newOrderCreated(order.Id,customerId,amount));returnResult.Success(order);}publicvoidApply(OrderCreated@event){_status=OrderStatus.Pending;_amount=@event.Amount;}}

Wire it up in Program.cs:

usingCompendium.Application.CQRS;usingMicrosoft.Extensions.DependencyInjection;varbuilder=WebApplication.CreateBuilder(args);// Register Compendium CQRS dispatchers (command/query handlers are resolved via IServiceProvider).builder.Services.AddScoped<ICommandDispatcher,CommandDispatcher>();builder.Services.AddScoped<IQueryDispatcher,QueryDispatcher>();// Register your command/query handlers, then wire the PostgreSQL event store adapter// using the options published by Compendium.Adapters.PostgreSQL.varapp=builder.Build();

Packages

These are the framework packages that ship from this repository. Adapter packages live in their own repositories — see Adapters above.

Package	Purpose	NuGet
Compendium.Core	DDD primitives, Result pattern, domain events
Compendium.Abstractions	Shared infrastructure port interfaces
Compendium.Abstractions.AI	AI provider contracts (incl. IAIProvider, IEmbeddingProvider, IReranker, agent loop)
Compendium.Abstractions.Billing	Billing provider contracts
Compendium.Abstractions.Email	Email provider contracts
Compendium.Abstractions.Identity	Identity provider contracts
Compendium.Abstractions.VectorStore	Vector store port (IVectorStore)
Compendium.Abstractions.Search	Search port (ISearchIndex)
Compendium.Application	CQRS dispatchers, handlers, pipelines
Compendium.Infrastructure	Projections, outbox, infrastructure building blocks
Compendium.Multitenancy	Tenant context, resolution, and scoping
Compendium.Adapters.AspNetCore	ASP.NET Core glue (middleware, ProblemDetails, multi-tenancy HTTP resolution)
Compendium.Testing	Test helpers, fakes, TestContainers fixtures

Documentation

The full documentation site is being built at scojh.github.io/Compendium (DocFX-powered). In the meantime:

• ROADMAP.md — themes, what's next, and what's out of scope
• CONTRIBUTING.md — build, test, conventions
• docs/adr/ — architecture decision records
• Source under src/ and the Nexus consumer code for end-to-end examples

Who's using Compendium?

• Nexus — Multi-tenant platform engineering by Sassy Solutions.

Using Compendium in your project? Open a PR to add yourself to this list.

Contributing

Contributions, issues, and feedback are welcome. See CONTRIBUTING.md for guidelines on code style, commit conventions, and the development loop.

License

MIT © 2026 Sassy Solutions. See LICENSE for details.