# nagyzoltanpeter/nim-brokers architecture

> Architecture diagram of the GitHub repository nagyzoltanpeter/nim-brokers, 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/nagyzoltanpeter/nim-brokers
- Repository: https://github.com/nagyzoltanpeter/nim-brokers

## Overview

nim-brokers lets a Nim interface declaration serve as a typed contract across in-process, cross-thread, and cross-language boundaries. The principal workflow is: declare a broker/interface, register an implementation or handler, then invoke it through the selected dispatch lane; optional API generation exposes the contract to foreign-language callers, while EXTAPI lets Nim consume foreign plugins. The README documents these capabilities, but the only sampled source is the EXTAPI ABI header, so detailed internal call relationships are not asserted.

Main entry points: [`brokers/api_library.nim`](https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/api_library.nim) (API shared library), [`brokers/internal/ext_runtime.nim`](https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/internal/ext_runtime.nim) (External plugin runtime), [`brokers/broker_implement.nim`](https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/broker_implement.nim) (Broker implementation), [`brokers/internal`](https://github.com/nagyzoltanpeter/nim-brokers/tree/master/brokers/internal) (Threaded dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_contracts["Contracts and lifecycle"]
  node_interface["Broker interface"]
  node_implementation["Broker implementation"]
  node_context["Broker context<br/>[broker_context.nim]"]
  node_scope["Broker scope<br/>[broker_scope.nim]"]
end

subgraph group_brokers["Broker dispatch"]
  node_request["Request broker<br/>[request_broker.nim]"]
  node_multi_request["Multi-request broker"]
  node_event["Event broker<br/>[event_broker.nim]"]
  node_signal["Signal broker<br/>[signal_broker.nim]"]
  node_mt_dispatch["Threaded dispatch"]
end

subgraph group_interop["Foreign-language interop"]
  node_api_library["API shared library<br/>[api_library.nim]"]
  node_api_schema["API schema and codecs"]
  node_api_codegen["Wrapper generation"]
  node_extapi["External plugin runtime<br/>[ext_runtime.nim]"]
  node_ext_brokers["EXTAPI broker integration<br/>[ext_brokers.nim]"]
  node_ext_plugin["Plugin interface<br/>[ext_plugin.nim]"]
end

subgraph group_internals["Dispatch internals"]
  node_cbor["CBOR transport"]
  node_queues["Thread queues and transport"]
end

node_nim_user(("Nim consumer"))
node_foreign_callers(("Foreign-language callers"))
node_plugin(("Foreign plugin"))

node_nim_user -->|"declares contract"| node_interface
node_nim_user -->|"implements contract"| node_implementation
node_implementation -->|"registers provider"| node_request
node_nim_user -->|"sends request"| node_request
node_nim_user -->|"fans out requests"| node_multi_request
node_nim_user -->|"emits or listens"| node_event
node_nim_user -->|"sends signal"| node_signal
node_nim_user -->|"isolates brokers"| node_context
node_nim_user -->|"scopes registrations"| node_scope
node_nim_user -->|"selects thread lane"| node_mt_dispatch
node_mt_dispatch -->|"uses ring and slab"| node_queues
node_nim_user -->|"selects API lane"| node_api_library
node_api_library -->|"uses CBOR ABI"| node_api_schema
node_api_library -->|"generates wrappers"| node_api_codegen
node_api_codegen -->|"exposes typed API"| node_foreign_callers
node_nim_user -->|"declares EXTAPI"| node_ext_brokers
node_ext_brokers -.->|"uses plugin runtime"| node_extapi
node_extapi -->|"tunnels plugin calls"| node_plugin
node_extapi -->|"transfers CBOR"| node_cbor
node_ext_plugin -->|"implements plugin ABI"| node_plugin

click node_interface "https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/broker_interface.nim"
click node_implementation "https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/broker_implement.nim"
click node_context "https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/broker_context.nim"
click node_scope "https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/broker_scope.nim"
click node_request "https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/request_broker.nim"
click node_multi_request "https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/multi_request_broker.nim"
click node_event "https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/event_broker.nim"
click node_signal "https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/signal_broker.nim"
click node_mt_dispatch "https://github.com/nagyzoltanpeter/nim-brokers/tree/master/brokers/internal"
click node_api_library "https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/api_library.nim"
click node_api_schema "https://github.com/nagyzoltanpeter/nim-brokers/tree/master/brokers/internal"
click node_api_codegen "https://github.com/nagyzoltanpeter/nim-brokers/tree/master/brokers/internal"
click node_extapi "https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/internal/ext_runtime.nim"
click node_ext_brokers "https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/internal/ext_brokers.nim"
click node_ext_plugin "https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/ext_plugin.nim"
click node_cbor "https://github.com/nagyzoltanpeter/nim-brokers/tree/master/brokers/internal"
click node_queues "https://github.com/nagyzoltanpeter/nim-brokers/tree/master/brokers/internal"

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_interface,node_implementation,node_context,node_scope toneBlue
class node_request,node_multi_request,node_event,node_signal,node_mt_dispatch toneAmber
class node_api_library,node_api_schema,node_api_codegen,node_extapi,node_ext_brokers,node_ext_plugin toneMint
class node_cbor,node_queues toneRose
class node_nim_user,node_foreign_callers,node_plugin toneIndigo
```

## Components

### Contracts and lifecycle

- [Broker interface](https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/broker_interface.nim): `brokers/broker_interface.nim`
- [Broker implementation](https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/broker_implement.nim): `brokers/broker_implement.nim`
- [Broker context](https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/broker_context.nim): `brokers/broker_context.nim`
- [Broker scope](https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/broker_scope.nim): `brokers/broker_scope.nim`

### Broker dispatch

- [Request broker](https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/request_broker.nim): `brokers/request_broker.nim`
- [Multi-request broker](https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/multi_request_broker.nim): `brokers/multi_request_broker.nim`
- [Event broker](https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/event_broker.nim): `brokers/event_broker.nim`
- [Signal broker](https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/signal_broker.nim): `brokers/signal_broker.nim`
- [Threaded dispatch](https://github.com/nagyzoltanpeter/nim-brokers/tree/master/brokers/internal): `brokers/internal`

### Foreign-language interop

- [API shared library](https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/api_library.nim): `brokers/api_library.nim`
- [API schema and codecs](https://github.com/nagyzoltanpeter/nim-brokers/tree/master/brokers/internal): `brokers/internal`
- [Wrapper generation](https://github.com/nagyzoltanpeter/nim-brokers/tree/master/brokers/internal): `brokers/internal`
- [External plugin runtime](https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/internal/ext_runtime.nim): `brokers/internal/ext_runtime.nim`
- [EXTAPI broker integration](https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/internal/ext_brokers.nim): `brokers/internal/ext_brokers.nim`
- [Plugin interface](https://github.com/nagyzoltanpeter/nim-brokers/blob/master/brokers/ext_plugin.nim): `brokers/ext_plugin.nim`

### Dispatch internals

- [CBOR transport](https://github.com/nagyzoltanpeter/nim-brokers/tree/master/brokers/internal): `brokers/internal`
- [Thread queues and transport](https://github.com/nagyzoltanpeter/nim-brokers/tree/master/brokers/internal): `brokers/internal`

### Other components

- **Nim consumer**
- **Foreign-language callers**
- **Foreign plugin**

## Connections

- Nim consumer → Broker interface: declares contract (evidence: `README.md`)
- Nim consumer → Broker implementation: implements contract (evidence: `README.md`)
- Broker implementation → Request broker: registers provider (evidence: `README.md`)
- Nim consumer → Request broker: sends request (evidence: `README.md`)
- Nim consumer → Multi-request broker: fans out requests (evidence: `README.md`)
- Nim consumer → Event broker: emits or listens (evidence: `README.md`)
- Nim consumer → Signal broker: sends signal (evidence: `README.md`)
- Nim consumer → Broker context: isolates brokers (evidence: `README.md`)
- Nim consumer → Broker scope: scopes registrations (evidence: `README.md`)
- Nim consumer → Threaded dispatch: selects thread lane (evidence: `README.md`)
- Threaded dispatch → Thread queues and transport: uses ring and slab (evidence: `README.md`)
- Nim consumer → API shared library: selects API lane (evidence: `README.md`)
- API shared library → API schema and codecs: uses CBOR ABI (evidence: `README.md`)
- API shared library → Wrapper generation: generates wrappers (evidence: `README.md`)
- Wrapper generation → Foreign-language callers: exposes typed API (evidence: `README.md`)
- Nim consumer → EXTAPI broker integration: declares EXTAPI (evidence: `README.md`)
- EXTAPI broker integration → External plugin runtime: uses plugin runtime
- External plugin runtime → Foreign plugin: tunnels plugin calls
- External plugin runtime → CBOR transport: transfers CBOR
- Plugin interface → Foreign plugin: implements plugin ABI
