# avibe-bot/avibe architecture

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

- Interactive diagram: https://gitdiagram.com/avibe-bot/avibe
- Repository: https://github.com/avibe-bot/avibe

## Overview

Avibe is a local-first agent runtime with browser and messaging-app clients. A user submits work through the Workbench or a chat platform; the controller dispatches it to a configured agent backend, maintains session state, and returns output through the originating channel. Major parallel capabilities include Model Hub routing, durable scheduled and watched work, project/session management, agent cataloguing, and agent-built Show Pages. The README documents product-level flows; source excerpts are partial, so internal links not directly evidenced are omitted.

Main entry points: [`ui/src/App.tsx`](https://github.com/avibe-bot/avibe/blob/master/ui/src/App.tsx) (Workbench), [`core/handlers/session_handler.py`](https://github.com/avibe-bot/avibe/blob/master/core/handlers/session_handler.py) (Session Handler), [`core/controller.py`](https://github.com/avibe-bot/avibe/blob/master/core/controller.py) (Runtime Controller), [`config/v2_config.py`](https://github.com/avibe-bot/avibe/blob/master/config/v2_config.py) (Model Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_workbench["Workbench<br/>[App.tsx]"]
  node_messaging["Messaging Apps"]
end

subgraph group_runtime["Agent Runtime"]
  node_controller["Runtime Controller<br/>[controller.py]"]
  node_dispatch["Message Dispatch"]
  node_session["Session Handler<br/>[session_handler.py]"]
  node_agent_service["Agent Service<br/>[service.py]"]
  node_backends["Agent Backends<br/>[catalog.py]"]
  node_output["Message Output<br/>[message_output.py]"]
end

subgraph group_models["Model Hub"]
  node_modelhub["Model Hub Service<br/>[service.py]"]
  node_model_runtime["Gateway Runtime<br/>[client.py]"]
  node_model_config["Model Configuration<br/>[v2_config.py]"]
end

subgraph group_harness["Durable Work"]
  node_harness_tasks["Schedules and Watches<br/>[scheduled_tasks.py]"]
  node_agent_catalog["Agent Catalog<br/>[vibe_agents.py]"]
  node_show_pages["Show Pages<br/>[show_pages.py]"]
end

subgraph group_state["Local State"]
  node_session_store[("Session Services")]
  node_workbench_sessions[("Workbench Sessions")]
  node_settings["Settings Manager"]
  node_config["Config Storage<br/>[paths.py]"]
  node_db[("Local Database<br/>[db.py]")]
end

node_user(("User"))
node_external_agents["Claude, Codex, OpenCode"]

node_user -->|"uses"| node_workbench
node_user -->|"messages"| node_messaging
node_workbench -.->|"submits work"| node_controller
node_messaging -->|"delivers messages"| node_controller
node_controller -.->|"dispatches"| node_dispatch
node_dispatch -.->|"routes turns"| node_session
node_session -.->|"starts turns"| node_agent_service
node_agent_service -->|"selects backend"| node_backends
node_backends -->|"drives CLIs"| node_external_agents
node_session -->|"manages sessions"| node_session_store
node_session -->|"produces replies"| node_output
node_output -.->|"delivers replies"| node_messaging
node_workbench -.->|"manages sessions"| node_workbench_sessions
node_modelhub -.->|"configures routes"| node_model_config
node_model_runtime -->|"reads configuration"| node_model_config
node_backends -->|"uses gateway"| node_model_runtime
node_controller -->|"sets up platforms"| node_settings
node_settings -.->|"reads settings"| node_model_config
node_harness_tasks -.->|"uses sessions"| node_session_store
node_agent_catalog -->|"persists agents"| node_db
node_workbench -->|"manages agents"| node_agent_catalog
node_workbench -->|"opens Show Pages"| node_show_pages
node_session_store -->|"stores session state"| node_db
node_workbench_sessions -->|"queries sessions"| node_db
node_config -->|"provides config paths"| node_model_config

click node_workbench "https://github.com/avibe-bot/avibe/blob/master/ui/src/App.tsx"
click node_messaging "https://github.com/avibe-bot/avibe/tree/master/modules/im"
click node_controller "https://github.com/avibe-bot/avibe/blob/master/core/controller.py"
click node_dispatch "https://github.com/avibe-bot/avibe/blob/master/core/message_dispatcher.py"
click node_session "https://github.com/avibe-bot/avibe/blob/master/core/handlers/session_handler.py"
click node_agent_service "https://github.com/avibe-bot/avibe/blob/master/modules/agents/service.py"
click node_backends "https://github.com/avibe-bot/avibe/blob/master/modules/agents/catalog.py"
click node_output "https://github.com/avibe-bot/avibe/blob/master/core/message_output.py"
click node_modelhub "https://github.com/avibe-bot/avibe/blob/master/core/handlers/model_hub/service.py"
click node_model_runtime "https://github.com/avibe-bot/avibe/blob/master/vibe/model_hub_runtime/client.py"
click node_model_config "https://github.com/avibe-bot/avibe/blob/master/config/v2_config.py"
click node_harness_tasks "https://github.com/avibe-bot/avibe/blob/master/core/scheduled_tasks.py"
click node_agent_catalog "https://github.com/avibe-bot/avibe/blob/master/core/vibe_agents.py"
click node_show_pages "https://github.com/avibe-bot/avibe/blob/master/core/show_pages.py"
click node_session_store "https://github.com/avibe-bot/avibe/blob/master/storage/sessions_service.py"
click node_workbench_sessions "https://github.com/avibe-bot/avibe/blob/master/storage/workbench_sessions_service.py"
click node_settings "https://github.com/avibe-bot/avibe/blob/master/modules/settings_manager.py"
click node_config "https://github.com/avibe-bot/avibe/blob/master/config/paths.py"
click node_db "https://github.com/avibe-bot/avibe/blob/master/storage/db.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_workbench,node_messaging,node_user toneBlue
class node_controller,node_dispatch,node_session,node_agent_service,node_backends,node_output toneAmber
class node_modelhub,node_model_runtime,node_model_config toneMint
class node_harness_tasks,node_agent_catalog,node_show_pages toneRose
class node_session_store,node_workbench_sessions,node_settings,node_config,node_db,node_external_agents toneIndigo
```

## Components

### User Interfaces

- [Workbench](https://github.com/avibe-bot/avibe/blob/master/ui/src/App.tsx): `ui/src/App.tsx`
- [Messaging Apps](https://github.com/avibe-bot/avibe/tree/master/modules/im): `modules/im`

### Agent Runtime

- [Runtime Controller](https://github.com/avibe-bot/avibe/blob/master/core/controller.py): `core/controller.py`
- [Message Dispatch](https://github.com/avibe-bot/avibe/blob/master/core/message_dispatcher.py): `core/message_dispatcher.py`
- [Session Handler](https://github.com/avibe-bot/avibe/blob/master/core/handlers/session_handler.py): `core/handlers/session_handler.py`
- [Agent Service](https://github.com/avibe-bot/avibe/blob/master/modules/agents/service.py): `modules/agents/service.py`
- [Agent Backends](https://github.com/avibe-bot/avibe/blob/master/modules/agents/catalog.py): `modules/agents/catalog.py`
- [Message Output](https://github.com/avibe-bot/avibe/blob/master/core/message_output.py): `core/message_output.py`

### Model Hub

- [Model Hub Service](https://github.com/avibe-bot/avibe/blob/master/core/handlers/model_hub/service.py): `core/handlers/model_hub/service.py`
- [Gateway Runtime](https://github.com/avibe-bot/avibe/blob/master/vibe/model_hub_runtime/client.py): `vibe/model_hub_runtime/client.py`
- [Model Configuration](https://github.com/avibe-bot/avibe/blob/master/config/v2_config.py): `config/v2_config.py`

### Durable Work

- [Schedules and Watches](https://github.com/avibe-bot/avibe/blob/master/core/scheduled_tasks.py): `core/scheduled_tasks.py`
- [Agent Catalog](https://github.com/avibe-bot/avibe/blob/master/core/vibe_agents.py): `core/vibe_agents.py`
- [Show Pages](https://github.com/avibe-bot/avibe/blob/master/core/show_pages.py): `core/show_pages.py`

### Local State

- [Session Services](https://github.com/avibe-bot/avibe/blob/master/storage/sessions_service.py): `storage/sessions_service.py`
- [Workbench Sessions](https://github.com/avibe-bot/avibe/blob/master/storage/workbench_sessions_service.py): `storage/workbench_sessions_service.py`
- [Settings Manager](https://github.com/avibe-bot/avibe/blob/master/modules/settings_manager.py): `modules/settings_manager.py`
- [Config Storage](https://github.com/avibe-bot/avibe/blob/master/config/paths.py): `config/paths.py`
- [Local Database](https://github.com/avibe-bot/avibe/blob/master/storage/db.py): `storage/db.py`

### Other components

- **User**
- **Claude, Codex, OpenCode**

## Connections

- User → Workbench: uses (evidence: `README.md`)
- User → Messaging Apps: messages (evidence: `README.md`)
- Workbench → Runtime Controller: submits work
- Messaging Apps → Runtime Controller: delivers messages (evidence: `core/controller.py`)
- Runtime Controller → Message Dispatch: dispatches (evidence: `core/controller.py`)
- Message Dispatch → Session Handler: routes turns
- Session Handler → Agent Service: starts turns
- Agent Service → Agent Backends: selects backend (evidence: `modules/agents/service.py`)
- Agent Backends → Claude, Codex, OpenCode: drives CLIs (evidence: `README.md`)
- Session Handler → Session Services: manages sessions (evidence: `core/handlers/session_handler.py`)
- Session Handler → Message Output: produces replies (evidence: `core/handlers/session_handler.py`)
- Message Output → Messaging Apps: delivers replies
- Workbench → Workbench Sessions: manages sessions
- Model Hub Service → Model Configuration: configures routes (evidence: `core/handlers/model_hub/service.py`)
- Gateway Runtime → Model Configuration: reads configuration (evidence: `vibe/model_hub_runtime/client.py`)
- Agent Backends → Gateway Runtime: uses gateway (evidence: `README.md`)
- Runtime Controller → Settings Manager: sets up platforms (evidence: `core/controller.py`)
- Settings Manager → Model Configuration: reads settings
- Schedules and Watches → Session Services: uses sessions
- Agent Catalog → Local Database: persists agents (evidence: `core/vibe_agents.py`)
- Workbench → Agent Catalog: manages agents (evidence: `README.md`)
- Workbench → Show Pages: opens Show Pages (evidence: `README.md`)
- Session Services → Local Database: stores session state (evidence: `storage/sessions_service.py`)
- Workbench Sessions → Local Database: queries sessions (evidence: `storage/workbench_sessions_service.py`)
- Config Storage → Model Configuration: provides config paths (evidence: `config/v2_config.py`)