# dani12po/zevora architecture

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

- Interactive diagram: https://gitdiagram.com/dani12po/zevora
- Repository: https://github.com/dani12po/zevora

## Overview

ZEVORA is a hybrid AI coding workspace: users submit chat or coding tasks through its browser UI, the gateway coordinates agent execution, local context and adaptive model routing, and the selected provider returns a response that may include workspace changes and verification. The README documents cache, memory, project context, evolution, provider management and approval-gated tools as additional capabilities. The excerpts show selected internals; subsystem links not established by those excerpts are based on the README’s documented workflow.

Main entry points: [`agent/core/execution.py`](https://github.com/dani12po/zevora/blob/main/agent/core/execution.py) (Agent Execution), [`main.py`](https://github.com/dani12po/zevora/blob/main/main.py) (API Gateway), [`static/app.js`](https://github.com/dani12po/zevora/blob/main/static/app.js) (Web UI), [`agent/routing/hybrid_router.py`](https://github.com/dani12po/zevora/blob/main/agent/routing/hybrid_router.py) (Adaptive Router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Workspace Experience"]
  node_web_ui["Web UI<br/>[app.js]"]
  node_gateway["API Gateway<br/>[main.py]"]
  node_controller["Gateway Controller<br/>[cli.py]"]
end

subgraph group_agent["Agent Workflow"]
  node_execution["Agent Execution<br/>[execution.py]"]
  node_planning["Task Planning<br/>[planning.py]"]
  node_workflow_journal["Workflow Journal<br/>[main.py]"]
end

subgraph group_intelligence["Local Intelligence"]
  node_project_context["Project Context<br/>[project_index.py]"]
  node_local_intelligence["Local Intelligence<br/>[engine.py]"]
  node_memory[("Memory Store<br/>[store.py]")]
  node_cache[("Exact Cache<br/>[engine.py]")]
  node_evolution["Experience Evolution<br/>[engine.py]"]
  node_skills["Skill Registry<br/>[registry.py]"]
end

subgraph group_inference["Inference and Providers"]
  node_router["Adaptive Router<br/>[hybrid_router.py]"]
  node_quality_fallback["Quality and Fallback<br/>[quality_gate.py]"]
  node_local_provider["Local AI Provider<br/>[local_provider.py]"]
  node_cloud_providers["Cloud Providers<br/>[registry.py]"]
  node_provider_management["Provider Management<br/>[service.py]"]
  node_local_model_manager["Local Model Manager<br/>[manager.py]"]
end

subgraph group_workspace["Workspace Tools"]
  node_mcp_tools["MCP Tools<br/>[mcp_gateway.py]"]
  node_workspace_access["Workspace Access<br/>[workspace.py]"]
  node_terminal["Terminal Sessions"]
end

node_user(("User"))

node_user -->|"submits task"| node_web_ui
node_web_ui -->|"sends request"| node_gateway
node_gateway -->|"dispatches chat"| node_execution
node_execution -->|"plans task"| node_planning
node_execution -->|"retrieves context"| node_project_context
node_execution -->|"checks cache and context"| node_local_intelligence
node_local_intelligence -->|"reads and writes"| node_cache
node_local_intelligence -->|"retrieves memory"| node_memory
node_execution -->|"requests candidate"| node_router
node_router -->|"selects local"| node_local_provider
node_router -->|"selects cloud"| node_cloud_providers
node_execution -->|"checks response"| node_quality_fallback
node_quality_fallback -->|"requests fallback"| node_router
node_execution -.->|"dispatches tools"| node_mcp_tools
node_mcp_tools -.->|"accesses files"| node_workspace_access
node_mcp_tools -.->|"runs commands"| node_terminal
node_gateway -->|"records activity"| node_workflow_journal
node_workflow_journal -->|"streams progress"| node_web_ui
node_gateway -->|"returns response"| node_web_ui
node_execution -->|"records outcome"| node_evolution
node_evolution -->|"registers approved skill"| node_skills
node_web_ui -->|"manages providers"| node_provider_management
node_provider_management -->|"updates registry"| node_cloud_providers
node_local_model_manager -->|"reports runtime state"| node_local_provider
node_controller -->|"starts and stops"| node_gateway

click node_web_ui "https://github.com/dani12po/zevora/blob/main/static/app.js"
click node_gateway "https://github.com/dani12po/zevora/blob/main/main.py"
click node_controller "https://github.com/dani12po/zevora/blob/main/zevora/cli.py"
click node_execution "https://github.com/dani12po/zevora/blob/main/agent/core/execution.py"
click node_planning "https://github.com/dani12po/zevora/blob/main/agent/core/planning.py"
click node_workflow_journal "https://github.com/dani12po/zevora/blob/main/main.py"
click node_project_context "https://github.com/dani12po/zevora/blob/main/agent/core/project_index.py"
click node_local_intelligence "https://github.com/dani12po/zevora/blob/main/agent/intelligence/engine.py"
click node_memory "https://github.com/dani12po/zevora/blob/main/agent/memory/store.py"
click node_cache "https://github.com/dani12po/zevora/blob/main/agent/intelligence/engine.py"
click node_evolution "https://github.com/dani12po/zevora/blob/main/agent/evolution/engine.py"
click node_skills "https://github.com/dani12po/zevora/blob/main/agent/skills/registry.py"
click node_router "https://github.com/dani12po/zevora/blob/main/agent/routing/hybrid_router.py"
click node_quality_fallback "https://github.com/dani12po/zevora/blob/main/agent/routing/quality_gate.py"
click node_local_provider "https://github.com/dani12po/zevora/blob/main/agent/providers/local_provider.py"
click node_cloud_providers "https://github.com/dani12po/zevora/blob/main/agent/providers/registry.py"
click node_provider_management "https://github.com/dani12po/zevora/blob/main/agent/providers/service.py"
click node_mcp_tools "https://github.com/dani12po/zevora/blob/main/agent/tools/mcp_gateway.py"
click node_workspace_access "https://github.com/dani12po/zevora/blob/main/agent/core/workspace.py"
click node_terminal "https://github.com/dani12po/zevora/blob/main/agent/tools/terminal_sessions.py"
click node_local_model_manager "https://github.com/dani12po/zevora/blob/main/agent/models/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_web_ui,node_gateway,node_controller,node_user toneBlue
class node_execution,node_planning,node_workflow_journal toneAmber
class node_project_context,node_local_intelligence,node_memory,node_cache,node_evolution,node_skills toneMint
class node_router,node_quality_fallback,node_local_provider,node_cloud_providers,node_provider_management,node_local_model_manager toneRose
class node_mcp_tools,node_workspace_access,node_terminal toneIndigo
```

## Components

### Workspace Experience

- [Web UI](https://github.com/dani12po/zevora/blob/main/static/app.js): `static/app.js`
- [API Gateway](https://github.com/dani12po/zevora/blob/main/main.py): `main.py`
- [Gateway Controller](https://github.com/dani12po/zevora/blob/main/zevora/cli.py): `zevora/cli.py`

### Agent Workflow

- [Agent Execution](https://github.com/dani12po/zevora/blob/main/agent/core/execution.py): `agent/core/execution.py`
- [Task Planning](https://github.com/dani12po/zevora/blob/main/agent/core/planning.py): `agent/core/planning.py`
- [Workflow Journal](https://github.com/dani12po/zevora/blob/main/main.py): `main.py`

### Local Intelligence

- [Project Context](https://github.com/dani12po/zevora/blob/main/agent/core/project_index.py): `agent/core/project_index.py`
- [Local Intelligence](https://github.com/dani12po/zevora/blob/main/agent/intelligence/engine.py): `agent/intelligence/engine.py`
- [Memory Store](https://github.com/dani12po/zevora/blob/main/agent/memory/store.py): `agent/memory/store.py`
- [Exact Cache](https://github.com/dani12po/zevora/blob/main/agent/intelligence/engine.py): `agent/intelligence/engine.py`
- [Experience Evolution](https://github.com/dani12po/zevora/blob/main/agent/evolution/engine.py): `agent/evolution/engine.py`
- [Skill Registry](https://github.com/dani12po/zevora/blob/main/agent/skills/registry.py): `agent/skills/registry.py`

### Inference and Providers

- [Adaptive Router](https://github.com/dani12po/zevora/blob/main/agent/routing/hybrid_router.py): `agent/routing/hybrid_router.py`
- [Quality and Fallback](https://github.com/dani12po/zevora/blob/main/agent/routing/quality_gate.py): `agent/routing/quality_gate.py`
- [Local AI Provider](https://github.com/dani12po/zevora/blob/main/agent/providers/local_provider.py): `agent/providers/local_provider.py`
- [Cloud Providers](https://github.com/dani12po/zevora/blob/main/agent/providers/registry.py): `agent/providers/registry.py`
- [Provider Management](https://github.com/dani12po/zevora/blob/main/agent/providers/service.py): `agent/providers/service.py`
- [Local Model Manager](https://github.com/dani12po/zevora/blob/main/agent/models/manager.py): `agent/models/manager.py`

### Workspace Tools

- [MCP Tools](https://github.com/dani12po/zevora/blob/main/agent/tools/mcp_gateway.py): `agent/tools/mcp_gateway.py`
- [Workspace Access](https://github.com/dani12po/zevora/blob/main/agent/core/workspace.py): `agent/core/workspace.py`
- [Terminal Sessions](https://github.com/dani12po/zevora/blob/main/agent/tools/terminal_sessions.py): `agent/tools/terminal_sessions.py`

### Other components

- **User**

## Connections

- User → Web UI: submits task
- Web UI → API Gateway: sends request
- API Gateway → Agent Execution: dispatches chat
- Agent Execution → Task Planning: plans task
- Agent Execution → Project Context: retrieves context
- Agent Execution → Local Intelligence: checks cache and context
- Local Intelligence → Exact Cache: reads and writes
- Local Intelligence → Memory Store: retrieves memory
- Agent Execution → Adaptive Router: requests candidate
- Adaptive Router → Local AI Provider: selects local
- Adaptive Router → Cloud Providers: selects cloud
- Agent Execution → Quality and Fallback: checks response
- Quality and Fallback → Adaptive Router: requests fallback
- Agent Execution → MCP Tools: dispatches tools
- MCP Tools → Workspace Access: accesses files
- MCP Tools → Terminal Sessions: runs commands
- API Gateway → Workflow Journal: records activity
- Workflow Journal → Web UI: streams progress
- API Gateway → Web UI: returns response
- Agent Execution → Experience Evolution: records outcome
- Experience Evolution → Skill Registry: registers approved skill
- Web UI → Provider Management: manages providers
- Provider Management → Cloud Providers: updates registry
- Local Model Manager → Local AI Provider: reports runtime state
- Gateway Controller → API Gateway: starts and stops