# Caravela v0.13.3 - Table of Contents

A schema-driven, composable full-stack framework for Phoenix. Declare your domain; sail with the generated code.

## Pages

- [README](readme.md)
- [License](license.md)
- [Notice](notice.md)

- Guides
  - [Getting started](getting_started.md)
  - [DSL reference](dsl.md)
  - [Generators](generators.md)
  - [Multi-tenancy](multi_tenancy.md)
  - [API versioning](versioning.md)
  - [GraphQL with Absinthe](graphql.md)
  - [Svelte frontend (render modes)](livesvelte.md)
  - [Live runtime](live_runtime.md)
  - [Flows](flows.md)
  - [Regeneration](regeneration.md)
  - [Authentication](auth.md)
  - [Policies](policies.md)
  - [Validation (changeset errors + i18n)](validation.md)
  - [Testing Caravela](testing.md)
  - [MCP server](mcp.md)

- Meta
  - [Changelog](changelog.md)

## Modules

- [Caravela](Caravela.md): Caravela — a schema-driven, composable full-stack framework for Phoenix.
- [Caravela.Auth](Caravela.Auth.md): Trait-based authentication support.
- [Caravela.ChangesetTranslator](Caravela.ChangesetTranslator.md): Translate `Ecto.Changeset` errors into a structured, i18n-ready
shape
- [Caravela.Compiler](Caravela.Compiler.md): Compile-time hook that assembles and validates a domain IR.
- [Caravela.Domain](Caravela.Domain.md): DSL entry point. `use Caravela.Domain` in a module to declare a domain
- [Caravela.Error](Caravela.Error.md): Uniform error shape emitted by every Caravela read / write path.
- [Caravela.Errors](Caravela.Errors.md): Structured compile-time errors for Caravela's DSL and generators.
- [Caravela.Flow](Caravela.Flow.md): Top-level entry point for the ephemeral async-workflow system.
- [Caravela.Flow.DSL](Caravela.Flow.DSL.md): DSL macros for declaring flows. Pulled in via `use Caravela.Flow`.
- [Caravela.Flow.Runner](Caravela.Flow.Runner.md): GenServer that executes a flow step tree one step at a time.
- [Caravela.Flow.Steps](Caravela.Flow.Steps.md): Step primitives that make up a flow tree.
- [Caravela.Flow.Steps.Debounce](Caravela.Flow.Steps.Debounce.md): Wait for `ms` of state-stability, then advance.
- [Caravela.Flow.Steps.Each](Caravela.Flow.Steps.Each.md): Iterate a collection already in state under `key`. For every item,
invoke `fun.(item, state)`. The fun may return
- [Caravela.Flow.Steps.Parallel](Caravela.Flow.Steps.Parallel.md): Invoke `tasks_fn.(state)` to build a list of zero-arity funs, run
them all concurrently, and collect each one's return under the
`collect_as` key in state.

- [Caravela.Flow.Steps.Race](Caravela.Flow.Steps.Race.md): Run every fun in `tasks` concurrently, take the first to return.
The winner is stored under the `collect_as` key.

- [Caravela.Flow.Steps.Repeat](Caravela.Flow.Steps.Repeat.md): Loop `step` forever. Break by raising or via `{:error, _}` from Run.
- [Caravela.Flow.Steps.Run](Caravela.Flow.Steps.Run.md): Run `fun.(state)` once. The return value drives what happens next
- [Caravela.Flow.Steps.Sequence](Caravela.Flow.Steps.Sequence.md): Run `steps` in order.
- [Caravela.Flow.Steps.SetState](Caravela.Flow.Steps.SetState.md): Synchronously apply `fun.(state)` → new state.
- [Caravela.Flow.Steps.Wait](Caravela.Flow.Steps.Wait.md): Pause for `ms` milliseconds, then advance.
- [Caravela.Flow.Steps.WaitUntil](Caravela.Flow.Steps.WaitUntil.md): Block until `fun.(state)` returns truthy, then advance.
- [Caravela.Flow.Supervisor](Caravela.Flow.Supervisor.md): DynamicSupervisor for flow runner processes.
- [Caravela.Gen.Auth](Caravela.Gen.Auth.md): Generates the authentication stack for a `Caravela.Schema.Domain`
whose authenticatable entity declares an `authenticatable` block.
- [Caravela.Gen.AuthLive](Caravela.Gen.AuthLive.md): Generates Phoenix LiveView pages that mount the auth Svelte
components produced by `Caravela.Gen.AuthSvelte`.
- [Caravela.Gen.AuthSvelte](Caravela.Gen.AuthSvelte.md): Generates typed Svelte components for the authentication UI from a
domain whose authenticatable entity declares an `authenticatable`
block.
- [Caravela.Gen.Context](Caravela.Gen.Context.md): Generates a Phoenix context module for a `Caravela.Schema.Domain`.
- [Caravela.Gen.Controller](Caravela.Gen.Controller.md): Generates one Phoenix JSON controller per entity in a
`Caravela.Schema.Domain`.
- [Caravela.Gen.Custom](Caravela.Gen.Custom.md): Preserves user-authored code across regenerations.
- [Caravela.Gen.EctoSchema](Caravela.Gen.EctoSchema.md): Generates one Ecto schema module per entity from a compiled
`Caravela.Schema.Domain`.
- [Caravela.Gen.GraphQL](Caravela.Gen.GraphQL.md): Generates Absinthe types, queries, and mutations from a
`Caravela.Schema.Domain`.
- [Caravela.Gen.LiveRoute](Caravela.Gen.LiveRoute.md): Pure-string router-snippet renderer — a debugging / legacy helper.
- [Caravela.Gen.LiveView](Caravela.Gen.LiveView.md): Generates Phoenix LiveView modules that mount Svelte components via
LiveSvelte.
- [Caravela.Gen.LiveViewTest](Caravela.Gen.LiveViewTest.md): Generates ExUnit tests for every `:live` entity's three LiveView
modules (Index / Show / Form). One test file per entity,
organized as `describe` blocks per module with one test per
action — a CI-ready skeleton the developer fills in with
fixtures and assertions specific to their domain.
- [Caravela.Gen.Migration](Caravela.Gen.Migration.md): Generates a single Ecto migration file for every entity in a
`Caravela.Schema.Domain`.
- [Caravela.Gen.RestController](Caravela.Gen.RestController.md): Generates Phoenix controllers that render Svelte components via
`caravela_svelte`'s Inertia-style transport (`:rest` render mode).
- [Caravela.Gen.RestControllerTest](Caravela.Gen.RestControllerTest.md): Generates ExUnit tests for every `:rest` entity's Phoenix
controller. One test file per entity, one `describe` per action,
one test per happy/unhappy path. Uses the standard
`Phoenix.ConnTest` stack and assumes `*.ConnCase` under
`test/support/conn_case.ex`.
- [Caravela.Gen.RouterScope](Caravela.Gen.RouterScope.md): Renders the router scope snippet a developer needs to paste into
their `lib/<app>_web/router.ex` after generating controllers.
- [Caravela.Gen.Svelte](Caravela.Gen.Svelte.md): Generates typed Svelte components and a TypeScript interfaces file
from a `Caravela.Schema.Domain`.
- [Caravela.Gen.SvelteForm](Caravela.Gen.SvelteForm.md): Generates a dynamic Svelte form component from a module that declares
`use Caravela.Live.Form`. The emitted component receives
`field_visibility` and `async_errors` as props and wraps visibility-
gated fields in `{#if field_visibility.<name>}` blocks.
- [Caravela.Gen.SvelteTest](Caravela.Gen.SvelteTest.md): Generates Vitest + `@testing-library/svelte` smoke tests — one
`*.test.ts` file colocated next to every generated Svelte
component. The tests assert the component mounts with minimally
valid props and exposes key entity fields in the DOM. They are
deliberately thin — a CI oracle that catches "my prop contract
changed and the component now throws", not a full UX regression
suite.
- [Caravela.IR](Caravela.IR.md): Public, JSON-serializable view of a compiled Caravela domain.
- [Caravela.Live.Domain](Caravela.Live.Domain.md): DSL for declaring a server-side state machine that a LiveView can mount
via `Caravela.Live.Template`. Mirrors the Ballerina "domain logic"
layer: state fields, named updaters that transition the state, and
event handlers that run on messages pushed from the Svelte side.
- [Caravela.Live.Encoders](Caravela.Live.Encoders.md): Protocol implementations so Ecto/Decimal types survive the trip from
the LiveView socket to a LiveSvelte Svelte component as sensible
JSON values instead of struct dumps.
- [Caravela.Live.Form](Caravela.Live.Form.md): DSL for declaring form-visibility predicates and async-validation
rules on top of `Caravela.Live.Domain`.
- [Caravela.Live.OnMount](Caravela.Live.OnMount.md): `on_mount` callback that assembles the per-request context map the
generated Caravela contexts expect (`%{current_user: ..., tenant: ...}`)
and assigns it to `socket.assigns.context`.
- [Caravela.Live.Template](Caravela.Live.Template.md): `use` macro that binds a Phoenix LiveView to a `Caravela.Live.Domain`
module.
- [Caravela.Live.Updater](Caravela.Live.Updater.md): Composable state updater functions for LiveView assigns.
- [Caravela.MCP](Caravela.MCP.md): [Model Context Protocol](https://modelcontextprotocol.io) server for
Caravela.
- [Caravela.MCP.Protocol](Caravela.MCP.Protocol.md): JSON-RPC 2.0 message encoding, decoding, and builders for the
Caravela MCP server.
- [Caravela.MCP.Router](Caravela.MCP.Router.md): Method dispatch for the Caravela MCP server.
- [Caravela.MCP.Server](Caravela.MCP.Server.md): Stdio event loop for the Caravela MCP server.
- [Caravela.MCP.Tool](Caravela.MCP.Tool.md): Behaviour + registry for Caravela MCP tools.
- [Caravela.MCP.Tool.DescribeDomain](Caravela.MCP.Tool.DescribeDomain.md): MCP tool: return the full Caravela IR for a domain module.
- [Caravela.MCP.Tool.DescribeEntity](Caravela.MCP.Tool.DescribeEntity.md): MCP tool: return the IR for a single entity within a Caravela
domain (fields, relations, policy, auth).
- [Caravela.MCP.Tool.DescribeFrontendMode](Caravela.MCP.Tool.DescribeFrontendMode.md): MCP tool: report the render-mode configuration for a Caravela
domain's entities — which ones use `:live` vs `:rest`, and whether
`:rest` entities opt into SSE realtime.
- [Caravela.MCP.Tool.ListEntities](Caravela.MCP.Tool.ListEntities.md): MCP tool: list the entity names declared by a Caravela domain.
- [Caravela.MCP.Tool.ValidateDsl](Caravela.MCP.Tool.ValidateDsl.md): MCP tool: compile a candidate Caravela domain DSL and report any
errors as structured data.
- [Caravela.Naming](Caravela.Naming.md): Naming conventions translating domain declarations into Elixir module
names, file paths, and Postgres table names.
- [Caravela.Policy](Caravela.Policy.md): Intermediate Representation for Caravela's triple-target policy
system.
- [Caravela.Policy.ActionGate](Caravela.Policy.ActionGate.md): A policy `allow :action, fn ... end` rule. `action` is one of
`:create`, `:update`, `:delete`. `arity` is 1 or 2.

- [Caravela.Policy.Entry](Caravela.Policy.Entry.md): The compiled IR for a single `policy :entity do ... end` block.
- [Caravela.Policy.FieldRule](Caravela.Policy.FieldRule.md): A field-level visibility rule. `arity` is either 1 (depends only on
the actor — static per request) or 2 (depends on actor + record —
evaluated per-row).

- [Caravela.Policy.Scope](Caravela.Policy.Scope.md): A row-level scope rule for an entity.
- [Caravela.Router](Caravela.Router.md): Router macros that register a Caravela domain's frontend routes at
compile time. The router stays in sync with the domain's DSL — add
an entity, regenerate, restart the server, and the routes exist.
- [Caravela.Schema](Caravela.Schema.md): Internal Intermediate Representation (IR) for a Caravela domain.
- [Caravela.Schema.AuthConfig](Caravela.Schema.AuthConfig.md): Authentication configuration attached to an entity via the
`authenticatable` DSL block.
- [Caravela.Schema.Domain](Caravela.Schema.Domain.md): A whole domain: the top-level IR produced by compilation.
- [Caravela.Schema.Entity](Caravela.Schema.Entity.md): A domain entity (table).
- [Caravela.Schema.Field](Caravela.Schema.Field.md): A single field on an entity.
- [Caravela.Schema.Hook](Caravela.Schema.Hook.md): A lifecycle hook declared in the DSL via `on_create`, `on_update`, or
`on_delete`.
- [Caravela.Schema.Relation](Caravela.Schema.Relation.md): A relation between two entities.
- [Caravela.Tenant](Caravela.Tenant.md): Row-level multi-tenancy support.
- [Caravela.Types](Caravela.Types.md): Type mapping between the Caravela DSL, Ecto, and Postgres.

- Exceptions
  - [Caravela.DSLError](Caravela.DSLError.md): Raised from Caravela DSL macros when a caller uses them incorrectly.
Carries a four-part message (what went wrong, what Caravela got, a
suggested fix, a docs URL). See `Caravela.Errors` for helpers that
build one of these from a `Macro.Env`.

  - [Caravela.GenError](Caravela.GenError.md): Raised from `Caravela.Gen.*` functions and `mix caravela.gen.*`
tasks when a generator can't produce a file given the current
domain shape. Shares the four-part message shape with
`Caravela.DSLError`.

## Mix Tasks

- [mix caravela.check](Mix.Tasks.Caravela.Check.md): One-stop validation for a Caravela-using project.
- [mix caravela.gen](Mix.Tasks.Caravela.Gen.md): All-in-one generator. Produces
- [mix caravela.gen.api](Mix.Tasks.Caravela.Gen.Api.md): Generates one Phoenix JSON controller per entity in the domain and
prints a router scope snippet the developer can paste into
`lib/<app>_web/router.ex`.
- [mix caravela.gen.auth](Mix.Tasks.Caravela.Gen.Auth.md): Generates the authentication stack from a Caravela domain whose
authenticatable entity declares an `authenticatable` block.
- [mix caravela.gen.context](Mix.Tasks.Caravela.Gen.Context.md): Generates a Phoenix context module for the given domain, with CRUD
functions for every entity, authorization via `can_*` permissions,
and lifecycle hooks via `on_*`.
- [mix caravela.gen.graphql](Mix.Tasks.Caravela.Gen.Graphql.md): Generates an Absinthe schema layer for the given domain: one file each
for object types, queries, and mutations. All three delegate to the
generated context module, so authorization, hooks, and multi-tenant
scoping flow through the Absinthe resolvers for free.
- [mix caravela.gen.live](Mix.Tasks.Caravela.Gen.Live.md): Generates the full Svelte frontend layer for a Caravela domain
- [mix caravela.gen.schema](Mix.Tasks.Caravela.Gen.Schema.md): Generates Ecto schemas and a migration file from a Caravela domain
declaration.
- [mix caravela.info](Mix.Tasks.Caravela.Info.md): Print a terminal-friendly summary of a compiled Caravela domain —
domain-level flags, every entity's fields / relations / policy /
auth config, and top-level counts.
- [mix caravela.ir](Mix.Tasks.Caravela.Ir.md): Print the public Intermediate Representation of a Caravela domain
as JSON. Intended for consumption by editors, LLMs, and external
tooling that wants a structured view of the domain without parsing
Elixir source.
- [mix caravela.mcp](Mix.Tasks.Caravela.Mcp.md): Start the [Model Context Protocol](https://modelcontextprotocol.io)
server for the current Caravela project on stdio.

