# kykiles/sysadmin-agents architecture

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

- Interactive diagram: https://gitdiagram.com/kykiles/sysadmin-agents
- Repository: https://github.com/kykiles/sysadmin-agents

## Overview

This is a Telegram-operated sysadmin agent: a user submits a natural-language task, the Director plans it and delegates work to temporary agents, which use dynamically loaded skills to inspect or change infrastructure; risky operations require Telegram approval. The map also preserves the documented learning and monitoring branches. Some runtime wiring and skill dispatch are unsampled, so uncertain links are dashed rather than asserted as direct calls.

Main entry points: [`app/agents/director.py`](https://github.com/kykiles/sysadmin-agents/blob/master/app/agents/director.py) (Director), [`app/bot/handlers.py`](https://github.com/kykiles/sysadmin-agents/blob/master/app/bot/handlers.py) (Telegram bot), [`skills/db/tools.py`](https://github.com/kykiles/sysadmin-agents/blob/master/skills/db/tools.py) (Skill tools), [`app/agents/base.py`](https://github.com/kykiles/sysadmin-agents/blob/master/app/agents/base.py) (Agent runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Interaction and agents"]
  node_telegram["Telegram bot<br/>[handlers.py]"]
  node_director["Director<br/>[director.py]"]
  node_agent["Agent runtime<br/>[base.py]"]
  node_messages["Task results<br/>[messages.py]"]
  node_progress["Task progress<br/>[progress.py]"]
  node_render["Response rendering<br/>[render.py]"]
end

subgraph group_execution["Skills and operations"]
  node_llm_client["LLM client<br/>[client.py]"]
  node_skill_loader["Skill loader<br/>[loader.py]"]
  node_skill_library["Skill packages"]
  node_skill_tools["Skill tools<br/>[tools.py]"]
  node_readonly["Read-only policy<br/>[readonly.py]"]
  node_docker_tools["Docker tools<br/>[docker.py]"]
  node_tool_framework["Tool framework<br/>[base.py]"]
end

subgraph group_memory["Memory and learning"]
  node_facts[("Knowledge facts<br/>[facts.py]")]
  node_journal[("Task journal<br/>[journal.py]")]
  node_consolidate["Memory consolidation<br/>[consolidate.py]"]
  node_learning["Learning review<br/>[review.py]"]
  node_history[("Dialog history<br/>[history.py]")]
end

subgraph group_monitoring["Monitoring"]
  node_monitor_loop["Health loop<br/>[loop.py]"]
  node_monitor_checks["Health checks<br/>[checks.py]"]
  node_monitor_state[("Monitor state<br/>[state.py]")]
end

subgraph group_platform["External systems"]
  node_host["Managed infrastructure"]
  node_llm_service["LLM provider"]
end

node_user(("Telegram user"))

node_user -->|"sends task"| node_telegram
node_telegram -.->|"submits task"| node_director
node_director -->|"spawns agents"| node_agent
node_director -->|"loads skills"| node_skill_loader
node_skill_loader -.->|"loads packages"| node_skill_library
node_agent -->|"requests completion"| node_llm_client
node_llm_client -->|"sends prompts"| node_llm_service
node_agent -->|"executes tools"| node_tool_framework
node_skill_tools -->|"builds tools"| node_tool_framework
node_skill_tools -->|"uses Docker API"| node_docker_tools
node_skill_tools -.->|"uses policy"| node_readonly
node_docker_tools -->|"manages containers"| node_host
node_director -->|"recalls knowledge"| node_facts
node_director -.->|"records tasks"| node_journal
node_director -.->|"uses dialog history"| node_history
node_learning -->|"reviews facts"| node_facts
node_learning -->|"requests proposals"| node_consolidate
node_consolidate -->|"reads task journal"| node_journal
node_telegram -->|"offers self-review"| node_learning
node_monitor_loop -->|"runs checks"| node_monitor_checks
node_monitor_loop -->|"uses state"| node_monitor_state
node_monitor_checks -->|"checks infrastructure"| node_host
node_director -->|"returns task result"| node_messages
node_telegram -->|"renders response"| node_render
node_messages -->|"formats result"| node_render
node_director -.->|"updates task plan"| node_progress

click node_telegram "https://github.com/kykiles/sysadmin-agents/blob/master/app/bot/handlers.py"
click node_director "https://github.com/kykiles/sysadmin-agents/blob/master/app/agents/director.py"
click node_agent "https://github.com/kykiles/sysadmin-agents/blob/master/app/agents/base.py"
click node_messages "https://github.com/kykiles/sysadmin-agents/blob/master/app/agents/messages.py"
click node_progress "https://github.com/kykiles/sysadmin-agents/blob/master/app/bot/progress.py"
click node_render "https://github.com/kykiles/sysadmin-agents/blob/master/app/bot/render.py"
click node_llm_client "https://github.com/kykiles/sysadmin-agents/blob/master/app/llm/client.py"
click node_skill_loader "https://github.com/kykiles/sysadmin-agents/blob/master/app/skills/loader.py"
click node_skill_library "https://github.com/kykiles/sysadmin-agents/tree/master/skills"
click node_skill_tools "https://github.com/kykiles/sysadmin-agents/blob/master/skills/db/tools.py"
click node_readonly "https://github.com/kykiles/sysadmin-agents/blob/master/app/skills/readonly.py"
click node_docker_tools "https://github.com/kykiles/sysadmin-agents/blob/master/app/tools/docker.py"
click node_tool_framework "https://github.com/kykiles/sysadmin-agents/blob/master/app/tools/base.py"
click node_facts "https://github.com/kykiles/sysadmin-agents/blob/master/agent_memory/facts.py"
click node_journal "https://github.com/kykiles/sysadmin-agents/blob/master/agent_memory/journal.py"
click node_consolidate "https://github.com/kykiles/sysadmin-agents/blob/master/agent_memory/consolidate.py"
click node_learning "https://github.com/kykiles/sysadmin-agents/blob/master/app/learning/review.py"
click node_history "https://github.com/kykiles/sysadmin-agents/blob/master/app/memory/history.py"
click node_monitor_loop "https://github.com/kykiles/sysadmin-agents/blob/master/app/monitoring/loop.py"
click node_monitor_checks "https://github.com/kykiles/sysadmin-agents/blob/master/app/monitoring/checks.py"
click node_monitor_state "https://github.com/kykiles/sysadmin-agents/blob/master/app/monitoring/state.py"

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_telegram,node_director,node_agent,node_messages,node_progress,node_render,node_user toneBlue
class node_llm_client,node_skill_loader,node_skill_library,node_skill_tools,node_readonly,node_docker_tools,node_tool_framework toneAmber
class node_facts,node_journal,node_consolidate,node_learning,node_history toneMint
class node_monitor_loop,node_monitor_checks,node_monitor_state toneRose
class node_host,node_llm_service toneIndigo
```

## Components

### Interaction and agents

- [Telegram bot](https://github.com/kykiles/sysadmin-agents/blob/master/app/bot/handlers.py): `app/bot/handlers.py`
- [Director](https://github.com/kykiles/sysadmin-agents/blob/master/app/agents/director.py): `app/agents/director.py`
- [Agent runtime](https://github.com/kykiles/sysadmin-agents/blob/master/app/agents/base.py): `app/agents/base.py`
- [Task results](https://github.com/kykiles/sysadmin-agents/blob/master/app/agents/messages.py): `app/agents/messages.py`
- [Task progress](https://github.com/kykiles/sysadmin-agents/blob/master/app/bot/progress.py): `app/bot/progress.py`
- [Response rendering](https://github.com/kykiles/sysadmin-agents/blob/master/app/bot/render.py): `app/bot/render.py`

### Skills and operations

- [LLM client](https://github.com/kykiles/sysadmin-agents/blob/master/app/llm/client.py): `app/llm/client.py`
- [Skill loader](https://github.com/kykiles/sysadmin-agents/blob/master/app/skills/loader.py): `app/skills/loader.py`
- [Skill packages](https://github.com/kykiles/sysadmin-agents/tree/master/skills): `skills`
- [Skill tools](https://github.com/kykiles/sysadmin-agents/blob/master/skills/db/tools.py): `skills/db/tools.py`
- [Read-only policy](https://github.com/kykiles/sysadmin-agents/blob/master/app/skills/readonly.py): `app/skills/readonly.py`
- [Docker tools](https://github.com/kykiles/sysadmin-agents/blob/master/app/tools/docker.py): `app/tools/docker.py`
- [Tool framework](https://github.com/kykiles/sysadmin-agents/blob/master/app/tools/base.py): `app/tools/base.py`

### Memory and learning

- [Knowledge facts](https://github.com/kykiles/sysadmin-agents/blob/master/agent_memory/facts.py): `agent_memory/facts.py`
- [Task journal](https://github.com/kykiles/sysadmin-agents/blob/master/agent_memory/journal.py): `agent_memory/journal.py`
- [Memory consolidation](https://github.com/kykiles/sysadmin-agents/blob/master/agent_memory/consolidate.py): `agent_memory/consolidate.py`
- [Learning review](https://github.com/kykiles/sysadmin-agents/blob/master/app/learning/review.py): `app/learning/review.py`
- [Dialog history](https://github.com/kykiles/sysadmin-agents/blob/master/app/memory/history.py): `app/memory/history.py`

### Monitoring

- [Health loop](https://github.com/kykiles/sysadmin-agents/blob/master/app/monitoring/loop.py): `app/monitoring/loop.py`
- [Health checks](https://github.com/kykiles/sysadmin-agents/blob/master/app/monitoring/checks.py): `app/monitoring/checks.py`
- [Monitor state](https://github.com/kykiles/sysadmin-agents/blob/master/app/monitoring/state.py): `app/monitoring/state.py`

### External systems

- **Managed infrastructure**
- **LLM provider**

### Other components

- **Telegram user**

## Connections

- Telegram user → Telegram bot: sends task
- Telegram bot → Director: submits task
- Director → Agent runtime: spawns agents (evidence: `app/agents/director.py`)
- Director → Skill loader: loads skills (evidence: `app/agents/director.py`)
- Skill loader → Skill packages: loads packages
- Agent runtime → LLM client: requests completion (evidence: `app/agents/base.py`)
- LLM client → LLM provider: sends prompts (evidence: `app/llm/client.py`)
- Agent runtime → Tool framework: executes tools (evidence: `app/agents/base.py`)
- Skill tools → Tool framework: builds tools (evidence: `skills/db/tools.py`)
- Skill tools → Docker tools: uses Docker API (evidence: `skills/db/tools.py`)
- Skill tools → Read-only policy: uses policy
- Docker tools → Managed infrastructure: manages containers
- Director → Knowledge facts: recalls knowledge (evidence: `app/agents/director.py`)
- Director → Task journal: records tasks
- Director → Dialog history: uses dialog history
- Learning review → Knowledge facts: reviews facts (evidence: `app/learning/review.py`)
- Learning review → Memory consolidation: requests proposals (evidence: `app/learning/review.py`)
- Memory consolidation → Task journal: reads task journal (evidence: `agent_memory/consolidate.py`)
- Telegram bot → Learning review: offers self-review (evidence: `app/bot/handlers.py`)
- Health loop → Health checks: runs checks (evidence: `app/monitoring/loop.py`)
- Health loop → Monitor state: uses state (evidence: `app/monitoring/loop.py`)
- Health checks → Managed infrastructure: checks infrastructure
- Director → Task results: returns task result (evidence: `app/agents/director.py`)
- Telegram bot → Response rendering: renders response (evidence: `app/bot/handlers.py`)
- Task results → Response rendering: formats result (evidence: `app/bot/render.py`)
- Director → Task progress: updates task plan
