# cratis_arc v0.1.0 - Table of Contents

> Opinionated CQRS application framework for Phoenix and Plug on Cratis Chronicle, with model-bound commands and queries, validation, authorization, observable queries and opt-in TypeScript proxy generation

## Pages

- [Arc for Elixir](readme.md)

## Modules

- [Arc](Arc.md): Arc for Elixir: an opinionated CQRS application framework for Phoenix and Plug, on Cratis
Chronicle.
- [Arc.Authentication.FromAssigns](Arc.Authentication.FromAssigns.md): Reads the principal from `conn.assigns[:arc_principal]` (an `Arc.Principal`), or builds one from
the signed-in user your own authentication assigned: `conn.assigns.current_scope.user` (the
`phx.gen.auth` shape) or `conn.assigns.current_user`, a map with `:id` and optionally `:name`,
`:email` and `:roles`.

- [Arc.Authentication.MicrosoftIdentityPlatform](Arc.Authentication.MicrosoftIdentityPlatform.md): Authenticates from the Microsoft identity platform headers an ingress supplies:
`x-ms-client-principal` (a base64 client principal), `x-ms-client-principal-id` and
`x-ms-client-principal-name`. These are what Azure App Service, Container Apps, Cratis AuthProxy
and the Lens browser extension send.
- [Arc.Authorization](Arc.Authorization.md): Authorization declarations and checks for commands and queries.
- [Arc.Chronicle](Arc.Chronicle.md): Appends the events a command returned to Chronicle.
- [Arc.CommandResult](Arc.CommandResult.md): The outcome of executing a command, shaped as the Arc command result envelope.

- [Arc.Descriptor](Arc.Descriptor.md): Compile-time metadata of a command or a read model, exposed as `__arc__/0` on the artifact.
- [Arc.Descriptor.Query](Arc.Descriptor.Query.md): Metadata of one query on a read model.
- [Arc.Filter](Arc.Filter.md): A cross-cutting rule that runs for commands and queries, whatever their own declarations say.
- [Arc.Identity](Arc.Identity.md): The identity the frontend shows: who the caller is, their roles, and application-specific details.
- [Arc.Identity.Context](Arc.Identity.Context.md): The input of an identity details provider: the authenticated caller.
- [Arc.Identity.Details](Arc.Identity.Details.md): The result of an identity details provider, when it needs more than `{:ok, details}`:
whether the user may enter the application at all, and the details to show.

- [Arc.Identity.OnBehalfOf](Arc.Identity.OnBehalfOf.md): Acting on behalf of a user: verifies the RS256 assertion Cratis AuthProxy signs for an on-behalf
session and attaches the actor to the represented user's principal.
- [Arc.Identity.Provider](Arc.Identity.Provider.md): Supplies the application-specific details of the signed-in user.
- [Arc.Identity.Result](Arc.Identity.Result.md): The resolved identity, as served from `/.cratis/me`.

- [Arc.Identity.SignedForwarding](Arc.Identity.SignedForwarding.md): Signed forwarded identity: an ingress attests the identity headers it sends with an
HMAC-SHA256 over the request, so the headers are no longer trusted merely because they are present.
- [Arc.Identity.Tenant](Arc.Identity.Tenant.md): A development tenant, as listed by `/.cratis/tenants`.
- [Arc.Identity.TenantsProvider](Arc.Identity.TenantsProvider.md): Lists the tenants a tool such as Lens offers to select.
- [Arc.Identity.User](Arc.Identity.User.md): A development user, as listed by `/.cratis/users` for tools such as Lens.
- [Arc.Identity.UsersProvider](Arc.Identity.UsersProvider.md): Lists the development users a tool such as Lens offers to sign in as.
- [Arc.Naming](Arc.Naming.md): Name conversions shared by routing, the wire format and proxy generation.
- [Arc.Page](Arc.Page.md): A page of results from a query that pages itself, for example a query over a database.
- [Arc.Plug.SseHub](Arc.Plug.SseHub.md): The multiplexed Server-Sent Events hub at `/.cratis/queries/sse`.
- [Arc.Policy](Arc.Policy.md): A named authorization policy. Register it on the application with `policies: [can_publish: MyApp.Policies.CanPublish]`.

- [Arc.QueryResult](Arc.QueryResult.md): The outcome of executing a query, shaped as the Arc query result envelope.

- [Arc.Schema.Field](Arc.Schema.Field.md): Typed metadata for one declared field.
- [Arc.Subscription](Arc.Subscription.md): One live subscription to an observable query.
- [Arc.Tenancy](Arc.Tenancy.md): Resolves which tenant a request is for.
- [Arc.Test.Case](Arc.Test.Case.md): `ExUnit.CaseTemplate` that starts an in-memory Chronicle client per test and puts an
`Arc.Test.Scenario` in the context as `:arc`.
- [Arc.Test.Scenario](Arc.Test.Scenario.md): The application and Chronicle test client of one test.
- [Arc.Types](Arc.Types.md): The field types Arc understands, and conversion between wire values and Elixir values.
- [Arc.Watch](Arc.Watch.md): A source of change notifications for observable queries.
- [Arc.Wire](Arc.Wire.md): Converts Elixir values to the JSON-ready shape of the Arc wire format.

- Authoring
  - [Arc.Command](Arc.Command.md): A model-bound command: a module whose struct is the request and whose `handle/2` decides.
  - [Arc.ReadModel](Arc.ReadModel.md): A read model container: the module that declares queries over one model type.
  - [Arc.Schema](Arc.Schema.md): Declares the fields of a command, a parameter object or a nested type.
  - [Arc.Validation](Arc.Validation.md): Builds validation results and evaluates declarative field rules.
  - [Arc.ValidationResult](Arc.ValidationResult.md): One validation outcome, carried in the command and query result envelopes.

- Runtime
  - [Arc.Application](Arc.Application.md): The runtime of one Arc application: discovery, configuration and the processes that serve
observable queries.
  - [Arc.Context](Arc.Context.md): Request-scoped facts handed to every command, query, validator and policy.
  - [Arc.Notifier](Arc.Notifier.md): Tells observable queries to run again.
  - [Arc.Pipeline](Arc.Pipeline.md): Runs commands and queries: authorize, bind, validate, provide, handle, record.
  - [Arc.Principal](Arc.Principal.md): The authenticated caller of a command or query.

- Hosting
  - [Arc.Authentication](Arc.Authentication.md): Authentication handlers turn an incoming request into an `Arc.Principal`.
  - [Arc.Plug](Arc.Plug.md): The Arc HTTP contract on Plug.
  - [Arc.Plug.Hub](Arc.Plug.Hub.md): The multiplexed WebSocket hub at `/.cratis/queries/ws`.
  - [Arc.Plug.SinglePage](Arc.Plug.SinglePage.md): Serves a single-page application: static files from a directory, and the `index.html` for
every other `GET` that accepts HTML, so client-side routes survive a refresh.

- Phoenix
  - [Arc.LiveView](Arc.LiveView.md): The Arc commands and queries, called in-process from a LiveView.
  - [Arc.LiveView.Form](Arc.LiveView.Form.md): A command as a Phoenix form.

- Proxy generation
  - [Arc.ProxyGenerator](Arc.ProxyGenerator.md): Generates TypeScript proxies for the React frontend packages (`@cratis/arc`, `@cratis/arc.react`)
from the commands and read models of an `Arc.Application`.

- Testing
  - [Arc.Test](Arc.Test.md): ExUnit support that runs the real Arc pipelines against Chronicle's in-memory kernel.

## Mix Tasks

- [mix arc.gen.proxies](Mix.Tasks.Arc.Gen.Proxies.md): Generates TypeScript proxies for the React frontend. Proxy generation is opt-in.
- [mix compile.arc](Mix.Tasks.Compile.Arc.md): Regenerates TypeScript proxies after each compile. Opt in by adding the compiler