# Elarion

- [Introduction](/docs): Elarion is a .NET application framework that turns modules, handlers, and attributes into deterministic, compile-time wiring — no runtime reflection scanning.
- [Why Elarion](/docs/why-elarion): The reasoning behind Elarion's opinions, how it differs from idiomatic ASP.NET Core, and whether the trade-offs fit your project.
- Getting started
  - [Getting started](/docs/getting-started): Install Elarion, get one handler onto the wire, and learn the project layout the generators expect.
  - [Installation](/docs/getting-started/installation): Add Elarion's packages and source generators to an application project and an ASP.NET Core host.
  - [Quickstart](/docs/getting-started/quickstart): Build a module, a handler, and a working JSON-RPC endpoint with Elarion in a few minutes.
  - [Project structure](/docs/getting-started/project-structure): How to lay out an Elarion solution and the conventions the source generators depend on.
- Tutorial
  - [Tutorial](/docs/tutorial): A complete, end-to-end walkthrough that builds a small billing application with every opinionated Elarion feature, plus a typed React frontend.
  - [Model the domain](/docs/tutorial/modeling): Define the billing entities, the BillingDbContext data-access context, and the Core, Clients, and Invoicing modules.
  - [Write the features](/docs/tutorial/features): Build the Clients module end to end — a decorator pipeline, current-user scoping, handlers, declarative validation, results, and per-user caching.
  - [Background work](/docs/tutorial/background-work): Build the Invoicing module — send invoice emails through a resilient retrying job, observe its status, and chase overdue invoices on a nightly cron.
  - [Host the API](/docs/tutorial/hosting): Compose the modules in an ASP.NET Core host, publish a JSON-RPC endpoint, expose the same handlers as MCP tools, and wire OpenTelemetry.
  - [Build the frontend](/docs/tutorial/frontend): Generate a typed client from the schema and call the Billing handlers from a React app with TanStack Query, AbortSignal cancellation, and shadcn/ui.
- Concepts
  - [Concepts](/docs/concepts): The three responsibilities Elarion separates, and why auto-detection is the default.
  - [Source generation](/docs/concepts/source-generation): How Elarion's Roslyn generators turn attributes and conventions into deterministic, inspectable registration code.
  - [Handlers](/docs/concepts/handlers): Handlers are Elarion's primary use-case unit — a request in, a Result out, with no transport concerns.
  - [Results & errors](/docs/concepts/results-and-errors): Result<T> is a lightweight success-or-failure return type, and AppError is the transport-agnostic failure model.
  - [Modules](/docs/concepts/modules): A module is an application boundary marked with [AppModule]. Its handlers, services, validation metadata, scheduled jobs, and event consumers are discovered and registered automatically, and feature-gated as one unit.
  - [Services](/docs/concepts/services): Annotate a class with [Service] and the generator registers it in DI — with conventional contract and lifetime resolution — through the module's ConfigureDefaultServices.
  - [Validation](/docs/concepts/validation): Two-tier request validation — DataAnnotations on the request DTO enforced at runtime and exported to every contract surface, business rules in the handler.
  - [Decorator pipelines](/docs/concepts/decorator-pipelines): Generated factories wrap each handler in an ordered decorator pipeline declared by assembly, module, or handler attributes.
  - [Authorization](/docs/concepts/authorization): Declarative, transport-neutral handler authorization — claims, roles, permissions, and named policies — independent of the authentication provider.
  - [Resource authorization](/docs/concepts/resource-authorization): Per-resource (read/write) access control and efficient database-level filtering — owner, tenant, and role-based sharing — composed from one declarative source.
  - [Feature flags & variants](/docs/concepts/feature-flags): Declarative, transport-neutral feature-flag gating for handlers — [FeatureGate] over an OpenFeature-backed IFeatureFlagService, with any provider behind it.
  - [Client capabilities](/docs/concepts/client-capabilities): One bootstrap snapshot — modules, feature flags/variants, and the user's grants — projected to the frontend over OpenFeature so the UI can hide or adapt itself.
  - Frontend modules
    - [Frontend modules](/docs/concepts/frontend-modules): The contribution model — typed extension points, declarative module manifests, and capability-gated resolution — extends "a module only touches its own code" to the web app.
    - [React & app shells](/docs/concepts/frontend-modules/react): The React bindings and composition root — glob-discovered manifests, ContributionProvider, useContributions, plain and shadcn/ui sidebars, and the Vite dedupe config.
    - [Routing](/docs/concepts/frontend-modules/routing): Module-owned route subtrees with the router's own API, the redirectUnless guard that shares contribution `when` semantics, and the TanStack Start SSR shim.
    - [Angular](/docs/concepts/frontend-modules/angular): The signal-first Angular bindings — provideContributions, injectContributions, and a self-owned *extensionSlot structural directive.
  - [Idempotency](/docs/concepts/idempotency): Declarative, transport-neutral, exactly-once command replay — [Idempotent] over a single-transaction, unique-constrained key store, with the key committed atomically with the operation.
  - [Audit trail](/docs/concepts/auditing): Declarative, transport-neutral audit records — who performed which action on which resource, with field-level change capture, success records committed atomically with the business transaction.
  - [Settings](/docs/concepts/settings): Runtime-changeable, key/value settings with a swappable store, in-process change watching, and an AOT-clean typed accessor — global and per-user.
  - [Persistence & transactions](/docs/concepts/persistence-and-transactions): How Elarion's EF Core stores and the event buses participate in the caller's database transaction — what commits and rolls back together, and what is delivered after commit.
  - [Variable substitution](/docs/concepts/variable-substitution): Spring-style ${key:-default} placeholders resolved from a pluggable source — a general building block reused across Elarion subsystems, not tied to any one feature.
  - [Cross-module communication](/docs/concepts/cross-module-communication): Direct, synchronous module-to-module calls go through a published [ModuleContract]; an analyzer keeps modules honest, and an optional generated typed in-process API lets a module call its own handlers by name.
  - Actors
    - [Actors](/docs/concepts/actors): Decide whether a live in-memory consistency unit deserves an actor, then choose the runtime, durability, placement, and integration model.
    - [Actor runtime and facades](/docs/concepts/actors/runtime): Generated facades, keying, activation, mailboxes, lifecycle, reentrancy, configuration, wiring, and worker-pool patterns.
    - [Actor state and placement](/docs/concepts/actors/state-and-placement): Snapshot durability, query semantics, conflict recovery, multi-instance topology, role leases, and actor placement.
    - [Actor events, streams, and telemetry](/docs/concepts/actors/integrations): Feed integration events into actors, stream ordered state out, and operate actors with traces and metrics.
  - [Solution structure](/docs/concepts/solution-structure): Where entities, modules, and schema configuration belong relative to the module-boundary rule — keep entities in a shared-kernel namespace, treat configuration as part of the shared data layer (not feature-owned), and graduate to bounded contexts only when they earn their keep.
- Capabilities
  - [Capabilities](/docs/capabilities): Choose the opt-in platform pieces you need — transports, policy, messaging, realtime, coordination, persistence, and operations.
  - [Hosting](/docs/capabilities/hosting): Wire the module bootstrapper, handler registry, and JSON-RPC endpoint into an ASP.NET Core host.
  - [Serialization](/docs/capabilities/serialization): One canonical JsonSerializerOptions that every Elarion subsystem reads, composed from per-module source-generated JSON contexts for AOT-friendly serialization.
  - Transports
    - [Transports](/docs/capabilities/transports): Map a handler over HTTP, JSON-RPC, MCP, or explicit unary/server-streaming gRPC service methods while keeping application logic transport-neutral.
    - [HTTP endpoints](/docs/capabilities/transports/http-endpoints): Mark a handler with [HttpEndpoint] and Elarion generates the minimal-API MapGet/MapPost mapping — unwrapping the Query/Command and mapping AppError to RFC 7807 status codes.
    - [Request-driven server streaming](/docs/capabilities/transports/server-streaming): Stream one request's lazy response over SSE or gRPC with IStreamHandler — and choose it deliberately over client events, ordered streams, or connections.
    - [OpenAPI](/docs/capabilities/transports/openapi): Bring the [HttpEndpoint] REST transport to schema/contract parity with JSON-RPC — an OpenAPI document, module tags, clean operation ids, ProblemDetails, and the Idempotency-Key contract, from Microsoft.AspNetCore.OpenApi.
    - [JSON-RPC](/docs/capabilities/transports/json-rpc): JSON-RPC is a first-class optional transport — mark a handler with [Handler] and Elarion takes it from dispatcher to typed TypeScript client.
    - [Schema generation](/docs/capabilities/transports/schema-generation): Export rpc-schema.json automatically during dotnet build with the Elarion.AspNetCore.SchemaGeneration MSBuild package.
    - [TypeScript client](/docs/capabilities/transports/typescript-client): Generate typed method contracts, Zod result schemas, and a portable fetch client from an exported rpc-schema.json.
    - [gRPC](/docs/capabilities/transports/grpc): Add unary and request-driven server-streaming gRPC service methods over Elarion handlers with explicit protobuf mapping, scoped identity, and stable AppError status translation.
    - [MCP server](/docs/capabilities/transports/mcp): Expose your handlers as a Model Context Protocol (MCP) server, independent of the JSON-RPC HTTP endpoint.
    - [Writing a custom transport](/docs/capabilities/transports/custom-transports): Invoke Elarion handlers from gRPC, a console, a queue, or another host while preserving scoped identity and the full handler pipeline.
  - [Current user](/docs/capabilities/current-user): ICurrentUser gives handlers transport-neutral access to the authenticated user, without depending on HttpContext.
  - [ASP.NET Core Identity](/docs/capabilities/identity): Optional ASP.NET Core Identity integration that composes onto a plain DbContext — no IdentityDbContext inheritance, snake_case-ready.
  - [Caching](/docs/capabilities/caching): Declarative handler result caching with [Cacheable] and tag-based invalidation with [CacheInvalidate], backed by HybridCache.
  - [Resilience](/docs/capabilities/resilience): Declare named retry/timeout policies as metadata, apply them to handlers and jobs, and back them with a runtime of your choice.
  - [Feature flag providers](/docs/capabilities/feature-flags): Wire a feature-flag backend into the host so [FeatureGate] handlers and variant services evaluate against the provider of your choice.
  - Scheduling
    - [Scheduling](/docs/capabilities/scheduling): Source-generated scheduled jobs share one in-memory scheduler with typed invocation, explicit policies, and OpenTelemetry instrumentation.
    - [Schedules](/docs/capabilities/scheduling/schedules): Define when a job runs with FixedRate, FixedDelay, Cron, or an initial-delay one-off — using compact duration literals and config placeholders.
    - [Overlap & misfire](/docs/capabilities/scheduling/overlap-and-misfire): Control what happens when runs of the same job collide, and when grid schedules fall behind.
    - [Runtime jobs](/docs/capabilities/scheduling/runtime-jobs): Schedule typed one-off jobs with a payload at runtime through IJobScheduler, and cancel them by id.
    - [Inspection](/docs/capabilities/scheduling/inspection): Read scheduler state through IJobSchedulerInspector — snapshots, next-due times, and per-job status.
    - [Execution semantics & positioning](/docs/capabilities/scheduling/semantics): Where each kind of scheduled work runs, what survives a restart, what the guarantees are — and when to choose a dedicated job system instead.
    - [Multi-node coordination](/docs/capabilities/scheduling/multi-node): How recurring jobs execute exactly once across a cluster — per-occurrence claims, the architecture behind them, and what you gain in practice.
  - Events & messaging
    - [Events & messaging](/docs/capabilities/events): An in-process eventing subsystem split by its relationship to the database transaction — inline domain events and after-commit integration events.
    - [Consuming events](/docs/capabilities/events/consuming-events): Declare event consumers as handlers or service methods, for both inline domain events and after-commit integration events, and keep them idempotent.
    - [Event backends](/docs/capabilities/events/backends): Choose between the best-effort in-memory integration bus and the durable EF Core transactional outbox, and wire the one you pick.
    - [Client events (near-realtime)](/docs/capabilities/events/client-events): Push after-commit facts to connected browsers as invalidation hints — typed topics, fail-closed subscriptions, and a generated TypeScript client over Server-Sent Events.
    - [Ordered streams](/docs/capabilities/events/streams): StreamHub, actor stream methods, and the resumable SSE endpoint — the ordered, completable tier next to client events.
  - [Coordination & role leases](/docs/capabilities/coordination): Elect one instance for a coarse application role on PostgreSQL, gate work at the holder, and route HTTP traffic to it when needed.
  - Client connections
    - [Client connections](/docs/capabilities/connections): Long-lived bidirectional links — device gateways and interactive clients — over a transport-neutral kernel; the app writes only the handshake and the codec.
    - [WebSocket endpoint](/docs/capabilities/connections/websocket): The ASP.NET Core connection adapter — subclass one handler for the authenticator and codec; accept, framing, lifecycle, and teardown are framework.
    - [TCP endpoints](/docs/capabilities/connections/tcp): Raw-socket listeners and dialers over the same handler/codec seams — framing, runtime endpoint management, TLS, bounded outbound backpressure, deterministic close.
    - [Device gateways](/docs/capabilities/connections/device-gateway): Keepalives, codec conversation helpers, and the full device-gateway loop — connections as the carrier, actors as the concurrency gate, handlers as the authorization gate.
    - [Simulation & testing](/docs/capabilities/connections/testing): Socket-less simulated connections, awaitable observers, in-memory TCP links, and the WebSocket test host — pick the lowest faithful tier.
    - [Low-allocation dispatch](/docs/capabilities/connections/low-allocation): The opt-in profile (ADR-0066) that removes steady-state garbage from connection dispatch — per-connection scopes, singleton handlers, telemetry opt-down, writer sends — down to 0 B per message.
  - [Device identity](/docs/capabilities/devices): Pairing codes, per-device keys, and the connect-time HMAC handshake — the provisioning chain every device gateway needs, without hand-rolling the security-relevant parts.
  - [Data-rate shaping](/docs/capabilities/data-rate-shaping): Shape high-frequency data with a write-behind buffer, a keyed conflater, a bounded MPSC command queue, and a staged-batch flusher for producer-owned hot state.
  - [Entity Framework Core](/docs/capabilities/entity-framework): Optional source generation for DbSet properties and entity configuration application — driven by [EntityConfiguration], applied to your concrete DbContext, explicit and AOT-friendly.
  - [Multi-tenancy](/docs/capabilities/multi-tenancy): Ambient per-tenant isolation — one marker interface attaches a model-level read filter and a write-time stamp, so a forgotten predicate cannot leak across tenants and a forgotten stamp cannot orphan a row.
  - [Bulk operations](/docs/capabilities/bulk-operations): Insert large entity sets at PostgreSQL COPY speed with a non-tracking, EF-native ExecuteInsertAsync.
  - [Pagination](/docs/capabilities/pagination): Transport-neutral keyset (cursor) and offset paging that produces a Page<T>, with composite sorts and an opaque cursor codec.
  - [Archive & restore](/docs/capabilities/archive-restore): Soft delete done deliberately — a nullable ArchivedAt timestamp, explicit query predicates, restore as a first-class command, a real DELETE for retention, and the common alternatives this recipe rejects.
  - [SQL migrations](/docs/capabilities/sql-migrations): Startup-applied SQL migrations for EF-free (NativeAOT) hosts — embedded scripts, normalized checksums, no repair command, PostgreSQL and SQLite providers.
  - [SQL mapping](/docs/capabilities/sql-mapping): AOT-native SQL row mapping for EF-free hosts — explicit generated mappers, injection-safe SQL interpolation, no reflection, no silent fallback.
  - [PostgreSQL extensions](/docs/capabilities/postgres-extensions): Extensions are composition, not scale-out — how to run TimescaleDB, pgvector & co on the one Postgres you already have, including combining several in one image.
  - [Time series](/docs/capabilities/time-series): Store telemetry on the PostgreSQL you already run — a TimescaleDB recipe composing bulk insert, keyset paging, scheduled retention, and client events.
  - [Blob storage](/docs/capabilities/blob-storage): Store binary content behind provider-neutral contracts, with an optional PostgreSQL-backed implementation.
  - [Blob uploads](/docs/capabilities/blob-uploads): Pre-upload files over an open, resumable transport (tus) or a minimal direct endpoint, reference them when creating an entity, and reclaim abandoned uploads automatically with a pending/commit/TTL lifecycle.
  - [Telemetry & observability](/docs/capabilities/telemetry): Elarion emits OpenTelemetry-compatible traces and metrics through System.Diagnostics — the host chooses exporters, the runtime forces no SDK dependency — and enriches every handler span and log scope with user context by default.
- Reference
  - [Reference](/docs/reference): Exhaustive, lookup-oriented facts — packages, configuration keys, attributes, diagnostics, conventions, and the result/error model.
  - [Packages](/docs/reference/packages): Canonical, grouped reference for every public Elarion .NET and npm package.
  - [Configuration](/docs/reference/configuration): Every configuration key and MSBuild property Elarion reads, in one place.
  - [Attributes](/docs/reference/attributes): The full catalog of Elarion attributes — what each one triggers, its parameters, and their defaults.
  - [Diagnostics](/docs/reference/diagnostics): Every generator and analyzer diagnostic Elarion can emit, what it means, and how to fix it.
  - [Conventions & layout](/docs/reference/conventions): The naming and namespace conventions the source generators depend on, and the project dependency rules.
  - [Result & error model](/docs/reference/result-and-errors): Lookup reference for Result<T>, Result, Unit, AppError, and ErrorKind, with each kind's mapping to JSON-RPC error codes and HTTP status.
  - [Troubleshooting](/docs/reference/troubleshooting): Common symptoms when wiring Elarion, their likely cause, and the fix.