# blackuprise/vicander architecture

> Architecture diagram of the GitHub repository blackuprise/vicander, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/blackuprise/vicander
- Repository: https://github.com/blackuprise/vicander

## Overview

Vicander is an Elixir DDD framework, not a standalone application: an adopting application defines domain types and use cases, configures a repository, and starts the framework’s event processes. Its main write workflow validates and executes a command, persists an aggregate with its events, then delivers those events to handlers and projections through the outbox. The README also documents read-only queries, repository-backed projections, and MCP access. Some subsystem paths and links are documented but unsampled; those links cite the README rather than implying source inspection.

Main entry points: [`lib/ddd/use_cases/command.ex`](https://github.com/blackuprise/vicander/blob/master/lib/ddd/use_cases/command.ex) (Commands), [`lib/ddd/mcp/server.ex`](https://github.com/blackuprise/vicander/blob/master/lib/ddd/mcp/server.ex) (MCP server), [`lib/ddd/persistence/repository.ex`](https://github.com/blackuprise/vicander/blob/master/lib/ddd/persistence/repository.ex) (Repository ports), [`lib/ddd/use_cases/query.ex`](https://github.com/blackuprise/vicander/blob/master/lib/ddd/use_cases/query.ex) (Queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_domain["Domain model"]
  node_model["Domain types"]
  node_specs["Specifications<br/>[specification.ex]"]
  node_identity["Identity<br/>[identity.ex]"]
end

subgraph group_usecases["Use cases"]
  node_commands["Commands<br/>[command.ex]"]
  node_queries["Queries<br/>[query.ex]"]
  node_listing["Listing and pagination<br/>[listing.ex]"]
end

subgraph group_persistence["Persistence"]
  node_uow["Unit of work<br/>[unit_of_work.ex]"]
  node_repo["Repository ports<br/>[repository.ex]"]
  node_ecto["Ecto repository<br/>[ecto.ex]"]
  node_memory["In-memory repository"]
  node_projection["Projections<br/>[projection.ex]"]
end

subgraph group_events["Events"]
  node_outbox[("Transactional outbox<br/>[flush.ex]")]
  node_poller["Outbox poller<br/>[poller.ex]"]
  node_bus["Event bus<br/>[event_bus.ex]"]
  node_handlers["Event handlers<br/>[event_handler.ex]"]
  node_deadletters["Dead-letter handling"]
end

subgraph group_interfaces["Interfaces and operations"]
  node_mcp["MCP server<br/>[server.ex]"]
  node_registry["MCP registry<br/>[registry.ex]"]
  node_transports["MCP transports"]
  node_operations["Health and telemetry"]
end

node_app(("Application caller"))

node_app -->|"calls"| node_commands
node_commands -->|"validates and operates"| node_model
node_model -->|"checks invariants"| node_specs
node_model -->|"uses identity"| node_identity
node_commands -->|"executes transaction"| node_uow
node_commands -->|"saves aggregate"| node_repo
node_uow -.->|"coordinates persistence"| node_ecto
node_repo -->|"implemented by"| node_ecto
node_repo -->|"implemented by"| node_memory
node_ecto -->|"writes events"| node_outbox
node_outbox -->|"supplies events"| node_poller
node_poller -->|"publishes events"| node_bus
node_bus -->|"dispatches events"| node_handlers
node_bus -->|"notifies projections"| node_projection
node_poller -->|"notifies on failure"| node_deadletters
node_app -->|"calls"| node_queries
node_queries -->|"reads through"| node_repo
node_app -.->|"requests listing"| node_listing
node_listing -.->|"queries repository"| node_repo
node_app -->|"connects client"| node_mcp
node_mcp -->|"builds registry"| node_registry
node_mcp -->|"serves over"| node_transports
node_mcp -->|"exposes tools"| node_commands
node_mcp -->|"exposes tools"| node_queries
node_commands -.->|"emits telemetry"| node_operations
node_queries -->|"emits telemetry"| node_operations

click node_model "https://github.com/blackuprise/vicander/tree/master/lib/ddd/model"
click node_specs "https://github.com/blackuprise/vicander/blob/master/lib/ddd/model/specification.ex"
click node_identity "https://github.com/blackuprise/vicander/blob/master/lib/ddd/model/identity.ex"
click node_commands "https://github.com/blackuprise/vicander/blob/master/lib/ddd/use_cases/command.ex"
click node_queries "https://github.com/blackuprise/vicander/blob/master/lib/ddd/use_cases/query.ex"
click node_listing "https://github.com/blackuprise/vicander/blob/master/lib/ddd/use_cases/listing.ex"
click node_uow "https://github.com/blackuprise/vicander/blob/master/lib/ddd/persistence/unit_of_work.ex"
click node_repo "https://github.com/blackuprise/vicander/blob/master/lib/ddd/persistence/repository.ex"
click node_ecto "https://github.com/blackuprise/vicander/blob/master/lib/ddd/persistence/repository/ecto.ex"
click node_memory "https://github.com/blackuprise/vicander/blob/master/lib/ddd/persistence/in_memory_repository.ex"
click node_projection "https://github.com/blackuprise/vicander/blob/master/lib/ddd/persistence/projection.ex"
click node_outbox "https://github.com/blackuprise/vicander/blob/master/lib/ddd/persistence/repository/ecto/flush.ex"
click node_poller "https://github.com/blackuprise/vicander/blob/master/lib/ddd/events/outbox/poller.ex"
click node_bus "https://github.com/blackuprise/vicander/blob/master/lib/ddd/events/event_bus.ex"
click node_handlers "https://github.com/blackuprise/vicander/blob/master/lib/ddd/events/event_handler.ex"
click node_deadletters "https://github.com/blackuprise/vicander/blob/master/lib/ddd/events/outbox/dead_letter_handler.ex"
click node_mcp "https://github.com/blackuprise/vicander/blob/master/lib/ddd/mcp/server.ex"
click node_registry "https://github.com/blackuprise/vicander/blob/master/lib/ddd/mcp/registry.ex"
click node_transports "https://github.com/blackuprise/vicander/tree/master/lib/ddd/mcp"
click node_operations "https://github.com/blackuprise/vicander/tree/master/lib/ddd/operations"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_model,node_specs,node_identity toneBlue
class node_commands,node_queries,node_listing toneAmber
class node_uow,node_repo,node_ecto,node_memory,node_projection toneMint
class node_outbox,node_poller,node_bus,node_handlers,node_deadletters toneRose
class node_mcp,node_registry,node_transports,node_operations,node_app toneIndigo
```

## Components

### Domain model

- [Domain types](https://github.com/blackuprise/vicander/tree/master/lib/ddd/model): `lib/ddd/model`
- [Specifications](https://github.com/blackuprise/vicander/blob/master/lib/ddd/model/specification.ex): `lib/ddd/model/specification.ex`
- [Identity](https://github.com/blackuprise/vicander/blob/master/lib/ddd/model/identity.ex): `lib/ddd/model/identity.ex`

### Use cases

- [Commands](https://github.com/blackuprise/vicander/blob/master/lib/ddd/use_cases/command.ex): `lib/ddd/use_cases/command.ex`
- [Queries](https://github.com/blackuprise/vicander/blob/master/lib/ddd/use_cases/query.ex): `lib/ddd/use_cases/query.ex`
- [Listing and pagination](https://github.com/blackuprise/vicander/blob/master/lib/ddd/use_cases/listing.ex): `lib/ddd/use_cases/listing.ex`

### Persistence

- [Unit of work](https://github.com/blackuprise/vicander/blob/master/lib/ddd/persistence/unit_of_work.ex): `lib/ddd/persistence/unit_of_work.ex`
- [Repository ports](https://github.com/blackuprise/vicander/blob/master/lib/ddd/persistence/repository.ex): `lib/ddd/persistence/repository.ex`
- [Ecto repository](https://github.com/blackuprise/vicander/blob/master/lib/ddd/persistence/repository/ecto.ex): `lib/ddd/persistence/repository/ecto.ex`
- [In-memory repository](https://github.com/blackuprise/vicander/blob/master/lib/ddd/persistence/in_memory_repository.ex): `lib/ddd/persistence/in_memory_repository.ex`
- [Projections](https://github.com/blackuprise/vicander/blob/master/lib/ddd/persistence/projection.ex): `lib/ddd/persistence/projection.ex`

### Events

- [Transactional outbox](https://github.com/blackuprise/vicander/blob/master/lib/ddd/persistence/repository/ecto/flush.ex): `lib/ddd/persistence/repository/ecto/flush.ex`
- [Outbox poller](https://github.com/blackuprise/vicander/blob/master/lib/ddd/events/outbox/poller.ex): `lib/ddd/events/outbox/poller.ex`
- [Event bus](https://github.com/blackuprise/vicander/blob/master/lib/ddd/events/event_bus.ex): `lib/ddd/events/event_bus.ex`
- [Event handlers](https://github.com/blackuprise/vicander/blob/master/lib/ddd/events/event_handler.ex): `lib/ddd/events/event_handler.ex`
- [Dead-letter handling](https://github.com/blackuprise/vicander/blob/master/lib/ddd/events/outbox/dead_letter_handler.ex): `lib/ddd/events/outbox/dead_letter_handler.ex`

### Interfaces and operations

- [MCP server](https://github.com/blackuprise/vicander/blob/master/lib/ddd/mcp/server.ex): `lib/ddd/mcp/server.ex`
- [MCP registry](https://github.com/blackuprise/vicander/blob/master/lib/ddd/mcp/registry.ex): `lib/ddd/mcp/registry.ex`
- [MCP transports](https://github.com/blackuprise/vicander/tree/master/lib/ddd/mcp): `lib/ddd/mcp`
- [Health and telemetry](https://github.com/blackuprise/vicander/tree/master/lib/ddd/operations): `lib/ddd/operations`

### Other components

- **Application caller**

## Connections

- Application caller → Commands: calls (evidence: `README.md`)
- Commands → Domain types: validates and operates (evidence: `README.md`)
- Domain types → Specifications: checks invariants (evidence: `README.md`)
- Domain types → Identity: uses identity (evidence: `README.md`)
- Commands → Unit of work: executes transaction (evidence: `README.md`)
- Commands → Repository ports: saves aggregate (evidence: `README.md`)
- Unit of work → Ecto repository: coordinates persistence
- Repository ports → Ecto repository: implemented by (evidence: `README.md`)
- Repository ports → In-memory repository: implemented by (evidence: `lib/ddd/persistence/in_memory_repository.ex`)
- Ecto repository → Transactional outbox: writes events (evidence: `README.md`)
- Transactional outbox → Outbox poller: supplies events (evidence: `README.md`)
- Outbox poller → Event bus: publishes events (evidence: `README.md`)
- Event bus → Event handlers: dispatches events (evidence: `README.md`)
- Event bus → Projections: notifies projections (evidence: `README.md`)
- Outbox poller → Dead-letter handling: notifies on failure (evidence: `lib/ddd/events/outbox/dead_letter_handler.ex`)
- Application caller → Queries: calls (evidence: `lib/ddd/use_cases/query.ex`)
- Queries → Repository ports: reads through (evidence: `README.md`)
- Application caller → Listing and pagination: requests listing
- Listing and pagination → Repository ports: queries repository
- Application caller → MCP server: connects client (evidence: `lib/ddd/mcp/server.ex`)
- MCP server → MCP registry: builds registry (evidence: `lib/ddd/mcp/server.ex`)
- MCP server → MCP transports: serves over (evidence: `lib/ddd/mcp/server.ex`)
- MCP server → Commands: exposes tools (evidence: `lib/ddd/mcp/server.ex`)
- MCP server → Queries: exposes tools (evidence: `lib/ddd/mcp/server.ex`)
- Commands → Health and telemetry: emits telemetry
- Queries → Health and telemetry: emits telemetry (evidence: `lib/ddd/use_cases/query.ex`)
