# codeonym-oss/mediary architecture

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

- Interactive diagram: https://gitdiagram.com/codeonym-oss/mediary
- Repository: https://github.com/codeonym-oss/mediary

## Overview

Mediary is a typed Python mediator/CQRS runtime. Applications mark messages and handlers, scan or register them, then send requests, publish notifications, or consume streams; mediator dispatch applies matching behaviors and resolves handler dependencies. The graph also preserves the documented CQRS, DI integrations, built-in behaviors, and testing helpers. Edges are limited to README statements and source-index references; unsampled integration internals are not inferred.

Main entry points: [`src/mediary/_mediator.py`](https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_mediator.py) (Mediator), [`src/mediary/_behaviors.py`](https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_behaviors.py) (Behavior Pipeline), [`src/mediary/_handlers.py`](https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_handlers.py) (Handler Binding), [`src/mediary/kinds.py`](https://github.com/codeonym-oss/mediary/blob/main/src/mediary/kinds.py) (Message Kinds)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dispatch["Dispatch Runtime"]
  node_mediator["Mediator<br/>[_mediator.py]"]
  node_scan["Package Scan<br/>[_scan.py]"]
  node_handlers["Handler Binding<br/>[_handlers.py]"]
  node_resolver["Dependency Resolver<br/>[_resolving.py]"]
  node_pipeline["Behavior Pipeline<br/>[_behaviors.py]"]
end

subgraph group_messages["Message Capabilities"]
  node_markers["Message Markers<br/>[_markers.py]"]
  node_kinds["Message Kinds<br/>[kinds.py]"]
  node_cqrs["CQRS Types<br/>[cqrs.py]"]
  node_streaming["Stream Runtime<br/>[_streaming.py]"]
  node_publishing["Notification Publishing<br/>[_publishing.py]"]
end

subgraph group_integrations["Integrations"]
  node_dishka["Dishka Adapter<br/>[dishka.py]"]
  node_fastapi["FastAPI Adapter<br/>[fastapi.py]"]
  node_otel["OpenTelemetry Adapter<br/>[otel.py]"]
end

subgraph group_support["Runtime Support"]
  node_concurrency["Async Concurrency<br/>[_concurrency.py]"]
  node_retryable["Retry Markers<br/>[_retryable.py]"]
  node_errors["Runtime Errors<br/>[_errors.py]"]
  node_deprecation["Deprecation Support<br/>[_deprecation.py]"]
  node_builtins["Built-in Behaviors<br/>[behaviors.py]"]
  node_testing["Testing Helpers<br/>[testing.py]"]
end

node_app(("Application"))
node_di["DI Container"]
node_framework["FastAPI App"]
node_telemetry["Telemetry Backend"]

node_app -->|"sends messages"| node_mediator
node_app -->|"scans package"| node_scan
node_mediator -->|"scans handlers"| node_scan
node_mediator -->|"dispatches to"| node_handlers
node_mediator -->|"wraps dispatch"| node_pipeline
node_mediator -->|"publishes through"| node_publishing
node_mediator -->|"creates streams"| node_streaming
node_mediator -->|"configures"| node_resolver
node_scan -->|"finds marked handlers"| node_markers
node_handlers -->|"resolves dependencies"| node_resolver
node_handlers -->|"runs sync handlers"| node_concurrency
node_handlers -->|"raises binding errors"| node_errors
node_pipeline -->|"resolves behaviors"| node_resolver
node_pipeline -->|"matches message kinds"| node_markers
node_pipeline -->|"raises behavior errors"| node_errors
node_publishing -->|"runs concurrent handlers"| node_concurrency
node_cqrs -->|"defines CQRS kinds"| node_kinds
node_cqrs -->|"provides handler decorators"| node_handlers
node_cqrs -->|"supports stream queries"| node_streaming
node_kinds -->|"defines kind markers"| node_markers
node_kinds -->|"targets behavior kinds"| node_pipeline
node_builtins -->|"implements behaviors"| node_pipeline
node_builtins -->|"checks retry markers"| node_retryable
node_builtins -->|"uses async utilities"| node_concurrency
node_testing -->|"extends mediator"| node_mediator
node_dishka -->|"adapts mediator"| node_mediator
node_dishka -.->|"integrates container"| node_di
node_fastapi -->|"integrates mediator"| node_mediator
node_fastapi -.->|"integrates with"| node_framework
node_otel -->|"uses message kinds"| node_kinds
node_otel -.->|"exports tracing"| node_telemetry
node_errors -->|"uses compatibility aliases"| node_deprecation

click node_mediator "https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_mediator.py"
click node_scan "https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_scan.py"
click node_handlers "https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_handlers.py"
click node_resolver "https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_resolving.py"
click node_pipeline "https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_behaviors.py"
click node_markers "https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_markers.py"
click node_kinds "https://github.com/codeonym-oss/mediary/blob/main/src/mediary/kinds.py"
click node_cqrs "https://github.com/codeonym-oss/mediary/blob/main/src/mediary/cqrs.py"
click node_streaming "https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_streaming.py"
click node_publishing "https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_publishing.py"
click node_concurrency "https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_concurrency.py"
click node_retryable "https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_retryable.py"
click node_errors "https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_errors.py"
click node_deprecation "https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_deprecation.py"
click node_builtins "https://github.com/codeonym-oss/mediary/blob/main/src/mediary/behaviors.py"
click node_testing "https://github.com/codeonym-oss/mediary/blob/main/src/mediary/testing.py"
click node_dishka "https://github.com/codeonym-oss/mediary/blob/main/src/mediary/ext/dishka.py"
click node_fastapi "https://github.com/codeonym-oss/mediary/blob/main/src/mediary/ext/fastapi.py"
click node_otel "https://github.com/codeonym-oss/mediary/blob/main/src/mediary/ext/otel.py"

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_mediator,node_scan,node_handlers,node_resolver,node_pipeline toneBlue
class node_markers,node_kinds,node_cqrs,node_streaming,node_publishing toneAmber
class node_dishka,node_fastapi,node_otel,node_framework toneMint
class node_concurrency,node_retryable,node_errors,node_deprecation,node_builtins,node_testing toneRose
class node_app,node_di,node_telemetry toneIndigo
```

## Components

### Dispatch Runtime

- [Mediator](https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_mediator.py): `src/mediary/_mediator.py`
- [Package Scan](https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_scan.py): `src/mediary/_scan.py`
- [Handler Binding](https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_handlers.py): `src/mediary/_handlers.py`
- [Dependency Resolver](https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_resolving.py): `src/mediary/_resolving.py`
- [Behavior Pipeline](https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_behaviors.py): `src/mediary/_behaviors.py`

### Message Capabilities

- [Message Markers](https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_markers.py): `src/mediary/_markers.py`
- [Message Kinds](https://github.com/codeonym-oss/mediary/blob/main/src/mediary/kinds.py): `src/mediary/kinds.py`
- [CQRS Types](https://github.com/codeonym-oss/mediary/blob/main/src/mediary/cqrs.py): `src/mediary/cqrs.py`
- [Stream Runtime](https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_streaming.py): `src/mediary/_streaming.py`
- [Notification Publishing](https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_publishing.py): `src/mediary/_publishing.py`

### Integrations

- [Dishka Adapter](https://github.com/codeonym-oss/mediary/blob/main/src/mediary/ext/dishka.py): `src/mediary/ext/dishka.py`
- [FastAPI Adapter](https://github.com/codeonym-oss/mediary/blob/main/src/mediary/ext/fastapi.py): `src/mediary/ext/fastapi.py`
- [OpenTelemetry Adapter](https://github.com/codeonym-oss/mediary/blob/main/src/mediary/ext/otel.py): `src/mediary/ext/otel.py`

### Runtime Support

- [Async Concurrency](https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_concurrency.py): `src/mediary/_concurrency.py`
- [Retry Markers](https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_retryable.py): `src/mediary/_retryable.py`
- [Runtime Errors](https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_errors.py): `src/mediary/_errors.py`
- [Deprecation Support](https://github.com/codeonym-oss/mediary/blob/main/src/mediary/_deprecation.py): `src/mediary/_deprecation.py`
- [Built-in Behaviors](https://github.com/codeonym-oss/mediary/blob/main/src/mediary/behaviors.py): `src/mediary/behaviors.py`
- [Testing Helpers](https://github.com/codeonym-oss/mediary/blob/main/src/mediary/testing.py): `src/mediary/testing.py`

### Other components

- **Application**
- **DI Container**
- **FastAPI App**
- **Telemetry Backend**

## Connections

- Application → Mediator: sends messages (evidence: `README.md`)
- Application → Package Scan: scans package (evidence: `README.md`)
- Mediator → Package Scan: scans handlers (evidence: `src/mediary/_mediator.py`)
- Mediator → Handler Binding: dispatches to (evidence: `src/mediary/_mediator.py`)
- Mediator → Behavior Pipeline: wraps dispatch (evidence: `src/mediary/_mediator.py`)
- Mediator → Notification Publishing: publishes through (evidence: `src/mediary/_mediator.py`)
- Mediator → Stream Runtime: creates streams (evidence: `src/mediary/_mediator.py`)
- Mediator → Dependency Resolver: configures (evidence: `src/mediary/_mediator.py`)
- Package Scan → Message Markers: finds marked handlers (evidence: `src/mediary/_scan.py`)
- Handler Binding → Dependency Resolver: resolves dependencies (evidence: `src/mediary/_handlers.py`)
- Handler Binding → Async Concurrency: runs sync handlers (evidence: `src/mediary/_handlers.py`)
- Handler Binding → Runtime Errors: raises binding errors (evidence: `src/mediary/_handlers.py`)
- Behavior Pipeline → Dependency Resolver: resolves behaviors (evidence: `src/mediary/_behaviors.py`)
- Behavior Pipeline → Message Markers: matches message kinds (evidence: `src/mediary/_behaviors.py`)
- Behavior Pipeline → Runtime Errors: raises behavior errors (evidence: `src/mediary/_behaviors.py`)
- Notification Publishing → Async Concurrency: runs concurrent handlers (evidence: `src/mediary/_publishing.py`)
- CQRS Types → Message Kinds: defines CQRS kinds (evidence: `src/mediary/cqrs.py`)
- CQRS Types → Handler Binding: provides handler decorators (evidence: `src/mediary/cqrs.py`)
- CQRS Types → Stream Runtime: supports stream queries (evidence: `src/mediary/cqrs.py`)
- Message Kinds → Message Markers: defines kind markers (evidence: `src/mediary/kinds.py`)
- Message Kinds → Behavior Pipeline: targets behavior kinds (evidence: `src/mediary/kinds.py`)
- Built-in Behaviors → Behavior Pipeline: implements behaviors (evidence: `src/mediary/behaviors.py`)
- Built-in Behaviors → Retry Markers: checks retry markers (evidence: `src/mediary/behaviors.py`)
- Built-in Behaviors → Async Concurrency: uses async utilities (evidence: `src/mediary/behaviors.py`)
- Testing Helpers → Mediator: extends mediator (evidence: `src/mediary/testing.py`)
- Dishka Adapter → Mediator: adapts mediator (evidence: `src/mediary/ext/dishka.py`)
- Dishka Adapter → DI Container: integrates container (evidence: `README.md`)
- FastAPI Adapter → Mediator: integrates mediator (evidence: `src/mediary/ext/fastapi.py`)
- FastAPI Adapter → FastAPI App: integrates with (evidence: `README.md`)
- OpenTelemetry Adapter → Message Kinds: uses message kinds (evidence: `src/mediary/ext/otel.py`)
- OpenTelemetry Adapter → Telemetry Backend: exports tracing (evidence: `README.md`)
- Runtime Errors → Deprecation Support: uses compatibility aliases (evidence: `src/mediary/_errors.py`)
