# tr3kkr/yuzu architecture

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

- Interactive diagram: https://gitdiagram.com/tr3kkr/yuzu
- Repository: https://github.com/tr3kkr/yuzu

## Overview

1. **This repo is a full endpoint-management control plane, not a single app.**  
   The main runtime pieces are `agents/core` (endpoint daemon), `server/core` (central management server), `gateway/` (optional Erlang/OTP relay), and `sdk/` (stable plugin ABI). The repo also carries the protocol definitions, packaged instruction content, deploy artifacts, docs/site, and tests.

2. **The agent is the on-device execution and telemetry boundary.**  
   `agents/core` is a C++23 daemon that discovers identity/certificates, loads plugins, runs triggers/schedulers, and maintains local KV/state. It is the only component that directly touches the managed endpoint’s OS surfaces and hardware/network APIs.

3. **Plugins are the main extensibility mechanism on the agent.**  
   `agents/plugins/*` contains many small shared-library plugins for inventory, security, network, software, and response actions. The SDK in `sdk/` defines the ABI, so plugins can be built independently while still being loaded by the agent at runtime.

4. **The server is the orchestration and control-plane hub.**  
   `server/core` owns authentication, RBAC, session/API token handling, instruction execution, policy/compliance evaluation, device inventory, notifications, workflows, and dashboards. Its code is organized around “stores”, “routes”, “engines”, and “UI” renderers rather than a single monolith.

5. **Device communication is gRPC/protobuf over mTLS.**  
   The wire contract lives under `proto/yuzu/...` and is mirrored by generated code in `gateway/` and used by both agent and server. The core data flows are registration, heartbeats, streaming command execution, result submission, and event watching.

6. **The optional gateway is a separate Erlang/OTP tier.**  
   `gateway/` sits between agents and server in larger or distributed deployments. It handles upstream routing, buffering/aggregation of heartbeats and registrations, health/circuit behavior, and gRPC proxying using `grpcbox`.

7. **Instruction content is a first-class data model, embedded at build time.**  
   `content/definitions/*.yaml` describes instruction definitions, sets, and packs. These are validated and embedded into the server build, then imported/executed as governed, versioned operations with typed params, typed result columns, and approval semantics.

8. **Persistence is split by concern, with explicit storage layers.**  
   The server has many domain stores and a PostgreSQL substrate/migration layer (`server/core/src/pg/*`), plus embedded-store helpers where appropriate. The agent uses local persistent state for identity and coordination, while the server persists operational records such as audits, approvals, executions, inventory, policies, and response/result sets.

9. **The web UI is server-rendered and tightly coupled to backend routes.**  
   `server/core` serves HTMX-style HTML fragments, static JS/CSS bundles, and route handlers for dashboards like inventory, devices, network, DEX, TAR, workflow, and settings. This is a server-driven UI rather than a separate frontend SPA.

10. **Observability and integrations are built into the architecture.**  
   Both agent and server expose Prometheus metrics; the repo includes Grafana provisioning/dashboards and ClickHouse-oriented deployment assets. External integrations also include OIDC for auth, webhooks/event sinks, and MCP tooling for agentic access.

11. **Deployment is multi-target and operationally opinionated.**  
   The repo includes Meson/vcpkg build files, Docker images and compose stacks, systemd units, Debian/RPM/MSI/macOS packaging, and CI workflows. That means architecture diagrams should show both the runtime topology and the packaging/deployment boundary, since the same codebase produces server, agent, gateway, and demo stacks.

12. **Docs and tests are part of the architecture contract.**  
   `docs/` contains the authoritative design docs and ADRs, while `tests/` covers unit, integration, end-to-end, and UI/puppeteer flows. The repo is heavily test- and policy-driven, so behavior is expected to be validated at multiple layers, not just by manual use.

Main entry points: [`server/core`](https://github.com/tr3kkr/yuzu/tree/main/server/core) (Server core), [`agents/core`](https://github.com/tr3kkr/yuzu/tree/main/agents/core) (Agent core), [`deploy`](https://github.com/tr3kkr/yuzu/tree/main/deploy) (Deploy), [`gateway`](https://github.com/tr3kkr/yuzu/tree/main/gateway) (Gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime plane"]
  node_agent_core["Agent core<br/>endpoint daemon"]
  node_agent_plugins["Plugins<br/>agent extensions"]
  node_sdk["SDK<br/>plugin ABI"]
  node_server_core["Server core<br/>control plane"]
  node_server_ingest["Ingest<br/>device intake"]
  node_server_exec["Execution<br/>instruction engine"]
  node_server_policy["Policy & auth<br/>governance"]
  node_server_ui["Server UI<br/>server-rendered web UI"]
  node_server_storage[("Storage<br/>persistence layer")]
  node_gateway["Gateway<br/>Erlang/OTP relay"]
  node_proto["Protobuf API<br/>wire contract"]
end

subgraph group_content["Content plane"]
  node_content_defs["Instructions<br/>embedded content"]
end

subgraph group_delivery["Delivery plane"]
  node_deploy["Deploy<br/>artifacts"]
  node_observability["Observability<br/>metrics & dashboards"]
  node_docs["Docs"]
  node_tests["Tests<br/>verification suite"]
  node_site["Site"]
  node_cli_scripts["Scripts<br/>ops tooling"]
  node_ci["CI<br/>automation<br/>[workflows]"]
end

node_agent_core -->|"loads"| node_agent_plugins
node_agent_plugins -->|"implements"| node_sdk
node_agent_core -->|"speaks"| node_proto
node_gateway -->|"mirrors"| node_proto
node_server_core -->|"serves"| node_proto
node_server_core -->|"ingests"| node_server_ingest
node_server_core -->|"orchestrates"| node_server_exec
node_server_core -->|"governs"| node_server_policy
node_server_core -->|"renders"| node_server_ui
node_server_core -->|"persists"| node_server_storage
node_gateway -->|"forwards"| node_server_core
node_agent_core -->|"registers"| node_server_core
node_content_defs -->|"feeds"| node_server_exec
node_content_defs -->|"checks"| node_server_policy
node_deploy -->|"packages"| node_agent_core
node_deploy -->|"packages"| node_server_core
node_deploy -->|"packages"| node_gateway
node_observability -->|"observes"| node_server_core
node_observability -->|"observes"| node_gateway
node_docs -->|"documents"| node_server_core
node_docs -->|"documents"| node_agent_core
node_tests -->|"verifies"| node_agent_core
node_tests -->|"verifies"| node_server_core
node_tests -->|"verifies"| node_gateway
node_site -->|"publishes"| node_docs
node_cli_scripts -->|"drives"| node_deploy
node_ci -->|"runs"| node_tests
node_ci -->|"builds"| node_deploy

click node_agent_core "https://github.com/tr3kkr/yuzu/tree/main/agents/core"
click node_agent_plugins "https://github.com/tr3kkr/yuzu/tree/main/agents/plugins"
click node_sdk "https://github.com/tr3kkr/yuzu/tree/main/sdk"
click node_server_core "https://github.com/tr3kkr/yuzu/tree/main/server/core"
click node_server_ingest "https://github.com/tr3kkr/yuzu/tree/main/server/core/src"
click node_server_exec "https://github.com/tr3kkr/yuzu/tree/main/server/core/src"
click node_server_policy "https://github.com/tr3kkr/yuzu/tree/main/server/core/src"
click node_server_ui "https://github.com/tr3kkr/yuzu/tree/main/server/core/src"
click node_server_storage "https://github.com/tr3kkr/yuzu/tree/main/server/core/src/pg"
click node_gateway "https://github.com/tr3kkr/yuzu/tree/main/gateway"
click node_proto "https://github.com/tr3kkr/yuzu/tree/main/proto/yuzu"
click node_content_defs "https://github.com/tr3kkr/yuzu/tree/main/content/definitions"
click node_deploy "https://github.com/tr3kkr/yuzu/tree/main/deploy"
click node_observability "https://github.com/tr3kkr/yuzu/tree/main/deploy/grafana"
click node_docs "https://github.com/tr3kkr/yuzu/tree/main/docs"
click node_tests "https://github.com/tr3kkr/yuzu/tree/main/tests"
click node_site "https://github.com/tr3kkr/yuzu/tree/main/site"
click node_cli_scripts "https://github.com/tr3kkr/yuzu/tree/main/scripts"
click node_ci "https://github.com/tr3kkr/yuzu/blob/main/.github/workflows"

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_agent_core,node_agent_plugins,node_sdk,node_server_core,node_server_ingest,node_server_exec,node_server_policy,node_server_ui,node_server_storage,node_gateway,node_proto toneBlue
class node_content_defs toneAmber
class node_deploy,node_observability,node_docs,node_tests,node_site,node_cli_scripts,node_ci toneMint
```

## Components

### Runtime plane

Core online services and on-device execution boundary.

- [Agent core](https://github.com/tr3kkr/yuzu/tree/main/agents/core): endpoint daemon · On-device C++ runtime that owns identity, local state, plugin loading, triggers, scheduling, and endpoint telemetry. · `agents/core`
- [Plugins](https://github.com/tr3kkr/yuzu/tree/main/agents/plugins): agent extensions · Shared-library capability modules for inventory, security, network, software, response, and collection tasks. · `agents/plugins`
- [SDK](https://github.com/tr3kkr/yuzu/tree/main/sdk): plugin ABI · Stable headers and utilities that define the plugin interface and allow independent plugin builds. · `sdk`
- [Server core](https://github.com/tr3kkr/yuzu/tree/main/server/core): control plane · Central C++ service for auth, orchestration, policies, inventory, workflows, UI rendering, and data persistence. · `server/core`
- [Ingest](https://github.com/tr3kkr/yuzu/tree/main/server/core/src): device intake · Heartbeats, registrations, inventory, execution results, analytics, and event ingestion paths. · `server/core/src`
- [Execution](https://github.com/tr3kkr/yuzu/tree/main/server/core/src): instruction engine · Instruction loading, approvals, scheduling, bundle orchestration, result sets, and response execution. · `server/core/src`
- [Policy & auth](https://github.com/tr3kkr/yuzu/tree/main/server/core/src): governance · Authentication, OIDC/MFA, RBAC, compliance, preflight, and approval decisions. · `server/core/src`
- [Server UI](https://github.com/tr3kkr/yuzu/tree/main/server/core/src): server-rendered web UI · HTMX-style routes and renderers for dashboards, settings, devices, inventory, network, DEX, TAR, and workflows. · `server/core/src`
- [Storage](https://github.com/tr3kkr/yuzu/tree/main/server/core/src/pg): persistence layer · PostgreSQL-backed stores, migrations, and domain-specific state for audits, inventory, executions, policies, and tokens. · `server/core/src/pg`
- [Gateway](https://github.com/tr3kkr/yuzu/tree/main/gateway): Erlang/OTP relay · Optional distributed tier that proxies gRPC, buffers registrations and heartbeats, and manages health and upstream routing. · `gateway`
- [Protobuf API](https://github.com/tr3kkr/yuzu/tree/main/proto/yuzu): wire contract · Shared gRPC/protobuf definitions for agent, common, gateway, and server management APIs over mTLS. · `proto/yuzu`

### Content plane

Versioned instruction definitions and embedded governed operations.

- [Instructions](https://github.com/tr3kkr/yuzu/tree/main/content/definitions): embedded content · YAML instruction definitions, sets, and packs validated at build time and embedded into the server. · `content/definitions`

### Delivery plane

Build, packaging, deployment, observability, and docs.

- [Deploy](https://github.com/tr3kkr/yuzu/tree/main/deploy): artifacts · Docker, systemd, packaging, compose, and environment assets for server, agent, gateway, and demo stacks. · `deploy`
- [Observability](https://github.com/tr3kkr/yuzu/tree/main/deploy/grafana): metrics & dashboards · Prometheus, Grafana provisioning, dashboards, alerts, and telemetry-oriented deployment assets. · `deploy/grafana`
- [Docs](https://github.com/tr3kkr/yuzu/tree/main/docs): architecture docs · Authoritative design docs, ADRs, runbooks, and user manuals that define behavior and operating constraints. · `docs`
- [Tests](https://github.com/tr3kkr/yuzu/tree/main/tests): verification suite · Unit, integration, shell, and puppeteer flows covering server, agent, gateway, and UI behavior. · `tests`
- [Site](https://github.com/tr3kkr/yuzu/tree/main/site): documentation site · Astro-based docs and manual site used to publish architecture and user-facing documentation. · `site`
- [Scripts](https://github.com/tr3kkr/yuzu/tree/main/scripts): ops tooling · Build, CI, release, UAT, and maintenance scripts that bridge development and deployment workflows. · `scripts`
- [CI](https://github.com/tr3kkr/yuzu/blob/main/.github/workflows): automation · GitHub workflows and code scanning that validate builds, security, docs, and release pipelines. · `.github/workflows`

## Connections

- Agent core → Plugins: loads · The daemon discovers and loads capability plugins at runtime.
- Plugins → SDK: implements · Plugins are compiled against the stable ABI and helper headers.
- Agent core → Protobuf API: speaks · Agent uses the protobuf contract for registration, heartbeats, and execution streams.
- Gateway → Protobuf API: mirrors · Gateway vendors and proxies the same management and agent API contract.
- Server core → Protobuf API: serves · Server implements management-side gRPC and shared wire semantics.
- Server core → Ingest: ingests · Ingestion paths receive device telemetry, results, and events.
- Server core → Execution: orchestrates · Instruction execution and workflow engines coordinate governed operations.
- Server core → Policy & auth: governs · Auth, RBAC, compliance, and approvals gate actions.
- Server core → Server UI: renders · Route handlers and page renderers build the server-driven UI.
- Server core → Storage: persists · Domain stores and migrations back operational records.
- Gateway → Server core: forwards · Optional relay tier routes upstream traffic to the server.
- Agent core → Server core: registers · Agents enroll, heartbeat, and submit results to the control plane.
- Instructions → Execution: feeds · Embedded instruction packs are imported by the execution layer.
- Instructions → Policy & auth: checks · Definitions carry approval, typing, and governance semantics.
- Deploy → Agent core: packages · Build and packaging assets produce agent binaries and installers.
- Deploy → Server core: packages · Deployment assets produce server images and service packages.
- Deploy → Gateway: packages · Deployment assets build and ship the gateway tier.
- Observability → Server core: observes · Dashboards and metrics expose server health and operations.
- Observability → Gateway: observes · Gateway metrics and dashboards cover relay health and buffering.
- Docs → Server core: documents · Design docs capture architecture, auth, storage, and operations.
- Docs → Agent core: documents · Agent docs cover privilege, plugins, enrollment, and runtime behavior.
- Tests → Agent core: verifies · Unit and integration tests exercise endpoint runtime behavior.
- Tests → Server core: verifies · Tests cover routes, stores, engines, and UI rendering.
- Tests → Gateway: verifies · Gateway suites cover routing, buffering, mTLS, and proxy behavior.
- Site → Docs: publishes · The documentation site renders the repo's architectural and user docs.
- Scripts → Deploy: drives · Scripts orchestrate builds, releases, UAT, and stack bring-up.
- CI → Tests: runs · Workflows execute test suites, checks, and release gates.
- CI → Deploy: builds · CI produces artifacts and validates packaging paths.
