# zazencodes/koyomi architecture

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

- Interactive diagram: https://gitdiagram.com/zazencodes/koyomi
- Repository: https://github.com/zazencodes/koyomi

## Overview

Koyomi is a small distributed job scheduler implemented in one Python module. Users manage jobs through the CLI or terminal dashboard; host schedulers ask the hub for due work, execute jobs locally, and report results and logs. The hub keeps job, run, host, and alert state as JSON. The README documents SSH-based remote access, catch-up behavior, service operation, and email alerts; the sampled source is partial, so internal call paths beyond those documented are not asserted.

Main entry points: [`koyomi.py`](https://github.com/zazencodes/koyomi/blob/main/koyomi.py) (Hub RPC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI commands<br/>[koyomi.py]"]
  node_dashboard["Terminal dashboard<br/>[koyomi.py]"]
end

subgraph group_coordination["Scheduling and coordination"]
  node_rpc["Hub RPC<br/>[koyomi.py]"]
  node_ssh["SSH transport"]
  node_scheduler["Host scheduler<br/>[koyomi.py]"]
  node_schedule["Schedule and catch-up<br/>[koyomi.py]"]
  node_jobcontrol["Job management<br/>[koyomi.py]"]
end

subgraph group_execution["Execution and results"]
  node_runner["Job runner<br/>[koyomi.py]"]
  node_output["Output streaming<br/>[koyomi.py]"]
  node_logs["Run logs and history<br/>[koyomi.py]"]
end

subgraph group_operations["State and alerts"]
  node_jsonstate[("Hub JSON state<br/>[koyomi.py]")]
  node_hoststatus["Host heartbeats<br/>[koyomi.py]"]
  node_alerts["Alert handling<br/>[koyomi.py]"]
end

node_user(("Operator"))
node_email["Email service"]
node_service["OS service manager"]

node_user -->|"runs commands"| node_cli
node_user -->|"opens dashboard"| node_dashboard
node_cli -->|"requests actions"| node_rpc
node_dashboard -->|"reloads and controls"| node_rpc
node_rpc -->|"uses for remote hub"| node_ssh
node_ssh -->|"routes to hub"| node_rpc
node_scheduler -->|"requests due runs"| node_rpc
node_scheduler -.->|"checks due slots"| node_schedule
node_rpc -.->|"dispatches job actions"| node_jobcontrol
node_jobcontrol -.->|"updates job state"| node_jsonstate
node_scheduler -->|"runs due jobs"| node_runner
node_runner -->|"streams output"| node_output
node_output -->|"uploads run output"| node_logs
node_scheduler -->|"reports results"| node_rpc
node_rpc -->|"stores run records"| node_jsonstate
node_rpc -.->|"records host reports"| node_hoststatus
node_scheduler -.->|"reports failures"| node_alerts
node_alerts -->|"sends alerts"| node_email
node_service -->|"starts scheduler"| node_scheduler
node_cli -->|"shows run logs"| node_logs
node_dashboard -->|"views run logs"| node_logs

click node_cli "https://github.com/zazencodes/koyomi/blob/main/koyomi.py"
click node_dashboard "https://github.com/zazencodes/koyomi/blob/main/koyomi.py"
click node_rpc "https://github.com/zazencodes/koyomi/blob/main/koyomi.py"
click node_scheduler "https://github.com/zazencodes/koyomi/blob/main/koyomi.py"
click node_schedule "https://github.com/zazencodes/koyomi/blob/main/koyomi.py"
click node_jobcontrol "https://github.com/zazencodes/koyomi/blob/main/koyomi.py"
click node_runner "https://github.com/zazencodes/koyomi/blob/main/koyomi.py"
click node_output "https://github.com/zazencodes/koyomi/blob/main/koyomi.py"
click node_logs "https://github.com/zazencodes/koyomi/blob/main/koyomi.py"
click node_jsonstate "https://github.com/zazencodes/koyomi/blob/main/koyomi.py"
click node_hoststatus "https://github.com/zazencodes/koyomi/blob/main/koyomi.py"
click node_alerts "https://github.com/zazencodes/koyomi/blob/main/koyomi.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_cli,node_dashboard toneBlue
class node_rpc,node_ssh,node_scheduler,node_schedule,node_jobcontrol toneAmber
class node_runner,node_output,node_logs toneMint
class node_jsonstate,node_hoststatus,node_alerts toneRose
class node_user,node_email,node_service toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/zazencodes/koyomi/blob/main/koyomi.py): `koyomi.py`
- [Terminal dashboard](https://github.com/zazencodes/koyomi/blob/main/koyomi.py): `koyomi.py`

### Scheduling and coordination

- [Hub RPC](https://github.com/zazencodes/koyomi/blob/main/koyomi.py): `koyomi.py`
- **SSH transport**
- [Host scheduler](https://github.com/zazencodes/koyomi/blob/main/koyomi.py): `koyomi.py`
- [Schedule and catch-up](https://github.com/zazencodes/koyomi/blob/main/koyomi.py): `koyomi.py`
- [Job management](https://github.com/zazencodes/koyomi/blob/main/koyomi.py): `koyomi.py`

### Execution and results

- [Job runner](https://github.com/zazencodes/koyomi/blob/main/koyomi.py): `koyomi.py`
- [Output streaming](https://github.com/zazencodes/koyomi/blob/main/koyomi.py): `koyomi.py`
- [Run logs and history](https://github.com/zazencodes/koyomi/blob/main/koyomi.py): `koyomi.py`

### State and alerts

- [Hub JSON state](https://github.com/zazencodes/koyomi/blob/main/koyomi.py): `koyomi.py`
- [Host heartbeats](https://github.com/zazencodes/koyomi/blob/main/koyomi.py): `koyomi.py`
- [Alert handling](https://github.com/zazencodes/koyomi/blob/main/koyomi.py): `koyomi.py`

### Other components

- **Operator**
- **Email service**
- **OS service manager**

## Connections

- Operator → CLI commands: runs commands (evidence: `README.md`)
- Operator → Terminal dashboard: opens dashboard (evidence: `README.md`)
- CLI commands → Hub RPC: requests actions (evidence: `README.md`)
- Terminal dashboard → Hub RPC: reloads and controls (evidence: `README.md`)
- Hub RPC → SSH transport: uses for remote hub (evidence: `README.md`)
- SSH transport → Hub RPC: routes to hub (evidence: `README.md`)
- Host scheduler → Hub RPC: requests due runs (evidence: `README.md`)
- Host scheduler → Schedule and catch-up: checks due slots (evidence: `koyomi.py`)
- Hub RPC → Job management: dispatches job actions (evidence: `koyomi.py`)
- Job management → Hub JSON state: updates job state (evidence: `koyomi.py`)
- Host scheduler → Job runner: runs due jobs (evidence: `README.md`)
- Job runner → Output streaming: streams output (evidence: `README.md`)
- Output streaming → Run logs and history: uploads run output (evidence: `README.md`)
- Host scheduler → Hub RPC: reports results (evidence: `README.md`)
- Hub RPC → Hub JSON state: stores run records (evidence: `README.md`)
- Hub RPC → Host heartbeats: records host reports (evidence: `koyomi.py`)
- Host scheduler → Alert handling: reports failures (evidence: `koyomi.py`)
- Alert handling → Email service: sends alerts (evidence: `README.md`)
- OS service manager → Host scheduler: starts scheduler (evidence: `README.md`)
- CLI commands → Run logs and history: shows run logs (evidence: `README.md`)
- Terminal dashboard → Run logs and history: views run logs (evidence: `README.md`)
