# tharunkumarra/avatar-os-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/tharunkumarra/avatar-os-v2
- Repository: https://github.com/tharunkumarra/avatar-os-v2

## Overview

Avatar OS is a registry-driven personal operating system built from four independent Hermes profiles that use Discord and coordinate through shared durable state. The main workflow is an agent recording an observation through the profile-bound plugin; the runtime authenticates and validates it against registry capabilities and domain definitions, journals the event, and reconciles projections into snapshots and rendered views. The repository also defines scheduled workflows and supports registry extension, deployment previews, and generation recovery. Edges reflect README statements and shown calls; unsampled subsystem relationships are omitted where not documented.

Main entry points: [`shared/avatar-os/tools/avatar_os.py`](https://github.com/tharunkumarra/avatar-os-v2/blob/main/shared/avatar-os/tools/avatar_os.py) (Avatar OS Runtime), [`integrations/hermes/avatar-os/__init__.py`](https://github.com/tharunkumarra/avatar-os-v2/blob/main/integrations/hermes/avatar-os/__init__.py) (Avatar OS Plugin), [`registry/system.json`](https://github.com/tharunkumarra/avatar-os-v2/blob/main/registry/system.json) (System Registry), [`profiles`](https://github.com/tharunkumarra/avatar-os-v2/tree/main/profiles) (Hermes Profiles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agents["Agents and Integration"]
  node_hermes["Hermes Profiles"]
  node_policies["Roles and Skills"]
  node_plugin["Avatar OS Plugin<br/>[__init__.py]"]
  node_cron["Profile Schedules"]
end

subgraph group_domain["Registry and Domains"]
  node_registry["System Registry<br/>[system.json]"]
  node_domains["Domain Manifests"]
  node_workflows["Workflow Definitions<br/>[workflows.json]"]
end

subgraph group_runtime["State Runtime"]
  node_runtime["Avatar OS Runtime<br/>[avatar_os.py]"]
  node_event_journal[("Event Journal")]
  node_snapshots["Projections and Views"]
  node_shared_state["Shared State Resources"]
end

subgraph group_operations["Operations"]
  node_schedule_renderer["Schedule Renderer"]
  node_scaffold["Registry Scaffolder<br/>[scaffold.py]"]
  node_deployment["Deployment Preview<br/>[deployment_plan.py]"]
  node_recovery["Generation Recovery<br/>[avatar_ops.py]"]
end

node_user(("User"))
node_discord(("Discord"))
node_operator(("Operator"))

node_user -->|"messages"| node_discord
node_discord -->|"routes sessions"| node_hermes
node_hermes -->|"registers tools"| node_plugin
node_hermes -->|"uses role policy"| node_policies
node_plugin -->|"loads and handles"| node_runtime
node_plugin -->|"reads identity and capabilities"| node_registry
node_plugin -->|"reads or writes resources"| node_shared_state
node_runtime -->|"compiles configuration"| node_registry
node_runtime -->|"validates event definitions"| node_domains
node_runtime -->|"appends events"| node_event_journal
node_runtime -->|"projects and renders"| node_snapshots
node_workflows -->|"defines schedules"| node_schedule_renderer
node_domains -->|"contributes close prompts"| node_schedule_renderer
node_schedule_renderer -->|"renders jobs"| node_cron
node_scaffold -->|"plans or creates entries"| node_registry
node_operator -->|"requests preview"| node_deployment
node_operator -->|"inspects or rolls back"| node_recovery
node_recovery -->|"activates generation"| node_registry

click node_hermes "https://github.com/tharunkumarra/avatar-os-v2/tree/main/profiles"
click node_policies "https://github.com/tharunkumarra/avatar-os-v2/tree/main/policy"
click node_plugin "https://github.com/tharunkumarra/avatar-os-v2/blob/main/integrations/hermes/avatar-os/__init__.py"
click node_registry "https://github.com/tharunkumarra/avatar-os-v2/blob/main/registry/system.json"
click node_domains "https://github.com/tharunkumarra/avatar-os-v2/tree/main/registry/domains"
click node_workflows "https://github.com/tharunkumarra/avatar-os-v2/blob/main/registry/workflows.json"
click node_schedule_renderer "https://github.com/tharunkumarra/avatar-os-v2/blob/main/scripts/render_workflows.py"
click node_cron "https://github.com/tharunkumarra/avatar-os-v2/tree/main/profiles"
click node_runtime "https://github.com/tharunkumarra/avatar-os-v2/blob/main/shared/avatar-os/tools/avatar_os.py"
click node_event_journal "https://github.com/tharunkumarra/avatar-os-v2/tree/main/shared/avatar-os"
click node_snapshots "https://github.com/tharunkumarra/avatar-os-v2/tree/main/shared/avatar-os"
click node_shared_state "https://github.com/tharunkumarra/avatar-os-v2/tree/main/shared/avatar-os"
click node_scaffold "https://github.com/tharunkumarra/avatar-os-v2/blob/main/scripts/scaffold.py"
click node_deployment "https://github.com/tharunkumarra/avatar-os-v2/blob/main/scripts/deployment_plan.py"
click node_recovery "https://github.com/tharunkumarra/avatar-os-v2/blob/main/scripts/avatar_ops.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_hermes,node_policies,node_plugin,node_cron,node_user toneBlue
class node_registry,node_domains,node_workflows toneAmber
class node_runtime,node_event_journal,node_snapshots,node_shared_state toneMint
class node_schedule_renderer,node_scaffold,node_deployment,node_recovery toneRose
class node_discord,node_operator toneIndigo
```

## Components

### Agents and Integration

- [Hermes Profiles](https://github.com/tharunkumarra/avatar-os-v2/tree/main/profiles): `profiles`
- [Roles and Skills](https://github.com/tharunkumarra/avatar-os-v2/tree/main/policy): `policy`
- [Avatar OS Plugin](https://github.com/tharunkumarra/avatar-os-v2/blob/main/integrations/hermes/avatar-os/__init__.py): `integrations/hermes/avatar-os/__init__.py`
- [Profile Schedules](https://github.com/tharunkumarra/avatar-os-v2/tree/main/profiles): `profiles`

### Registry and Domains

- [System Registry](https://github.com/tharunkumarra/avatar-os-v2/blob/main/registry/system.json): `registry/system.json`
- [Domain Manifests](https://github.com/tharunkumarra/avatar-os-v2/tree/main/registry/domains): `registry/domains`
- [Workflow Definitions](https://github.com/tharunkumarra/avatar-os-v2/blob/main/registry/workflows.json): `registry/workflows.json`

### State Runtime

- [Avatar OS Runtime](https://github.com/tharunkumarra/avatar-os-v2/blob/main/shared/avatar-os/tools/avatar_os.py): `shared/avatar-os/tools/avatar_os.py`
- [Event Journal](https://github.com/tharunkumarra/avatar-os-v2/tree/main/shared/avatar-os): `shared/avatar-os`
- [Projections and Views](https://github.com/tharunkumarra/avatar-os-v2/tree/main/shared/avatar-os): `shared/avatar-os`
- [Shared State Resources](https://github.com/tharunkumarra/avatar-os-v2/tree/main/shared/avatar-os): `shared/avatar-os`

### Operations

- [Schedule Renderer](https://github.com/tharunkumarra/avatar-os-v2/blob/main/scripts/render_workflows.py): `scripts/render_workflows.py`
- [Registry Scaffolder](https://github.com/tharunkumarra/avatar-os-v2/blob/main/scripts/scaffold.py): `scripts/scaffold.py`
- [Deployment Preview](https://github.com/tharunkumarra/avatar-os-v2/blob/main/scripts/deployment_plan.py): `scripts/deployment_plan.py`
- [Generation Recovery](https://github.com/tharunkumarra/avatar-os-v2/blob/main/scripts/avatar_ops.py): `scripts/avatar_ops.py`

### Other components

- **User**
- **Discord**
- **Operator**

## Connections

- User → Discord: messages (evidence: `README.md`)
- Discord → Hermes Profiles: routes sessions (evidence: `README.md`)
- Hermes Profiles → Avatar OS Plugin: registers tools (evidence: `README.md`)
- Hermes Profiles → Roles and Skills: uses role policy (evidence: `README.md`)
- Avatar OS Plugin → Avatar OS Runtime: loads and handles (evidence: `integrations/hermes/avatar-os/__init__.py`)
- Avatar OS Plugin → System Registry: reads identity and capabilities (evidence: `integrations/hermes/avatar-os/__init__.py`)
- Avatar OS Plugin → Shared State Resources: reads or writes resources (evidence: `integrations/hermes/avatar-os/__init__.py`)
- Avatar OS Runtime → System Registry: compiles configuration (evidence: `README.md`)
- Avatar OS Runtime → Domain Manifests: validates event definitions (evidence: `README.md`)
- Avatar OS Runtime → Event Journal: appends events (evidence: `README.md`)
- Avatar OS Runtime → Projections and Views: projects and renders (evidence: `README.md`)
- Workflow Definitions → Schedule Renderer: defines schedules (evidence: `README.md`)
- Domain Manifests → Schedule Renderer: contributes close prompts (evidence: `README.md`)
- Schedule Renderer → Profile Schedules: renders jobs (evidence: `README.md`)
- Registry Scaffolder → System Registry: plans or creates entries (evidence: `README.md`)
- Operator → Deployment Preview: requests preview (evidence: `README.md`)
- Operator → Generation Recovery: inspects or rolls back (evidence: `README.md`)
- Generation Recovery → System Registry: activates generation (evidence: `README.md`)
