# maxmasai/agentic-web architecture

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

- Interactive diagram: https://gitdiagram.com/maxmasai/agentic-web
- Repository: https://github.com/maxmasai/agentic-web

## Overview

Agentic Web is a PySide6 desktop platform for multi-agent AI orchestration and autonomous desktop/browser operations. Its primary flow is a user task entering the desktop application, reaching the orchestration runtime, and being delegated to specialist agents and tools before producing a result. The repository also documents canvas workflows, MCP, skills, plugins, token analytics, and live voice. The graph combines the supplied excerpts, SOURCE INDEX references, and README claims; several UI and feature implementations were not sampled, so their internal wiring is not asserted.

Main entry points: [`core/system/main.py`](https://github.com/maxmasai/agentic-web/blob/main/core/system/main.py) (Task orchestrator), [`services/llm_provider.py`](https://github.com/maxmasai/agentic-web/blob/main/services/llm_provider.py) (Model provider), [`app.py`](https://github.com/maxmasai/agentic-web/blob/main/app.py) (Desktop shell), [`browser/browser_controller.py`](https://github.com/maxmasai/agentic-web/blob/main/browser/browser_controller.py) (Browser automation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop application"]
  node_desktop["Desktop shell<br/>[app.py]"]
  node_mission_ui["Mission interfaces"]
  node_token_ui["Token dashboard"]
end

subgraph group_orchestration["Agent orchestration"]
  node_runtime["Task orchestrator<br/>[main.py]"]
  node_agent_roster["Agent roster<br/>[agentlist.py]"]
  node_agency_catalog["Agency catalog"]
  node_skill_engine["Skills manager<br/>[skills_manager.py]"]
  node_llm["Model provider<br/>[llm_provider.py]"]
end

subgraph group_capabilities["Execution capabilities"]
  node_browser["Browser automation"]
  node_canvas["Autonomous canvas<br/>[canvas_engine.py]"]
  node_tool_executor["Internal tools"]
  node_voice["Live voice<br/>[server.py]"]
  node_plugin_manager["Plugin manager<br/>[plugin_manager.py]"]
  node_mcp["MCP tools<br/>[mcp_client.py]"]
end

subgraph group_services["Platform services"]
  node_auth["Authentication<br/>[auth_service.py]"]
  node_token_service["Token tracking<br/>[token_manager.py]"]
  node_state[("Persistent state<br/>[state_store.py]")]
  node_layout["Window layouts"]
end

subgraph group_integrations["External systems"]
  node_llm_services{{"Model APIs"}}
  node_web{{"Websites"}}
  node_desktop_os{{"Desktop OS"}}
  node_mcp_servers{{"MCP servers"}}
end

node_user(("Desktop user"))

node_user -->|"starts task"| node_desktop
node_desktop -->|"starts runtime"| node_runtime
node_desktop -->|"shows pages"| node_mission_ui
node_mission_ui -.->|"submits tasks"| node_runtime
node_runtime -->|"selects agents"| node_agent_roster
node_runtime -->|"runs browser tasks"| node_browser
node_runtime -->|"executes tools"| node_tool_executor
node_runtime -->|"tiles windows"| node_layout
node_runtime -.->|"requests completion"| node_llm
node_runtime -.->|"uses specialists"| node_agency_catalog
node_agency_catalog -->|"integrates skills"| node_skill_engine
node_runtime -.->|"supports workflows"| node_canvas
node_runtime -.->|"offers voice mode"| node_voice
node_runtime -.->|"supports plugins"| node_plugin_manager
node_runtime -.->|"dispatches MCP tools"| node_mcp
node_llm -->|"checks credentials"| node_auth
node_auth -->|"authenticates"| node_llm_services
node_llm -->|"sends prompts"| node_llm_services
node_browser -->|"controls pages"| node_web
node_browser -.->|"opens applications"| node_desktop_os
node_layout -.->|"arranges windows"| node_desktop_os
node_mcp -.->|"connects tools"| node_mcp_servers
node_token_ui -->|"reads usage"| node_token_service
node_token_service -.->|"tracks consumption"| node_llm
node_runtime -.->|"persists agent state"| node_state

click node_desktop "https://github.com/maxmasai/agentic-web/blob/main/app.py"
click node_mission_ui "https://github.com/maxmasai/agentic-web/tree/main/gui/pages"
click node_token_ui "https://github.com/maxmasai/agentic-web/blob/main/gui/pages/token_manager_page.py"
click node_runtime "https://github.com/maxmasai/agentic-web/blob/main/core/system/main.py"
click node_agent_roster "https://github.com/maxmasai/agentic-web/blob/main/core/agents/agentlist.py"
click node_agency_catalog "https://github.com/maxmasai/agentic-web/blob/main/core/agency_agents_manager.py"
click node_skill_engine "https://github.com/maxmasai/agentic-web/blob/main/core/skills_manager.py"
click node_llm "https://github.com/maxmasai/agentic-web/blob/main/services/llm_provider.py"
click node_browser "https://github.com/maxmasai/agentic-web/blob/main/browser/browser_controller.py"
click node_canvas "https://github.com/maxmasai/agentic-web/blob/main/core/workflows/canvas_engine.py"
click node_tool_executor "https://github.com/maxmasai/agentic-web/blob/main/core/system/internal_tool_executor.py"
click node_voice "https://github.com/maxmasai/agentic-web/blob/main/voice/backend/server.py"
click node_plugin_manager "https://github.com/maxmasai/agentic-web/blob/main/plugins/plugin_manager.py"
click node_mcp "https://github.com/maxmasai/agentic-web/blob/main/services/mcp_client.py"
click node_auth "https://github.com/maxmasai/agentic-web/blob/main/services/auth_service.py"
click node_token_service "https://github.com/maxmasai/agentic-web/blob/main/services/token_manager.py"
click node_state "https://github.com/maxmasai/agentic-web/blob/main/system/state_store.py"
click node_layout "https://github.com/maxmasai/agentic-web/blob/main/system/fancyzones_manager.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_desktop,node_mission_ui,node_token_ui,node_user toneBlue
class node_runtime,node_agent_roster,node_agency_catalog,node_skill_engine,node_llm toneAmber
class node_browser,node_canvas,node_tool_executor,node_voice,node_plugin_manager,node_mcp toneMint
class node_auth,node_token_service,node_state,node_layout toneRose
class node_llm_services,node_web,node_desktop_os,node_mcp_servers toneIndigo
```

## Components

### Desktop application

- [Desktop shell](https://github.com/maxmasai/agentic-web/blob/main/app.py): `app.py`
- [Mission interfaces](https://github.com/maxmasai/agentic-web/tree/main/gui/pages): `gui/pages`
- [Token dashboard](https://github.com/maxmasai/agentic-web/blob/main/gui/pages/token_manager_page.py): `gui/pages/token_manager_page.py`

### Agent orchestration

- [Task orchestrator](https://github.com/maxmasai/agentic-web/blob/main/core/system/main.py): `core/system/main.py`
- [Agent roster](https://github.com/maxmasai/agentic-web/blob/main/core/agents/agentlist.py): `core/agents/agentlist.py`
- [Agency catalog](https://github.com/maxmasai/agentic-web/blob/main/core/agency_agents_manager.py): `core/agency_agents_manager.py`
- [Skills manager](https://github.com/maxmasai/agentic-web/blob/main/core/skills_manager.py): `core/skills_manager.py`
- [Model provider](https://github.com/maxmasai/agentic-web/blob/main/services/llm_provider.py): `services/llm_provider.py`

### Execution capabilities

- [Browser automation](https://github.com/maxmasai/agentic-web/blob/main/browser/browser_controller.py): `browser/browser_controller.py`
- [Autonomous canvas](https://github.com/maxmasai/agentic-web/blob/main/core/workflows/canvas_engine.py): `core/workflows/canvas_engine.py`
- [Internal tools](https://github.com/maxmasai/agentic-web/blob/main/core/system/internal_tool_executor.py): `core/system/internal_tool_executor.py`
- [Live voice](https://github.com/maxmasai/agentic-web/blob/main/voice/backend/server.py): `voice/backend/server.py`
- [Plugin manager](https://github.com/maxmasai/agentic-web/blob/main/plugins/plugin_manager.py): `plugins/plugin_manager.py`
- [MCP tools](https://github.com/maxmasai/agentic-web/blob/main/services/mcp_client.py): `services/mcp_client.py`

### Platform services

- [Authentication](https://github.com/maxmasai/agentic-web/blob/main/services/auth_service.py): `services/auth_service.py`
- [Token tracking](https://github.com/maxmasai/agentic-web/blob/main/services/token_manager.py): `services/token_manager.py`
- [Persistent state](https://github.com/maxmasai/agentic-web/blob/main/system/state_store.py): `system/state_store.py`
- [Window layouts](https://github.com/maxmasai/agentic-web/blob/main/system/fancyzones_manager.py): `system/fancyzones_manager.py`

### External systems

- **Model APIs**
- **Websites**
- **Desktop OS**
- **MCP servers**

### Other components

- **Desktop user**

## Connections

- Desktop user → Desktop shell: starts task (evidence: `README.md`)
- Desktop shell → Task orchestrator: starts runtime (evidence: `app.py`)
- Desktop shell → Mission interfaces: shows pages (evidence: `app.py`)
- Mission interfaces → Task orchestrator: submits tasks
- Task orchestrator → Agent roster: selects agents (evidence: `core/system/main.py`)
- Task orchestrator → Browser automation: runs browser tasks (evidence: `core/system/main.py`)
- Task orchestrator → Internal tools: executes tools (evidence: `core/system/main.py`)
- Task orchestrator → Window layouts: tiles windows (evidence: `core/system/main.py`)
- Task orchestrator → Model provider: requests completion
- Task orchestrator → Agency catalog: uses specialists (evidence: `README.md`)
- Agency catalog → Skills manager: integrates skills (evidence: `core/agency_agents_manager.py`)
- Task orchestrator → Autonomous canvas: supports workflows (evidence: `README.md`)
- Task orchestrator → Live voice: offers voice mode (evidence: `README.md`)
- Task orchestrator → Plugin manager: supports plugins (evidence: `README.md`)
- Task orchestrator → MCP tools: dispatches MCP tools (evidence: `README.md`)
- Model provider → Authentication: checks credentials (evidence: `services/llm_provider.py`)
- Authentication → Model APIs: authenticates (evidence: `services/auth_service.py`)
- Model provider → Model APIs: sends prompts (evidence: `services/llm_provider.py`)
- Browser automation → Websites: controls pages (evidence: `browser/browser_controller.py`)
- Browser automation → Desktop OS: opens applications (evidence: `README.md`)
- Window layouts → Desktop OS: arranges windows (evidence: `README.md`)
- MCP tools → MCP servers: connects tools (evidence: `README.md`)
- Token dashboard → Token tracking: reads usage (evidence: `gui/pages/token_manager_page.py`)
- Token tracking → Model provider: tracks consumption
- Task orchestrator → Persistent state: persists agent state (evidence: `README.md`)
