# Alvo > Describe your backend in one JSON file. Get a secure, production-shaped API — standalone in Docker or embedded in your ASP.NET Core app. Alvo is a .NET-native backend-as-a-service: one JSON descriptor (validated by a JSON Schema) defines entities, CEL access rules compiled to SQL, hooks, computed fields and webhooks; it runs as a Docker image or embedded in ASP.NET Core. Status: pre-v0.1 — the image runs from its edge tag (ghcr.io/burgyn/alvo:edge); no NuGet package or release is published yet. Errors are RFC 9457 problem documents. Their `type` is `https://alvo.dev/errors/`; that domain does not resolve yet, so read `https://alvo.burgyn.online/reference/problem-types/#` instead. Branch on the slug, never on `detail`. ## Descriptor schema and skills - [Descriptor JSON Schema](https://alvo.burgyn.online/schema/v1/project.json): validate every descriptor against it; also at https://raw.githubusercontent.com/Burgyn/MMLib.Alvo/main/schema/project.schema.json - [alvo-descriptor-capabilities-and-limits](https://raw.githubusercontent.com/Burgyn/MMLib.Alvo/main/plugins/alvo/skills/alvo-descriptor-capabilities-and-limits/SKILL.md): Use when asked whether Alvo can do something, or when a change needs a block or an action this build may not run — what is honoured, what is only warned, and what is refused. - [alvo-descriptor-computed-and-rollups](https://raw.githubusercontent.com/Burgyn/MMLib.Alvo/main/plugins/alvo/skills/alvo-descriptor-computed-and-rollups/SKILL.md): Use when an Alvo descriptor field should be derived rather than written — a computed value over its own row, or a rollup over related rows — and what a computed expression may contain. - [alvo-descriptor-entities-and-fields](https://raw.githubusercontent.com/Burgyn/MMLib.Alvo/main/plugins/alvo/skills/alvo-descriptor-entities-and-fields/SKILL.md): Use when an Alvo descriptor change adds, renames or removes an entity or a field, or sets required, unique, default, hidden or readOnly — paths, keys, reserved names, renames that keep data. - [alvo-descriptor-field-types-and-formats](https://raw.githubusercontent.com/Burgyn/MMLib.Alvo/main/plugins/alvo/skills/alvo-descriptor-field-types-and-formats/SKILL.md): Use when an Alvo descriptor field needs a type or its facets — string or text, decimal precision and scale, enum values, a ref and its onDelete, or a format such as email. - [alvo-descriptor-hooks](https://raw.githubusercontent.com/Burgyn/MMLib.Alvo/main/plugins/alvo/skills/alvo-descriptor-hooks/SKILL.md): Use when an Alvo descriptor change must refuse a write or fill in a value as a row is written — before-hooks with a condition and a reject or mutate action. - [alvo-descriptor-indexes](https://raw.githubusercontent.com/Burgyn/MMLib.Alvo/main/plugins/alvo/skills/alvo-descriptor-indexes/SKILL.md): Use when an Alvo descriptor change should speed up a query or make a combination of fields unique — composite and unique-per-group indexes, and the indexes Alvo already creates by itself. - [alvo-descriptor-project-access](https://raw.githubusercontent.com/Burgyn/MMLib.Alvo/main/plugins/alvo/skills/alvo-descriptor-project-access/SKILL.md): Use when an Alvo descriptor change decides who may manage the project itself — the admin, developer and viewer levels of the access block, and who is allowed to change them. - [alvo-descriptor-rules-and-cel](https://raw.githubusercontent.com/Burgyn/MMLib.Alvo/main/plugins/alvo/skills/alvo-descriptor-rules-and-cel/SKILL.md): Use when an Alvo descriptor change decides who may list, read, create, update or delete the rows of an entity — CEL rules over the caller and the row, and what a rule may contain. - [alvo-descriptor-traits-and-tenancy](https://raw.githubusercontent.com/Burgyn/MMLib.Alvo/main/plugins/alvo/skills/alvo-descriptor-traits-and-tenancy/SKILL.md): Use when an Alvo descriptor change touches audit, softDelete, tenancy, storage or realtime on an entity, or project tenancy — the columns each trait adds and what this build honours. In Claude Code they are the `alvo` plugin: `/plugin marketplace add Burgyn/MMLib.Alvo`, then `/plugin install alvo@mmlib-alvo`. For another agent, install them into its skills folder (default `.claude/skills`; pass another as `sh -s -- `): `curl -fsSL https://raw.githubusercontent.com/Burgyn/MMLib.Alvo/main/scripts/install-agent-skills | sh` ## Start here - [For coding agents](https://alvo.burgyn.online/start-here/coding-agents/): Give a coding agent what it needs to change an Alvo backend safely, from llms.txt and the JSON Schema to a checked, previewed and idempotent apply. - [Why Alvo](https://alvo.burgyn.online/start-here/why-alvo/): Decide whether Alvo fits your project, what makes it different, when not to use it, and how it compares with Supabase, PocketBase and hand-written ASP.NET Core. - [Quick start](https://alvo.burgyn.online/start-here/quick-start/): Start the published standalone image with one compose file, create a record and read it back, in five minutes. - [Tutorial: your first backend](https://alvo.burgyn.online/start-here/tutorial/): Build a help desk's backend in four small steps: an entity, access rules, a before-hook and a computed field, then look at it in the dashboard. - [Run your own descriptor](https://alvo.burgyn.online/start-here/run-your-own/): Run the published standalone image over a descriptor you wrote, with API keys for the roles it declares, using Docker and three downloaded files. - [Embed Alvo in ASP.NET Core](https://alvo.burgyn.online/start-here/embed/): Add Alvo to an existing ASP.NET Core app, so it serves its API next to your own endpoints from the same descriptor. - [What works today](https://alvo.burgyn.online/start-here/what-works-today/): Check what this pre-v0.1 build runs, what it accepts but does not run yet, what it refuses, and how fast it is. ## Guides - [Entities and fields](https://alvo.burgyn.online/guides/entities-and-fields/): Add an entity to the descriptor, give its fields types and constraints, decide per caller who reads and writes a field, and link entities with references. - [Access rules](https://alvo.burgyn.online/guides/access-rules/): Decide per operation who may list, read, create, update and delete the rows of an entity, let callers reach only their own rows, and test a rule before a request does. - [Before-hooks](https://alvo.burgyn.online/guides/before-hooks/): Validate and transform writes: refuse a write, or fill in a value, inside the write's own transaction. - [Computed fields and rollups](https://alvo.burgyn.online/guides/computed-and-rollups/): Derive a field from the other fields of its row, or total up the rows that point at it, and let Alvo keep the value current. - [Indexes and uniqueness](https://alvo.burgyn.online/guides/indexes/): Declare composite indexes for the queries you run most, make a combination of fields unique, and know which indexes Alvo already creates. - [Authentication and API keys](https://alvo.burgyn.online/guides/authentication/): Give each caller an API key with a user, roles and scopes, and know exactly what Alvo answers when a key is missing, wrong or too narrow. - [Multi-tenancy](https://alvo.burgyn.online/guides/multi-tenancy/): Keep each tenant's rows apart in one database: turn tenancy on, give each key its tenant, share reference data across tenants, and know what the isolation guarantees. - [Audit row changes](https://alvo.burgyn.online/guides/audit-row-changes/): Record on every row who created it, who last changed it and when, with values no caller can forge. - [After-hooks, events and webhooks](https://alvo.burgyn.online/guides/after-hooks-and-webhooks/): React to a committed change: post the event to a webhook or send an email, know exactly what is delivered, how often it is retried, and where it may go. - [The admin dashboard](https://alvo.burgyn.online/guides/admin-dashboard/): Sign in to the admin dashboard, change the schema, rules and hooks with every edit checked as you type, browse the data under your own rules, and roll a change back. - [The schema assistant](https://alvo.burgyn.online/guides/schema-assistant/): Connect the dashboard's schema assistant to a model, ask it for a descriptor change in your own words, and review the checked proposal before you apply it yourself. - [Running in production](https://alvo.burgyn.online/guides/production/): Run the standalone host the way production should: on PostgreSQL, with secrets in files, a startup mode that never migrates by surprise, behind a proxy, with probes your orchestrator can trust. - [Apply and evolve your descriptor](https://alvo.burgyn.online/guides/apply-and-evolve/): Change a running backend's descriptor safely: preview the plan, apply it against the revision you read, rename without losing data, drop data only on purpose, and roll back. - [Call Alvo from your endpoints](https://alvo.burgyn.online/guides/call-from-endpoints/): Read and write Alvo's data from your own minimal-API endpoints, in process and under the descriptor's rules, and mount the generated API beside them under your own prefix. - [Custom CEL functions](https://alvo.burgyn.online/guides/custom-cel-functions/): Register a function written in C# in your embedded host, and call it from your descriptor's hook conditions and mutate values. - [Handle errors](https://alvo.burgyn.online/guides/handle-errors/): Read Alvo's problem documents, branch on the problem type rather than the message, and tell a refusal from an empty page or a missing row. - [Use your own authentication](https://alvo.burgyn.online/guides/own-authentication/): Let the users who sign in to your embedded app read and write Alvo's data under the descriptor's rules, without writing authorization code of your own. - [Read data: filter, sort, page](https://alvo.burgyn.online/guides/read-data/): Filter, sort and page through rows with the Data API's PostgREST-style query string, count the matches, and send a long query as a JSON body. - [Write data safely](https://alvo.burgyn.online/guides/write-data/): Create, replace, update and delete rows without losing someone else's change, retry a create without writing it twice, and write many rows in one transaction. ## Examples - [Examples](https://alvo.burgyn.online/examples/): Every example descriptor in the repository: what it shows, whether it applies, and how to run it. ## Concepts - [The project descriptor](https://alvo.burgyn.online/concepts/descriptor/): Understand the one JSON document that defines an Alvo backend: what belongs in it, where it lives, how it is checked and how it changes over time. - [CEL in Alvo](https://alvo.burgyn.online/concepts/cel/): Understand how Alvo uses CEL: one grammar in five profiles, each limited to what its place in the descriptor needs, compiled at apply, rendered into SQL where it filters rows, and failing closed. - [Security model](https://alvo.burgyn.online/concepts/security-model/): Understand what Alvo enforces on every request, who can change what, and where its guarantees stop: default-deny, rules in the data layer, hooks that fail closed, and what an error does and does not disclose. - [Standalone and embedded](https://alvo.burgyn.online/concepts/modes/): Understand the two ways to run Alvo, a container driven by a descriptor or packages inside your own ASP.NET Core app, what each gives you, and how to choose. - [Dynamic entities](https://alvo.burgyn.online/concepts/dynamic-entities/): Understand the planned embedded mode where your application's own users define new record types at runtime, stored in one shared store instead of a table per type. - [Architecture](https://alvo.burgyn.online/concepts/architecture/): Understand how Alvo is built: a control path that applies the descriptor, a runtime path every request takes, the ports every provider plugs into, the outbox behind every event, and the packages. - [Glossary](https://alvo.burgyn.online/concepts/glossary/): Look up the terms Alvo's docs use, from access level and apply to warned and working copy, each with a link to where it is taught. ## Reference - [Reference](https://alvo.burgyn.online/reference/): Generated from the code: every page in this section is produced by tools/MMLib.Alvo.DocsGen at build time. - [Descriptor reference](https://alvo.burgyn.online/reference/descriptor/): Declarative definition of an Alvo backend. - [branding](https://alvo.burgyn.online/reference/descriptor/branding/): Identity of THIS project/backend (display name, logo), shown wherever the project is presented: its section in the admin dashboard, generated end-user surfaces, transactional emails. - [tenancy](https://alvo.burgyn.online/reference/descriptor/tenancy/): Declares this backend as multi-tenant (definition, not infrastructure). - [dynamicEntities](https://alvo.burgyn.online/reference/descriptor/dynamic-entities/): Governance for runtime, user-defined entities (the dynamic schema-registry driver). - [auth](https://alvo.burgyn.online/reference/descriptor/auth/): Authentication and application roles. - [access](https://alvo.burgyn.online/reference/descriptor/access/): Who may manage THIS project in the admin dashboard (project-scoped), mapped to management levels by ROLE MEMBERSHIP. - [entities](https://alvo.burgyn.online/reference/descriptor/entities/): Entity definitions. - [entities.fields](https://alvo.burgyn.online/reference/descriptor/entities-fields/): Entity fields. - [entities.fields: computed and rollup](https://alvo.burgyn.online/reference/descriptor/entities-computed-and-rollups/): Value derived from other fields of the SAME row (pure arithmetic/expression, deterministic, no side effects), e.g. unit_price * amount. - [entities.rules](https://alvo.burgyn.online/reference/descriptor/entities-rules/): Per-operation authorization rules — CEL, compiled into a SQL predicate. - [entities.hooks](https://alvo.burgyn.online/reference/descriptor/entities-hooks/): Lifecycle hooks. - [entities.indexes](https://alvo.burgyn.online/reference/descriptor/entities-indexes/): Explicit composite/extra indexes beyond the automatic ones (PK, unique, ref). - [automation](https://alvo.burgyn.online/reference/descriptor/automation/): ECA rules (event–condition–action). - [templates](https://alvo.burgyn.online/reference/descriptor/templates/): Reusable message templates referenced by email/notification actions. - [formats](https://alvo.burgyn.online/reference/descriptor/formats/): Reusable named validation formats referenced by field.format (beyond the built-ins email/uri/phone). - [webhooks](https://alvo.burgyn.online/reference/descriptor/webhooks/): Managed webhook endpoints (Standard Webhooks: HMAC signing, retries, DLQ). - [functions](https://alvo.burgyn.online/reference/descriptor/functions/): Custom logic — csx scripts (standalone). - [CEL functions](https://alvo.burgyn.online/reference/cel-functions/): Every built-in CEL function, generated from the engine's catalog. - [Configuration keys](https://alvo.burgyn.online/reference/configuration/): Every Alvo:* option, its type and default, generated from the options types. - [Problem types](https://alvo.burgyn.online/reference/problem-types/): Every RFC 9457 problem type the API can answer with, generated from AlvoProblemTypes. - [Management API](https://alvo.burgyn.online/reference/management-api/): Every route of the Management API, read from a running host's route table. - [Capabilities in this build](https://alvo.burgyn.online/reference/capabilities/): What this build honours, what it parses and does not run, and what it refuses at apply. - [Limits and budgets](https://alvo.burgyn.online/reference/limits/): Every size, depth and count limit the API enforces, read from the code. - [C# API](https://alvo.burgyn.online/reference/csharp/): The host-facing C# surface of each MMLib.Alvo.* package: registration, options and the ports a host calls or implements. - [MMLib.Alvo.Abstractions](https://alvo.burgyn.online/reference/csharp/mmlib-alvo-abstractions/): The interface-first root of the Alvo dependency graph: every port, and nothing that implements one. - [MMLib.Alvo](https://alvo.burgyn.online/reference/csharp/mmlib-alvo/): The Alvo core: schema registry, Data API, rule engine, events and management, registered with AddAlvo. - [MMLib.Alvo.Data.EntityFrameworkCore](https://alvo.burgyn.online/reference/csharp/mmlib-alvo-data-entityframeworkcore/): The relational adapter every Alvo engine driver is built on. - [MMLib.Alvo.Data.Sqlite](https://alvo.burgyn.online/reference/csharp/mmlib-alvo-data-sqlite/): The SQLite driver for Alvo, registered with UseSqlite. - [MMLib.Alvo.Data.PostgreSql](https://alvo.burgyn.online/reference/csharp/mmlib-alvo-data-postgresql/): The PostgreSQL driver for Alvo, registered with UsePostgreSql. - [MMLib.Alvo.Admin](https://alvo.burgyn.online/reference/csharp/mmlib-alvo-admin/): The Alvo admin dashboard: server-interactive Blazor components and the design system they ship with. - [MMLib.Alvo.Ai](https://alvo.burgyn.online/reference/csharp/mmlib-alvo-ai/): The Alvo schema assistant: an agent that reads a project and proposes a descriptor change, and cannot apply one. - [MMLib.Alvo.Identity](https://alvo.burgyn.online/reference/csharp/mmlib-alvo-identity/): ASP.NET Core Identity for Alvo: administrator accounts, roles, cookie sign-in and the bootstrap administrator. - [Data API conventions](https://alvo.burgyn.online/data-api/conventions/): The routes, query grammar, paging, headers, statuses and problem documents every generated Data API endpoint follows. - [Data API — example (vehicle-registry)](https://alvo.burgyn.online/reference/data-api/): The generated REST API of the vehicle-registry example; every descriptor generates its own at GET /openapi/v1.json. ## Project - [Changelog](https://alvo.burgyn.online/project/changelog/): Every notable change, rendered from CHANGELOG.md. - [Contributing](https://alvo.burgyn.online/project/contributing/): How to contribute to Alvo, rendered from CONTRIBUTING.md. - [FAQ](https://alvo.burgyn.online/project/faq/): Find short answers to the questions people ask first about Alvo: its status, packages, authentication, databases, scope, CEL, errors and licence. - [License](https://alvo.burgyn.online/project/license/): Alvo's core is licensed under Apache-2.0, and stays free and open source. - [Roadmap and status](https://alvo.burgyn.online/project/roadmap/): See where Alvo is before v0.1, what may still change before the release and what you can rely on, what v0.1 means, and what is planned after it. ## Optional - [Full text](https://alvo.burgyn.online/llms-full.txt): The start-here, guide, example and concept pages plus the descriptor, CEL, problem-type, capability, configuration and limits reference as one file.