# dshbox/cordis-rs architecture

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

- Interactive diagram: https://gitdiagram.com/dshbox/cordis-rs
- Repository: https://github.com/dshbox/cordis-rs

## Overview

Cordis is a typed runtime for long-lived, plugin-oriented Rust applications. An application prepares plugin configuration into typed input, admits a prepared plugin through a Context, and receives a FiberHandle for lifecycle control and disposal. Active plugins can register generation-owned resources, publish or require exact-realm Services, and communicate through explicitly routed typed Events. The optional Loader plans and resolves declarative plugin sources before lifecycle admission; cordis-timer adds generation-bound time operations. The graph follows the README and sampled source; unsampled subsystem wiring is shown only where documented.

Main entry points: [`crates/cordis-core/src/context.rs`](https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/context.rs) (Context), [`crates/cordis-core/src/fiber/mod.rs`](https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/fiber/mod.rs) (Fiber lifecycle), [`crates/cordis-core/src/events/dispatch.rs`](https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/events/dispatch.rs) (Event dispatch), [`crates/cordis-loader/src/lib.rs`](https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-loader/src/lib.rs) (Loader API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Application API"]
  node_facade["Cordis facade<br/>[lib.rs]"]
end

subgraph group_runtime["Lifecycle runtime"]
  node_context["Context<br/>[context.rs]"]
  node_plugin["Plugin contract<br/>[plugin.rs]"]
  node_fiber["Fiber lifecycle<br/>[mod.rs]"]
  node_convergence["Settle protocol<br/>[inertia.rs]"]
  node_registry["Fiber registry<br/>[registry.rs]"]
end

subgraph group_capabilities["Runtime capabilities"]
  node_services["Service slots<br/>[service.rs]"]
  node_events["Event dispatch<br/>[dispatch.rs]"]
  node_listeners["Listener roles<br/>[listener.rs]"]
  node_effects["Effects cleanup<br/>[effect.rs]"]
  node_observations["Runtime observations<br/>[observation.rs]"]
  node_logger["Logging<br/>[logger.rs]"]
end

subgraph group_extensions["Optional extensions"]
  node_loader["Loader API<br/>[lib.rs]"]
  node_plan["Load plan<br/>[plan.rs]"]
  node_resolver["Plugin resolver<br/>[resolver.rs]"]
  node_handoff["Load handoff<br/>[handoff.rs]"]
  node_timer["Timer operations<br/>[shapes.rs]"]
end

node_application(("Application"))
node_tokio(("Tokio runtime"))

node_application -->|"uses API"| node_facade
node_facade -->|"re-exports"| node_context
node_application -->|"defines plugin"| node_plugin
node_plugin -->|"prepares input"| node_context
node_application -->|"spawns prepared"| node_context
node_context -->|"admits plugin"| node_fiber
node_fiber -->|"settles toward target"| node_convergence
node_convergence -->|"checks dependencies"| node_services
node_fiber -->|"tracks lifecycle"| node_registry
node_context -->|"publishes or looks up"| node_services
node_context -->|"registers and dispatches"| node_events
node_events -->|"invokes roles"| node_listeners
node_fiber -->|"cleans generation"| node_effects
node_services -->|"publishes visibility"| node_observations
node_events -->|"publishes dispatch"| node_observations
node_context -->|"subscribes"| node_observations
node_context -->|"configures logging"| node_logger
node_application -->|"configures loading"| node_loader
node_loader -->|"builds plan"| node_plan
node_loader -->|"resolves entries"| node_resolver
node_resolver -->|"provides prepared plugin"| node_handoff
node_handoff -->|"admits plugin"| node_context
node_context -.->|"registers timer work"| node_timer
node_timer -.->|"schedules deadlines"| node_tokio
node_timer -->|"registers cleanup"| node_effects

click node_facade "https://github.com/dshbox/cordis-rs/blob/main/crates/cordis/src/lib.rs"
click node_context "https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/context.rs"
click node_plugin "https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/plugin.rs"
click node_fiber "https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/fiber/mod.rs"
click node_convergence "https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/fiber/inertia.rs"
click node_registry "https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/registry.rs"
click node_services "https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/service.rs"
click node_events "https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/events/dispatch.rs"
click node_listeners "https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/events/listener.rs"
click node_effects "https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/effect.rs"
click node_observations "https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/observation.rs"
click node_logger "https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/logger.rs"
click node_loader "https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-loader/src/lib.rs"
click node_plan "https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-loader/src/plan.rs"
click node_resolver "https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-loader/src/resolver.rs"
click node_handoff "https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-loader/src/handoff.rs"
click node_timer "https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-timer/src/shapes.rs"

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_facade toneBlue
class node_context,node_plugin,node_fiber,node_convergence,node_registry toneAmber
class node_services,node_events,node_listeners,node_effects,node_observations,node_logger toneMint
class node_loader,node_plan,node_resolver,node_handoff,node_timer toneRose
class node_application,node_tokio toneIndigo
```

## Components

### Application API

- [Cordis facade](https://github.com/dshbox/cordis-rs/blob/main/crates/cordis/src/lib.rs): `crates/cordis/src/lib.rs`

### Lifecycle runtime

- [Context](https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/context.rs): `crates/cordis-core/src/context.rs`
- [Plugin contract](https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/plugin.rs): `crates/cordis-core/src/plugin.rs`
- [Fiber lifecycle](https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/fiber/mod.rs): `crates/cordis-core/src/fiber/mod.rs`
- [Settle protocol](https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/fiber/inertia.rs): `crates/cordis-core/src/fiber/inertia.rs`
- [Fiber registry](https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/registry.rs): `crates/cordis-core/src/registry.rs`

### Runtime capabilities

- [Service slots](https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/service.rs): `crates/cordis-core/src/service.rs`
- [Event dispatch](https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/events/dispatch.rs): `crates/cordis-core/src/events/dispatch.rs`
- [Listener roles](https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/events/listener.rs): `crates/cordis-core/src/events/listener.rs`
- [Effects cleanup](https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/effect.rs): `crates/cordis-core/src/effect.rs`
- [Runtime observations](https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/observation.rs): `crates/cordis-core/src/observation.rs`
- [Logging](https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-core/src/logger.rs): `crates/cordis-core/src/logger.rs`

### Optional extensions

- [Loader API](https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-loader/src/lib.rs): `crates/cordis-loader/src/lib.rs`
- [Load plan](https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-loader/src/plan.rs): `crates/cordis-loader/src/plan.rs`
- [Plugin resolver](https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-loader/src/resolver.rs): `crates/cordis-loader/src/resolver.rs`
- [Load handoff](https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-loader/src/handoff.rs): `crates/cordis-loader/src/handoff.rs`
- [Timer operations](https://github.com/dshbox/cordis-rs/blob/main/crates/cordis-timer/src/shapes.rs): `crates/cordis-timer/src/shapes.rs`

### Other components

- **Application**
- **Tokio runtime**

## Connections

- Application → Cordis facade: uses API
- Cordis facade → Context: re-exports
- Application → Plugin contract: defines plugin
- Plugin contract → Context: prepares input
- Application → Context: spawns prepared
- Context → Fiber lifecycle: admits plugin
- Fiber lifecycle → Settle protocol: settles toward target
- Settle protocol → Service slots: checks dependencies
- Fiber lifecycle → Fiber registry: tracks lifecycle
- Context → Service slots: publishes or looks up
- Context → Event dispatch: registers and dispatches
- Event dispatch → Listener roles: invokes roles
- Fiber lifecycle → Effects cleanup: cleans generation
- Service slots → Runtime observations: publishes visibility
- Event dispatch → Runtime observations: publishes dispatch
- Context → Runtime observations: subscribes
- Context → Logging: configures logging
- Application → Loader API: configures loading
- Loader API → Load plan: builds plan
- Loader API → Plugin resolver: resolves entries
- Plugin resolver → Load handoff: provides prepared plugin
- Load handoff → Context: admits plugin
- Context → Timer operations: registers timer work
- Timer operations → Tokio runtime: schedules deadlines
- Timer operations → Effects cleanup: registers cleanup