.NET Headless Framework

The modular .NET framework that stays out of your way.

116+ NuGet packages • Abstraction + Provider pattern • Zero lock-in

Quick Start • Packages • Architecture • LLM Context • Contributing

Why Headless?

Most .NET frameworks force opinions on you — folder structures, ORM choices, messaging transports, cloud providers. Headless doesn't.

Every feature ships as a pair: a thin abstraction package (interfaces and contracts) and one or more provider packages (concrete implementations). You pick the pieces you need, wire them up, and own the result.

Composable — 116+ standalone packages. Use one or use fifty.
Swappable — Switch from Redis to in-memory caching, or AWS to Azure blob storage, by changing one line.
Explicit — No hidden conventions, no magic. Every behavior is visible in your code.
Testable — Every abstraction is mockable. Every provider is integration-tested with Testcontainers.

Quick Start

dotnet add package Headless.Api
dotnet add package Headless.Caching.Redis
dotnet add package Headless.Orm.EntityFramework

var builder = WebApplication.CreateBuilder(args);

builder.AddHeadlessApi();

builder.Services.AddHeadlessRedisCache(options =>
{
    options.ConnectionString = "localhost:6379";
});

builder.Services.AddAzureBlobStorage(options =>
{
    options.ConnectionString = "your-connection-string";
    options.ContainerName = "uploads";
});

builder.Services.AddAwsSesEmail(options =>
{
    options.FromEmail = "noreply@example.com";
});

var app = builder.Build();
app.UseResponseCompression();
app.UseHsts();
app.Run();

Packages

API & Web

Everything you need to stand up production-grade ASP.NET Core APIs — request/response conventions, validation pipelines, structured logging, and OpenAPI documentation out of the box.

Package	Description
Headless.Api	ASP.NET Core API utilities and conventions
Headless.Api.Abstractions	API abstractions and contracts
Headless.Api.DataProtection	Data protection key storage
Headless.Api.FluentValidation	FluentValidation integration for APIs
Headless.Api.Logging.Serilog	Serilog logging integration
Headless.Api.MinimalApi	Minimal API utilities
Headless.Api.Mvc	MVC-specific utilities

Core

Foundational building blocks shared across the framework — domain primitives, DDD base types, guard clauses, and entity/event infrastructure.

Package	Description
Headless.Extensions	Core primitives and utilities
Headless.Core	Domain-Driven Design building blocks
Headless.Security.Abstractions	Security contracts and options
Headless.Security	String encryption and hashing services
Headless.Checks	Guard clauses and argument validation
Headless.Domain	Domain entities and events
Headless.Domain.LocalPublisher	In-process domain event publishing

Audit Log

Property-level audit logging for tracking entity mutations and explicit business events. Records what changed, who changed it, and when — with EF Core persistence.

Package	Description
Headless.AuditLog.Abstractions	Audit log contracts and interfaces
Headless.AuditLog.EntityFramework	EF Core audit log persistence

Blob Storage

Unified blob storage interface with providers for every major cloud and protocol. Store and retrieve files without coupling to any single vendor.

Package	Description
Headless.Blobs.Abstractions	Blob storage interfaces
Headless.Blobs.Aws	AWS S3 blob storage
Headless.Blobs.Azure	Azure Blob storage
Headless.Blobs.FileSystem	Local filesystem storage
Headless.Blobs.Redis	Redis blob storage
Headless.Blobs.SshNet	SFTP blob storage

Caching

Multi-tier caching with a clean abstraction layer. Supports in-memory, Redis, and hybrid (L1/L2) strategies — swap providers without touching business logic.

Package	Description
Headless.Caching.Abstractions	Caching interfaces
Headless.Caching.Hybrid	Hybrid caching (L1/L2)
Headless.Caching.Memory	In-memory caching
Headless.Caching.Redis	Redis caching

Email

Send transactional and marketing emails through a unified interface. Plug in AWS SES, SMTP via MailKit, or a no-op dev provider for local testing.

Package	Description
Headless.Emails.Abstractions	Email sending interfaces
Headless.Emails.Core	Core email implementation
Headless.Emails.Aws	AWS SES email provider
Headless.Emails.Dev	Development email provider
Headless.Emails.Mailkit	MailKit SMTP provider

Feature Management

Runtime feature flags backed by persistent storage. Toggle features without redeployment and query flag state from anywhere in your application.

Package	Description
Headless.Features.Abstractions	Feature flag interfaces
Headless.Features.Core	Feature management implementation
Headless.Features.Storage.EntityFramework	EF Core feature storage

Identity

Identity persistence and storage extensions for ASP.NET Core Identity, built on EF Core.

Package	Description
Headless.Identity.Storage.EntityFramework	EF Core identity storage

Imaging

Image processing pipeline with pluggable backends. Resize, crop, convert, and optimize images through a clean abstraction.

Package	Description
Headless.Imaging.Abstractions	Image processing interfaces
Headless.Imaging.Core	Core image processing
Headless.Imaging.ImageSharp	ImageSharp implementation

Logging

Structured logging utilities and enrichers built on top of Serilog.

Package	Description
Headless.Logging.Serilog	Serilog logging utilities

Media

Content indexing and metadata extraction for media files — images, video, and documents.

Package	Description
Headless.Media.Indexing.Abstractions	Media indexing interfaces
Headless.Media.Indexing	Media indexing implementation

Messaging

Reliable distributed message bus with transactional outbox, automatic retries, delayed delivery, and type-safe consumers. 7 transport providers and 3 storage backends — swap the underlying infrastructure without changing application code.

Package	Description
Headless.Messaging.Abstractions	Core messaging interfaces and contracts
Headless.Messaging.Core	Runtime engine: outbox, retries, delayed delivery, consumer orchestration
Headless.Messaging.Dashboard	Web UI for monitoring messages, failures, and system health
Headless.Messaging.Dashboard.K8s	Kubernetes node auto-discovery for the dashboard
Headless.Messaging.OpenTelemetry	Tracing, metrics, and context propagation

Transports:

Package	Description
Headless.Messaging.RabbitMq	RabbitMQ (AMQP)
Headless.Messaging.Kafka	Apache Kafka
Headless.Messaging.AwsSqs	AWS SQS + SNS
Headless.Messaging.AzureServiceBus	Azure Service Bus
Headless.Messaging.Nats	NATS with JetStream
Headless.Messaging.Pulsar	Apache Pulsar
Headless.Messaging.RedisStreams	Redis Streams
Headless.Messaging.InMemoryQueue	In-memory (dev/testing)

Storage backends:

Package	Description
Headless.Messaging.PostgreSql	PostgreSQL message persistence
Headless.Messaging.SqlServer	SQL Server message persistence
Headless.Messaging.InMemoryStorage	Ephemeral storage (dev/testing)

Jobs

Distributed background job scheduling with cron expressions, delayed execution, monitoring dashboard, and OpenTelemetry observability. Source-generated for compile-time safety.

Package	Description
Headless.Jobs.Abstractions	Job scheduling interfaces
Headless.Jobs.Core	Job engine: cron, delays, retries, monitoring
Headless.Jobs.SourceGenerator	Compile-time code gen for `[Jobs]`-marked jobs
Headless.Jobs.Dashboard	Web UI for job monitoring
Headless.Jobs.OpenTelemetry	Tracing and metrics for job execution
Headless.Jobs.EntityFramework	EF Core job state persistence
Headless.Jobs.Caching.Redis	Redis node registry and heartbeats

OpenAPI

API documentation generation and interactive UIs. Supports NSwag for spec generation, OData query conventions, and Scalar for a modern API explorer.

Package	Description
Headless.OpenApi.Nswag	NSwag OpenAPI generation
Headless.OpenApi.Nswag.OData	NSwag OData support
Headless.OpenApi.Scalar	Scalar API documentation

ORM

Database access utilities for Entity Framework Core and Couchbase — conventions, seed data, soft deletes, and multi-tenancy support.

Package	Description
Headless.Orm.EntityFramework	Entity Framework Core utilities
Headless.Orm.Couchbase	Couchbase ORM utilities

Payments

Payment gateway integrations for the MENA region. Cash-in (collection) and cash-out (disbursement) flows through Paymob.

Package	Description
Headless.Payments.Paymob.CashIn	Paymob cash-in payments
Headless.Payments.Paymob.CashOut	Paymob cash-out payments
Headless.Payments.Paymob.Services	Paymob shared services

Permissions

Dynamic, database-backed permission system. Define permissions as code, store assignments in EF Core, and query access control at runtime.

Package	Description
Headless.Permissions.Abstractions	Permission system interfaces
Headless.Permissions.Core	Permission system implementation
Headless.Permissions.Storage.EntityFramework	EF Core permission storage

Push Notifications

Send push notifications through Firebase Cloud Messaging with a clean abstraction. Includes a no-op dev provider for local testing.

Package	Description
Headless.PushNotifications.Abstractions	Push notification interfaces
Headless.PushNotifications.Dev	Development push provider
Headless.PushNotifications.Firebase	Firebase Cloud Messaging

Distributed Locking

Coordinate access to shared resources across distributed services. Supports regular locks with expiration and throttling locks for rate limiting.

Package	Description
Headless.DistributedLocks.Abstractions	Distributed locking interfaces
Headless.DistributedLocks.Core	Distributed locking implementation
Headless.DistributedLocks.Cache	Cache-based locking
Headless.DistributedLocks.Redis	Redis-based locking

Serialization

Pluggable serialization with providers for System.Text.Json and MessagePack. Use the same interface for JSON APIs and binary wire formats.

Package	Description
Headless.Serializer.Abstractions	Serialization interfaces
Headless.Serializer.Json	System.Text.Json serializer
Headless.Serializer.MessagePack	MessagePack serializer

Settings

Dynamic application settings stored in a database. Change configuration at runtime without redeployment, with caching and change notification support.

Package	Description
Headless.Settings.Abstractions	Dynamic settings interfaces
Headless.Settings.Core	Settings management implementation
Headless.Settings.Storage.EntityFramework	EF Core settings storage

SMS

Send SMS messages through a unified interface with providers for major regional and global carriers.

Package	Description
Headless.Sms.Abstractions	SMS sending interfaces
Headless.Sms.Aws	AWS SNS SMS provider
Headless.Sms.Cequens	Cequens SMS provider
Headless.Sms.Connekio	Connekio SMS provider
Headless.Sms.Dev	Development SMS provider
Headless.Sms.Infobip	Infobip SMS provider
Headless.Sms.Twilio	Twilio SMS provider
Headless.Sms.VictoryLink	VictoryLink SMS provider
Headless.Sms.Vodafone	Vodafone SMS provider

SQL

Lightweight connection factories for raw SQL access when you need to drop below the ORM. Supports PostgreSQL, SQL Server, and SQLite.

Package	Description
Headless.Sql.Abstractions	SQL connection interfaces
Headless.Sql.PostgreSql	PostgreSQL connection factory
Headless.Sql.SqlServer	SQL Server connection factory
Headless.Sql.Sqlite	SQLite connection factory

Testing

Test infrastructure and utilities — base classes, builders, fixtures, and Testcontainers integration for real-database integration tests.

Package	Description
Headless.Testing	Testing utilities and base classes
Headless.Testing.Testcontainers	Testcontainers fixtures

TUS (Resumable Uploads)

TUS protocol support for reliable, resumable file uploads. Handles large files gracefully with Azure Blob Storage and distributed locking.

Package	Description
Headless.Tus	TUS protocol utilities
Headless.Tus.Azure	Azure Blob TUS store
Headless.Tus.DistributedLocks	TUS file locking

Utilities

Cross-cutting utilities that don't belong to a specific domain — validation extensions, source generators, hosting helpers, geospatial, and more.

Package	Description
Headless.FluentValidation	FluentValidation extensions
Headless.Generator.Primitives	Primitive types source generator
Headless.Generator.Primitives.Abstractions	Generator abstractions
Headless.Hosting	.NET hosting utilities
Headless.NetTopologySuite	Geospatial utilities
Headless.ReCaptcha	Google reCAPTCHA integration
Headless.Redis	Redis utilities
Headless.Sitemaps	XML sitemap generation
Headless.Slugs	URL slug generation

Architecture

Every feature follows the abstraction + provider pattern:

Headless.*.Abstractions  →  Interfaces and contracts (what)
Headless.*.<Provider>    →  Concrete implementation (how)

This means you can:

Swap providers without touching business logic
Mock any dependency in unit tests
Add your own provider by implementing the abstraction

LLM Context

Machine-readable project context for AI-assisted development:

llms.txt — Compact overview
llms-full.txt — Full package documentation

For Consumers

If your project uses Headless packages, add the following to your CLAUDE.md or AGENTS.md so AI agents can fetch the correct documentation:

## Headless Framework

This project uses [Headless .NET Framework](https://github.com/xshaheen/headless-framework) packages.

Documentation index: https://raw.githubusercontent.com/xshaheen/headless-framework/main/llms.txt

When working with a Headless domain, fetch the relevant domain doc:
- API & Web: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/api.md
- Core: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/core.md
- Multi-Tenancy: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/multi-tenancy.md
- Blob Storage: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/blobs.md
- Caching: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/caching.md
- Email: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/emails.md
- Feature Management: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/features.md
- Identity: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/identity.md
- Imaging: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/imaging.md
- Logging: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/logging.md
- Media: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/media.md
- Messaging (Distributed Bus): https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/messaging.md
- Audit Log: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/audit-log.md
- OpenAPI: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/openapi.md
- ORM: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/orm.md
- Payments: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/payments.md
- Permissions: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/permissions.md
- Push Notifications: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/push-notifications.md
- Distributed Locks: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/distributed-locks.md
- Serialization: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/serialization.md
- Settings: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/settings.md
- SMS: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/sms.md
- SQL: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/sql.md
- Testing: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/testing.md
- Jobs (Background Jobs): https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/jobs.md
- TUS (Resumable Uploads): https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/tus.md
- Utilities: https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/utilities.md

Key rules:
- Use `ICache` from `Headless.Caching.Abstractions`, NOT `Microsoft.Extensions.Caching.Distributed.IDistributedCache`
- Use `IBlobStorage` from `Headless.Blobs.Abstractions`, not cloud SDK clients directly
- Use `Headless.Messaging` for distributed messaging, not raw transport clients (`RabbitMQ.Client`, `Confluent.Kafka`)
- Use `Headless.Jobs` for background jobs with `[Jobs]` attribute + source generator, not Hangfire/Quartz
- Use `*.Dev` packages (Emails.Dev, Sms.Dev, PushNotifications.Dev) in development
- Always depend on `*.Abstractions` packages for interfaces, add one provider for implementation

Contributing

Contributions are welcome — issues, feature requests, and PRs. See individual package READMEs for package-specific details.

Name		Name	Last commit message	Last commit date
Latest commit History 1,290 Commits
.claude		.claude
.github		.github
.husky		.husky
.vscode		.vscode
demo		demo
docs		docs
src		src
tests		tests
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
Directory.Build.props		Directory.Build.props
Directory.Build.targets		Directory.Build.targets
Directory.Packages.props		Directory.Packages.props
Directory.Solution.props		Directory.Solution.props
README.md		README.md
dotnet-tools.json		dotnet-tools.json
global.json		global.json
headless-framework.slnx		headless-framework.slnx
headless-framework.slnx.DotSettings		headless-framework.slnx.DotSettings
llms-full.txt		llms-full.txt
llms.txt		llms.txt
logo.png		logo.png
nuget.config		nuget.config

Folders and files

Latest commit

History

Repository files navigation

.NET Headless Framework

Why Headless?

Quick Start

Packages

API & Web

Core

Audit Log

Blob Storage

Caching

Email

Feature Management

Identity

Imaging

Logging

Media

Messaging

Jobs

OpenAPI

ORM

Payments

Permissions

Push Notifications

Distributed Locking

Serialization

Settings

SMS

SQL

Testing

TUS (Resumable Uploads)

Utilities

Architecture

LLM Context

For Consumers

Contributing

About

Resources

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 8

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages