# vicander v0.1.1 - Table of Contents

> Domain-Driven Design framework for Elixir: entities, aggregates, specifications, commands, queries, an event outbox, projections and an MCP server

## Pages

- [Vicander](readme.md)
- [Changelog](changelog.md)

## Modules

- [DDD](DDD.md): The Domain-Driven Design framework: entities, aggregates, value objects, specifications,
commands, events and the outbox. It knows nothing about any application built on it.

- [DDD.Dialect](DDD.Dialect.md): The few things that differ between databases.
- [DDD.Dialect.Postgres](DDD.Dialect.Postgres.md): `DDD.Dialect` for `Ecto.Adapters.Postgres`.
- [DDD.Health.Query](DDD.Health.Query.md): `DDD.Health.check/0` as a `DDD.Query`, so it can be listed in an MCP server (or anywhere a
query is accepted)
- [DDD.Test](DDD.Test.md): Helpers for testing an application built on the framework.
- [DDD.Type.Json](DDD.Type.Json.md): Ecto type behind the `:json` field type: any JSON term (map or list) in a `jsonb` column.
Ecto's own `:map` refuses lists.

- Model
  - [DDD.Aggregate](DDD.Aggregate.md): Behaviour and macros for Domain-Driven Design Aggregate Roots.
  - [DDD.BoundedContext](DDD.BoundedContext.md): Macro for declaring a Bounded Context.
  - [DDD.DomainService](DDD.DomainService.md): Marker for Domain Services — stateless, domain-logic-only modules.
  - [DDD.Entity](DDD.Entity.md): Behaviour and macros for Domain-Driven Design Entities.
  - [DDD.Error](DDD.Error.md): Structured error produced by the framework.
  - [DDD.Identity](DDD.Identity.md): Identities of entities and aggregates, and generating them.
  - [DDD.Money](DDD.Money.md): An amount of money in one currency, as a value object.
  - [DDD.Specification](DDD.Specification.md): Specification pattern: a named, reusable, composable business rule.
  - [DDD.Type](DDD.Type.md): The field types of entities, aggregates and value objects, and everything the framework
does with them: checking a value, storing it in Postgres, and writing it as JSON.
  - [DDD.ValueObject](DDD.ValueObject.md): Behaviour and macros for Domain-Driven Design Value Objects.

- Use cases
  - [DDD.Command](DDD.Command.md): A command is the input of one use case, and it carries its own handler.
  - [DDD.Filter](DDD.Filter.md): A small, safe filter language that becomes a SQL `WHERE`, for the listing functions of
`DDD.Repository.Ecto` adapters and `DDD.Projection`s (`list/1`, `page/1`, `slice/1`,
`count/1`).
  - [DDD.Listing](DDD.Listing.md): The listing functions shared by repository adapters (`DDD.Repository.Ecto`) and projections
(`DDD.Projection`): `list/1`, `page/1`, `slice/1` and `count/1`.
  - [DDD.Page](DDD.Page.md): One numbered page of a listing, with the totals. Returned by `page/1` on repository adapters
and projections
  - [DDD.Params](DDD.Params.md): The declared input of a use case: the fields, descriptions and validation that
`DDD.Command` and `DDD.Query` share.
  - [DDD.Query](DDD.Query.md): A query is the input of one read use case, and it carries its own handler.
  - [DDD.Slice](DDD.Slice.md): A window of a listing that continues from a cursor (keyset pagination). Returned by `slice/1`
on repository adapters and projections

- Events
  - [DDD.DomainEvent](DDD.DomainEvent.md): Behaviour and macros for Domain Events.
  - [DDD.EventBus](DDD.EventBus.md): Simple in-process pub/sub event bus.
  - [DDD.EventHandler](DDD.EventHandler.md): A handler for domain events delivered through the outbox.
  - [DDD.Outbox.DeadLetterHandler](DDD.Outbox.DeadLetterHandler.md): A supervised process that applies a `DDD.Outbox.DeadLetterPolicy` to dead-lettered events.
  - [DDD.Outbox.DeadLetterPolicy](DDD.Outbox.DeadLetterPolicy.md): Decides what to do with a dead-lettered event.
  - [DDD.Outbox.DeadLetterPolicy.Default](DDD.Outbox.DeadLetterPolicy.Default.md): The recommended default: **keep** every dead letter. The failure has already been logged at
error level and emitted as a `[:ddd, :outbox, :dead_letter]` telemetry event, so someone
looks at it and replays it by hand (`mix vic.outbox.replay`).
  - [DDD.Outbox.DeadLetters](DDD.Outbox.DeadLetters.md): Inspect and resolve dead-lettered outbox events.
  - [DDD.Outbox.Delivery](DDD.Outbox.Delivery.md): A row of `event_deliveries`: which handler already processed which event, and how.

  - [DDD.Outbox.Event](DDD.Outbox.Event.md): A row of the `domain_events` outbox table (see `mix vic.gen.outbox_migration`).
  - [DDD.Outbox.Poller](DDD.Outbox.Poller.md): GenServer that delivers the events in the `domain_events` outbox table to their handlers.
  - [DDD.Outbox.Pruner](DDD.Outbox.Pruner.md): Prunes the outbox on a timer (`DDD.Outbox.Retention`). Started by `DDD.Supervisor` when it is
given `retention: [older_than_days: 30]`; `:every_ms` sets how often (default: hourly).

  - [DDD.Outbox.Retention](DDD.Outbox.Retention.md): Deleting old events from the outbox, so `domain_events` doesn't grow forever.
  - [DDD.Supervisor](DDD.Supervisor.md): Starts what the framework needs at runtime, in the right order: the event bus, the handler
subscriptions, the outbox poller and the dead-letter handler. Put it in your supervision tree
after your repo

- Persistence
  - [DDD.InMemoryRepository](DDD.InMemoryRepository.md): Generic in-memory repository adapter. Ideal for tests.
  - [DDD.Migration](DDD.Migration.md): Snapshot-based migration generation for aggregates stored by `DDD.Repository.Ecto`.
  - [DDD.Projection](DDD.Projection.md): A read model: a denormalized table kept up to date by domain events.
  - [DDD.Repository](DDD.Repository.md): Port (interface) for DDD Repositories.
  - [DDD.Repository.Ecto](DDD.Repository.Ecto.md): Auto-generates a full Ecto repository adapter from a `DDD.Repository` port.
  - [DDD.Serializer](DDD.Serializer.md): Converts nested entities to JSON-ready maps and back.

- MCP
  - [DDD.MCP](DDD.MCP.md): The application as a [Model Context Protocol](https://modelcontextprotocol.io) server: an AI
client can call its commands and queries as tools and read its aggregates as resources.
  - [DDD.MCP.Args](DDD.MCP.Args.md): Turns the JSON arguments of a tool call into the typed attributes of a command or query.
  - [DDD.MCP.Json](DDD.MCP.Json.md): Turns the result of a command, query or repository lookup into JSON.
  - [DDD.MCP.Registry](DDD.MCP.Registry.md): What an MCP server exposes, checked once when the server is built.
  - [DDD.MCP.Schema](DDD.MCP.Schema.md): JSON Schema for the input of a command or query, built from its declared fields.
  - [DDD.MCP.Server](DDD.MCP.Server.md): Declares which commands, queries and aggregates an application offers over MCP.
  - [DDD.MCP.Stdio](DDD.MCP.Stdio.md): The stdio transport: one JSON-RPC message per line on standard input, one reply per line on
standard output. Standard output carries only protocol messages, so anything that logs must
write to standard error (`mix vic.mcp` arranges that).

- Operations
  - [DDD.Config](DDD.Config.md): The framework's application configuration, in one place.
  - [DDD.Health](DDD.Health.md): A health check for the parts of the framework that can fall behind silently: the database,
the outbox and the projections.
  - [DDD.Telemetry](DDD.Telemetry.md): The `:telemetry` events the framework emits, in one place.

## Mix Tasks

- [mix vic.gen.migration](Mix.Tasks.Vic.Gen.Migration.md): Generates the Ecto migration for an aggregate stored by `DDD.Repository.Ecto`.
- [mix vic.gen.outbox_migration](Mix.Tasks.Vic.Gen.OutboxMigration.md): Generates an Ecto migration for the DDD outbox `domain_events` table.
- [mix vic.health](Mix.Tasks.Vic.Health.md): Prints `DDD.Health.check/1` and exits non-zero unless everything is `ok`, so it can run as a
deploy gate or a container health probe.
- [mix vic.mcp](Mix.Tasks.Vic.Mcp.md): Serves a `DDD.MCP.Server` module as a Model Context Protocol server on standard input and
output, for an AI client to launch
- [mix vic.outbox.dead_letters](Mix.Tasks.Vic.Outbox.DeadLetters.md): Lists events the outbox gave up delivering (infrastructure failures that kept recurring).
- [mix vic.outbox.discard](Mix.Tasks.Vic.Outbox.Discard.md): Resolves a dead-lettered event as discarded: it stays in the table for the record, but
nothing will deliver it.
- [mix vic.outbox.prune](Mix.Tasks.Vic.Outbox.Prune.md): Deletes events older than a number of days from the outbox (`DDD.Outbox.Retention`).
- [mix vic.outbox.replay](Mix.Tasks.Vic.Outbox.Replay.md): Makes the outbox retry dead-lettered events from scratch.
- [mix vic.projection.rebuild](Mix.Tasks.Vic.Projection.Rebuild.md): Empties a projection's table and replays every stored event into it, in order.