# leakyrus/hostedsender architecture

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

- Interactive diagram: https://gitdiagram.com/leakyrus/hostedsender
- Repository: https://github.com/leakyrus/hostedsender

## Overview

1. **Overall shape**
   - This is a multi-project .NET solution split into a shared core, concrete handler packages, Windows-specific adapters, and host executables.
   - The architecture is intentionally modular: most behavior is defined by interfaces in `Handlers.Abstractions`, while implementation lives in separate packages.

2. **Core abstraction layer**
   - `Handlers.Abstractions` defines the domain contracts and settings models used across the system.
   - It includes handler interfaces for major output domains: `Box`, `Osc`, `PatternCollections`, configuration, JSON, and pattern handling.
   - This layer is the main boundary for dependency inversion: higher-level logic depends on abstractions, not on transport or OS-specific details.

3. **Pattern execution model**
   - The `PatternHandlerSettings` folder defines the configuration objects that drive behavior, such as `DefaultPatternHandlerSetting`, `MediaPatternHandlerSetting`, `DateTimePatternHandlerSetting`, `AfkPatternHandlerSettings`, `AnimationPatternHandlerSetting`, and `ProcessExecutionTimePatternHandlerSetting`.
   - `PatternBuilder` and `IPatternBuilder`/`IPatternHandler` indicate that the app constructs runtime handlers from configuration rather than hardcoding them.
   - `Handlers.PatternHandlers` contains the concrete handler implementations that interpret those settings and produce pattern-specific results.

4. **Configuration and persistence**
   - `Handlers.Config` provides the runtime config reader and default config creation.
   - `Handlers.Abstractions.Config` and `Handlers.Abstractions.Json` define the contracts for config loading and serialization behavior.
   - `Handlers.Json` supplies the concrete JSON serializer option provider and pattern-setting type resolver, which suggests polymorphic config serialization is a key part of the system.

5. **Collection and grouping layer**
   - `PatternCollections` is a separate abstraction/implementation pair, implying the app groups patterns into collections rather than handling them one-by-one.
   - This is likely the unit the host consumes: a collection of pattern definitions is loaded, built, and executed as a cohesive set.

6. **Output/transport subsystems**
   - `Handlers.Osc` and `Handlers.Box` represent two distinct output domains.
   - OSC support is split into handler, builder, and collection types, suggesting the app can assemble and manage multiple OSC endpoints or channels.
   - Box support provides a similar abstraction for another output target or device-facing integration, likely treated as a separate transport boundary.

7. **Context providers for runtime state**
   - `Handlers.Abstractions.Media` and `Handlers.Media.Windows` provide media state access through `IMediaInfoProvider`.
   - `Handlers.Abstractions.UserInputInfo` and `Handlers.UserInputInfo.Windows` provide user-input/AFK-related state via `IUserInputProvider`.
   - These are environment-aware inputs consumed by pattern handlers, so runtime behavior depends on live system state rather than only static config.

8. **Host/runtime orchestration**
   - `Hosted.Worker` is the runtime coordinator: it contains `Runner`, `WorkerHost`, `FileWatcher`, and `Lazier`, indicating it watches for changes and drives execution lazily or incrementally.
   - This layer is the main composition root for long-running behavior and likely owns the main control loop.
   - `appsettings.json` in this project suggests it also has standard host configuration alongside the app-specific config files.

9. **Executable entry points**
   - `Hosted.Windows` is the top-level runnable app, with `Program.cs` as the entry point.
   - `Hosted.Worker.Windows` and `Handlers.UserInputInfo.Windows` / `Handlers.Media.Windows` are Windows-only implementation packages, which cleanly separate OS-dependent code from the shared core.
   - The solution is therefore not purely cross-platform; Windows-specific services are isolated behind interfaces.

10. **Dependency injection as composition mechanism**
   - Nearly every implementation project contains a `DependencyInjection.cs`, showing that startup wiring is done through DI modules rather than manual object creation.
   - This is how abstractions, handlers, providers, and transports are assembled into a working pipeline at host startup.

11. **Data flow at a high level**
   - Config is loaded and/or generated, then JSON type resolution materializes concrete pattern settings.
   - Pattern collections are converted into pattern handlers through the builder layer.
   - Pattern handlers pull live context from media and user-input providers and then emit output through OSC or Box handlers.
   - The worker host monitors for changes and re-runs the pipeline as needed.

12. **Operational/tooling boundary**
   - The repo includes a GitHub Actions workflow and publish profiles under `Hosted.Windows`, indicating it is built and packaged as a distributable Windows application.
   - The solution file ties all packages together, but the important architecture boundary remains: shared contracts + modular implementations + hosted runtime.

Main entry points: [`Hosted.Worker/Hosted.Worker.csproj`](https://github.com/leakyrus/hostedsender/blob/master/Hosted.Worker/Hosted.Worker.csproj) (Worker), [`Handlers/Handlers.csproj`](https://github.com/leakyrus/hostedsender/blob/master/Handlers/Handlers.csproj) (Patterns), [`Handlers.Abstractions/Handlers.Abstractions.csproj`](https://github.com/leakyrus/hostedsender/blob/master/Handlers.Abstractions/Handlers.Abstractions.csproj) (Handlers.Abstractions), [`Handlers/PatternHandlers/PatternHandler.cs`](https://github.com/leakyrus/hostedsender/blob/master/Handlers/PatternHandlers/PatternHandler.cs) (Pattern handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_contracts["Contracts"]
  node_abstractions["Handlers.Abstractions<br/>contracts"]
  node_abstractions_media["Media contracts"]
  node_abstractions_input["Input contracts"]
end

subgraph group_implementations["Implementations"]
  node_config_pkg["Config"]
  node_json_pkg["JSON"]
  node_patterns_pkg["Patterns<br/>[Handlers.csproj]"]
  node_pattern_builder["PatternBuilder<br/>[PatternBuilder.cs]"]
  node_pattern_handlers["Pattern handlers<br/>[PatternHandler.cs]"]
  node_box_pkg["Box"]
  node_osc_pkg["OSC"]
  node_pattern_collections_pkg["Collections"]
end

subgraph group_runtime["Runtime"]
  node_worker["Worker<br/>runtime"]
  node_host_app["Hosted.Windows"]
end

subgraph group_windows["Windows"]
  node_media_windows["Media provider<br/>windows-adapter"]
  node_input_windows["Input provider<br/>windows-adapter"]
  node_worker_windows["Worker.Windows<br/>windows-host"]
end

node_config_pkg -->|"implements config"| node_abstractions
node_json_pkg -->|"implements json"| node_abstractions
node_pattern_collections_pkg -->|"implements collections"| node_abstractions
node_box_pkg -->|"implements box"| node_abstractions
node_osc_pkg -->|"implements osc"| node_abstractions
node_patterns_pkg -->|"implements patterns"| node_abstractions
node_patterns_pkg -->|"contains"| node_pattern_builder
node_pattern_builder -->|"creates"| node_pattern_handlers
node_pattern_handlers -->|"reads media"| node_abstractions_media
node_pattern_handlers -->|"reads input"| node_abstractions_input
node_media_windows -->|"implements media"| node_abstractions_media
node_input_windows -->|"implements input"| node_abstractions_input
node_worker -->|"loads config"| node_config_pkg
node_worker -->|"runs collections"| node_pattern_collections_pkg
node_worker -->|"executes patterns"| node_patterns_pkg
node_worker -->|"routes output"| node_box_pkg
node_worker -->|"routes output"| node_osc_pkg
node_worker_windows -->|"wires"| node_worker
node_host_app -->|"starts"| node_worker_windows
node_host_app -->|"hosts"| node_worker
node_patterns_pkg -->|"uses provider"| node_media_windows
node_patterns_pkg -->|"uses provider"| node_input_windows
node_json_pkg -->|"serializes settings"| node_patterns_pkg

click node_abstractions "https://github.com/leakyrus/hostedsender/blob/master/Handlers.Abstractions/Handlers.Abstractions.csproj"
click node_abstractions_media "https://github.com/leakyrus/hostedsender/blob/master/Handlers.Abstractions.Media/Handlers.Abstractions.Media.csproj"
click node_abstractions_input "https://github.com/leakyrus/hostedsender/blob/master/Handlers.Abstractions.UserInputInfo/Handlers.Abstractions.UserInputInfo.csproj"
click node_config_pkg "https://github.com/leakyrus/hostedsender/blob/master/Handlers.Config/Handlers.Config.csproj"
click node_json_pkg "https://github.com/leakyrus/hostedsender/blob/master/Handlers.Json/Handlers.Json.csproj"
click node_patterns_pkg "https://github.com/leakyrus/hostedsender/blob/master/Handlers/Handlers.csproj"
click node_pattern_builder "https://github.com/leakyrus/hostedsender/blob/master/Handlers/PatternHandlers/PatternBuilder.cs"
click node_pattern_handlers "https://github.com/leakyrus/hostedsender/blob/master/Handlers/PatternHandlers/PatternHandler.cs"
click node_box_pkg "https://github.com/leakyrus/hostedsender/blob/master/Handlers.Box/Handlers.Box.csproj"
click node_osc_pkg "https://github.com/leakyrus/hostedsender/blob/master/Handlers.Osc/Handlers.Osc.csproj"
click node_pattern_collections_pkg "https://github.com/leakyrus/hostedsender/blob/master/Handlers.PatternCollections/Handlers.PatternCollections.csproj"
click node_media_windows "https://github.com/leakyrus/hostedsender/blob/master/Handlers.Media.Windows/Handlers.Media.Windows.csproj"
click node_input_windows "https://github.com/leakyrus/hostedsender/blob/master/Handlers.UserInputInfo.Windows/Handlers.UserInputInfo.Windows.csproj"
click node_worker "https://github.com/leakyrus/hostedsender/blob/master/Hosted.Worker/Hosted.Worker.csproj"
click node_worker_windows "https://github.com/leakyrus/hostedsender/blob/master/Hosted.Worker.Windows/Hosted.Worker.Windows.csproj"
click node_host_app "https://github.com/leakyrus/hostedsender/blob/master/Hosted.Windows/Hosted.Windows.csproj"

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_abstractions,node_abstractions_media,node_abstractions_input toneBlue
class node_config_pkg,node_json_pkg,node_patterns_pkg,node_pattern_builder,node_pattern_handlers,node_box_pkg,node_osc_pkg,node_pattern_collections_pkg toneAmber
class node_worker,node_host_app toneMint
class node_media_windows,node_input_windows,node_worker_windows toneRose
```

## Components

### Contracts

Shared abstractions and settings models

- [Handlers.Abstractions](https://github.com/leakyrus/hostedsender/blob/master/Handlers.Abstractions/Handlers.Abstractions.csproj): contracts · Core interfaces, settings, and domain contracts · `Handlers.Abstractions/Handlers.Abstractions.csproj`
- [Media contracts](https://github.com/leakyrus/hostedsender/blob/master/Handlers.Abstractions.Media/Handlers.Abstractions.Media.csproj): contracts · Media state abstraction layer · `Handlers.Abstractions.Media/Handlers.Abstractions.Media.csproj`
- [Input contracts](https://github.com/leakyrus/hostedsender/blob/master/Handlers.Abstractions.UserInputInfo/Handlers.Abstractions.UserInputInfo.csproj): contracts · User-input and AFK abstraction layer · `Handlers.Abstractions.UserInputInfo/Handlers.Abstractions.UserInputInfo.csproj`

### Implementations

Concrete handler, config, and JSON packages

- [Config](https://github.com/leakyrus/hostedsender/blob/master/Handlers.Config/Handlers.Config.csproj): package · Config reader and default config creation · `Handlers.Config/Handlers.Config.csproj`
- [JSON](https://github.com/leakyrus/hostedsender/blob/master/Handlers.Json/Handlers.Json.csproj): package · Polymorphic serialization support · `Handlers.Json/Handlers.Json.csproj`
- [Patterns](https://github.com/leakyrus/hostedsender/blob/master/Handlers/Handlers.csproj): package · Concrete pattern handler implementations · `Handlers/Handlers.csproj`
- [PatternBuilder](https://github.com/leakyrus/hostedsender/blob/master/Handlers/PatternHandlers/PatternBuilder.cs): builder · Builds handlers from pattern settings · `Handlers/PatternHandlers/PatternBuilder.cs`
- [Pattern handlers](https://github.com/leakyrus/hostedsender/blob/master/Handlers/PatternHandlers/PatternHandler.cs): handlers · Default, media, datetime, AFK, animation, and timing handlers · `Handlers/PatternHandlers/PatternHandler.cs`
- [Box](https://github.com/leakyrus/hostedsender/blob/master/Handlers.Box/Handlers.Box.csproj): package · Box output handler implementation · `Handlers.Box/Handlers.Box.csproj`
- [OSC](https://github.com/leakyrus/hostedsender/blob/master/Handlers.Osc/Handlers.Osc.csproj): package · OSC handler, builder, and collection implementation · `Handlers.Osc/Handlers.Osc.csproj`
- [Collections](https://github.com/leakyrus/hostedsender/blob/master/Handlers.PatternCollections/Handlers.PatternCollections.csproj): package · Pattern collection handling layer · `Handlers.PatternCollections/Handlers.PatternCollections.csproj`

### Runtime

Worker and executable hosts

- [Worker](https://github.com/leakyrus/hostedsender/blob/master/Hosted.Worker/Hosted.Worker.csproj): runtime · File watcher, runner, lazy reload, host loop · `Hosted.Worker/Hosted.Worker.csproj`
- [Hosted.Windows](https://github.com/leakyrus/hostedsender/blob/master/Hosted.Windows/Hosted.Windows.csproj): app · Top-level executable entry point · `Hosted.Windows/Hosted.Windows.csproj`

### Windows

Windows-specific providers and host wiring

- [Media provider](https://github.com/leakyrus/hostedsender/blob/master/Handlers.Media.Windows/Handlers.Media.Windows.csproj): windows-adapter · Windows media info provider · `Handlers.Media.Windows/Handlers.Media.Windows.csproj`
- [Input provider](https://github.com/leakyrus/hostedsender/blob/master/Handlers.UserInputInfo.Windows/Handlers.UserInputInfo.Windows.csproj): windows-adapter · Windows user-input provider · `Handlers.UserInputInfo.Windows/Handlers.UserInputInfo.Windows.csproj`
- [Worker.Windows](https://github.com/leakyrus/hostedsender/blob/master/Hosted.Worker.Windows/Hosted.Worker.Windows.csproj): windows-host · Windows-specific worker wiring · `Hosted.Worker.Windows/Hosted.Worker.Windows.csproj`

## Connections

- Config → Handlers.Abstractions: implements config · Provides concrete config reader and default config creator
- JSON → Handlers.Abstractions: implements json · Provides serializer options and type resolution
- Collections → Handlers.Abstractions: implements collections · Implements collection contracts for patterns
- Box → Handlers.Abstractions: implements box · Implements box handler contracts
- OSC → Handlers.Abstractions: implements osc · Implements OSC handler contracts
- Patterns → Handlers.Abstractions: implements patterns · Implements pattern handler contracts
- Patterns → PatternBuilder: contains · Hosts the builder that materializes handlers
- PatternBuilder → Pattern handlers: creates · Builds concrete handlers from settings
- Pattern handlers → Media contracts: reads media · Consumes live media state through abstraction
- Pattern handlers → Input contracts: reads input · Consumes user-input/AFK state through abstraction
- Media provider → Media contracts: implements media · Windows media provider implementation
- Input provider → Input contracts: implements input · Windows user-input provider implementation
- Worker → Config: loads config · Reads runtime configuration and watches for changes
- Worker → Collections: runs collections · Coordinates loaded pattern collections
- Worker → Patterns: executes patterns · Drives pattern execution pipeline
- Worker → Box: routes output · Sends results to box transport
- Worker → OSC: routes output · Sends results to OSC transport
- Worker.Windows → Worker: wires · Windows-specific startup composition
- Hosted.Windows → Worker.Windows: starts · Executable entry point bootstraps worker host
- Hosted.Windows → Worker: hosts · Runs the long-lived worker pipeline
- Patterns → Media provider: uses provider · Pattern logic depends on live media data at runtime
- Patterns → Input provider: uses provider · Pattern logic depends on live input state at runtime
- JSON → Patterns: serializes settings · Supports polymorphic pattern setting materialization