# loft-games/service-daemon-rs architecture

> Architecture diagram of the GitHub repository loft-games/service-daemon-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/loft-games/service-daemon-rs
- Repository: https://github.com/loft-games/service-daemon-rs

## Overview

Service Daemon is a Tokio framework for declaring and supervising long-running services, injecting typed providers, and dispatching event-driven triggers. The principal workflow is: application declarations are expanded into link-time registries, the daemon resolves providers and prepares runtimes, then starts services under scheduling and restart policies; trigger handlers run through a separate dispatch lifecycle. Supporting branches cover managed state and recovery, logging, diagnostics/topology export, and simulation. The tree and README establish these capabilities; sampled source confirms startup orchestration and logging behavior, while some subsystem wiring is documented rather than directly sampled.

Main entry points: [`service-daemon/src/core/service_daemon/startup_pipeline.rs`](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/service_daemon/startup_pipeline.rs) (Startup Pipeline), [`service-daemon/src/core/service_daemon/runner/mod.rs`](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/service_daemon/runner/mod.rs) (Service Runner), [`service-daemon/src/models/service.rs`](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/models/service.rs) (Link-Time Registries), [`service-daemon/src/core/logging/services.rs`](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/logging/services.rs) (Logging Services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_declarations["Declarations"]
  node_service_macro["Service Macro<br/>[mod.rs]"]
  node_provider_macro["Provider Macro<br/>[mod.rs]"]
  node_trigger_macro["Trigger Macro<br/>[mod.rs]"]
  node_registry[("Link-Time Registries<br/>[service.rs]")]
end

subgraph group_lifecycle["Daemon Lifecycle"]
  node_daemon["Daemon Builder And API<br/>[builder.rs]"]
  node_startup["Startup Pipeline"]
  node_preflight["Startup Preflight"]
  node_provider_graph["Provider Resolution<br/>[provider_graph.rs]"]
  node_provider_init["Provider Initialization<br/>[provider_init.rs]"]
  node_service_runner["Service Runner<br/>[mod.rs]"]
  node_supervisor["Restart Supervisor<br/>[supervisor.rs]"]
  node_wave_runner["Priority Waves<br/>[wave.rs]"]
  node_scheduling["Adaptive Scheduling"]
end

subgraph group_events["Triggers And State"]
  node_trigger_runner["Trigger Runner<br/>[mod.rs]"]
  node_trigger_dispatch["Trigger Dispatch<br/>[dispatch.rs]"]
  node_managed_state["Managed State<br/>[managed_state.rs]"]
  node_context["Service Context<br/>[mod.rs]"]
end

subgraph group_operations["Operations"]
  node_logging["Logging Services<br/>[services.rs]"]
  node_log_queue["Log Event Queue<br/>[model.rs]"]
  node_diagnostics[("Diagnostics Store<br/>[diagnostics.rs]")]
  node_topology["Topology Export"]
  node_simulation["Mock Simulation<br/>[simulation.rs]"]
end

node_application(("Tokio Application"))
node_stderr(("Standard Error"))

node_application -->|"declares services"| node_service_macro
node_application -->|"declares providers"| node_provider_macro
node_application -->|"declares triggers"| node_trigger_macro
node_service_macro -->|"generates entries"| node_registry
node_provider_macro -->|"generates entries"| node_registry
node_trigger_macro -->|"generates entries"| node_registry
node_application -->|"builds and runs"| node_daemon
node_daemon -->|"starts lifecycle"| node_startup
node_startup -->|"runs checks"| node_preflight
node_preflight -->|"prepares graph"| node_provider_graph
node_provider_graph -->|"initializes providers"| node_provider_init
node_startup -->|"spawns services"| node_service_runner
node_service_runner -->|"supervises generations"| node_supervisor
node_service_runner -->|"orders startup"| node_wave_runner
node_service_runner -->|"selects runtime lanes"| node_scheduling
node_trigger_runner -->|"dispatches payloads"| node_trigger_dispatch
node_context -->|"accesses state"| node_managed_state
node_logging -->|"consumes events"| node_log_queue
node_logging -->|"writes console output"| node_stderr
node_startup -.->|"records runtime observations"| node_diagnostics
node_startup -.->|"starts collector"| node_topology
node_application -.->|"simulates async behavior"| node_simulation

click node_service_macro "https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon-macro/src/service/mod.rs"
click node_provider_macro "https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon-macro/src/provider/mod.rs"
click node_trigger_macro "https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon-macro/src/trigger/mod.rs"
click node_registry "https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/models/service.rs"
click node_daemon "https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/service_daemon/builder.rs"
click node_startup "https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/service_daemon/startup_pipeline.rs"
click node_preflight "https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/service_daemon/startup_preflight.rs"
click node_provider_graph "https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/service_daemon/provider_graph.rs"
click node_provider_init "https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/provider_init.rs"
click node_service_runner "https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/service_daemon/runner/mod.rs"
click node_supervisor "https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/service_daemon/runner/supervisor.rs"
click node_wave_runner "https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/service_daemon/runner/wave.rs"
click node_scheduling "https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/adaptive_scheduling.rs"
click node_trigger_runner "https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/trigger_runner/mod.rs"
click node_trigger_dispatch "https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/trigger_runner/dispatch.rs"
click node_managed_state "https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/managed_state.rs"
click node_context "https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/context/mod.rs"
click node_logging "https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/logging/services.rs"
click node_log_queue "https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/logging/model.rs"
click node_diagnostics "https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/diagnostics.rs"
click node_topology "https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/topology_collector.rs"
click node_simulation "https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/context/simulation.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_service_macro,node_provider_macro,node_trigger_macro,node_registry toneBlue
class node_daemon,node_startup,node_preflight,node_provider_graph,node_provider_init,node_service_runner,node_supervisor,node_wave_runner,node_scheduling toneAmber
class node_trigger_runner,node_trigger_dispatch,node_managed_state,node_context toneMint
class node_logging,node_log_queue,node_diagnostics,node_topology,node_simulation toneRose
class node_application,node_stderr toneIndigo
```

## Components

### Declarations

- [Service Macro](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon-macro/src/service/mod.rs): `service-daemon-macro/src/service/mod.rs`
- [Provider Macro](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon-macro/src/provider/mod.rs): `service-daemon-macro/src/provider/mod.rs`
- [Trigger Macro](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon-macro/src/trigger/mod.rs): `service-daemon-macro/src/trigger/mod.rs`
- [Link-Time Registries](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/models/service.rs): `service-daemon/src/models/service.rs`

### Daemon Lifecycle

- [Daemon Builder And API](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/service_daemon/builder.rs): `service-daemon/src/core/service_daemon/builder.rs`
- [Startup Pipeline](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/service_daemon/startup_pipeline.rs): `service-daemon/src/core/service_daemon/startup_pipeline.rs`
- [Startup Preflight](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/service_daemon/startup_preflight.rs): `service-daemon/src/core/service_daemon/startup_preflight.rs`
- [Provider Resolution](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/service_daemon/provider_graph.rs): `service-daemon/src/core/service_daemon/provider_graph.rs`
- [Provider Initialization](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/provider_init.rs): `service-daemon/src/core/provider_init.rs`
- [Service Runner](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/service_daemon/runner/mod.rs): `service-daemon/src/core/service_daemon/runner/mod.rs`
- [Restart Supervisor](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/service_daemon/runner/supervisor.rs): `service-daemon/src/core/service_daemon/runner/supervisor.rs`
- [Priority Waves](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/service_daemon/runner/wave.rs): `service-daemon/src/core/service_daemon/runner/wave.rs`
- [Adaptive Scheduling](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/adaptive_scheduling.rs): `service-daemon/src/core/adaptive_scheduling.rs`

### Triggers And State

- [Trigger Runner](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/trigger_runner/mod.rs): `service-daemon/src/core/trigger_runner/mod.rs`
- [Trigger Dispatch](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/trigger_runner/dispatch.rs): `service-daemon/src/core/trigger_runner/dispatch.rs`
- [Managed State](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/managed_state.rs): `service-daemon/src/core/managed_state.rs`
- [Service Context](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/context/mod.rs): `service-daemon/src/core/context/mod.rs`

### Operations

- [Logging Services](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/logging/services.rs): `service-daemon/src/core/logging/services.rs`
- [Log Event Queue](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/logging/model.rs): `service-daemon/src/core/logging/model.rs`
- [Diagnostics Store](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/diagnostics.rs): `service-daemon/src/core/diagnostics.rs`
- [Topology Export](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/topology_collector.rs): `service-daemon/src/core/topology_collector.rs`
- [Mock Simulation](https://github.com/loft-games/service-daemon-rs/blob/master/service-daemon/src/core/context/simulation.rs): `service-daemon/src/core/context/simulation.rs`

### Other components

- **Tokio Application**
- **Standard Error**

## Connections

- Tokio Application → Service Macro: declares services
- Tokio Application → Provider Macro: declares providers
- Tokio Application → Trigger Macro: declares triggers
- Service Macro → Link-Time Registries: generates entries
- Provider Macro → Link-Time Registries: generates entries
- Trigger Macro → Link-Time Registries: generates entries
- Tokio Application → Daemon Builder And API: builds and runs
- Daemon Builder And API → Startup Pipeline: starts lifecycle
- Startup Pipeline → Startup Preflight: runs checks
- Startup Preflight → Provider Resolution: prepares graph
- Provider Resolution → Provider Initialization: initializes providers
- Startup Pipeline → Service Runner: spawns services
- Service Runner → Restart Supervisor: supervises generations
- Service Runner → Priority Waves: orders startup
- Service Runner → Adaptive Scheduling: selects runtime lanes
- Trigger Runner → Trigger Dispatch: dispatches payloads
- Service Context → Managed State: accesses state
- Logging Services → Log Event Queue: consumes events
- Logging Services → Standard Error: writes console output
- Startup Pipeline → Diagnostics Store: records runtime observations
- Startup Pipeline → Topology Export: starts collector
- Tokio Application → Mock Simulation: simulates async behavior