# adityait019/orchestrator architecture

> Architecture diagram of the GitHub repository adityait019/orchestrator, 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/adityait019/orchestrator
- Repository: https://github.com/adityait019/orchestrator

## Overview

Nexus is a capability-driven platform for discovering remote agents, coordinating their work, and returning streamed, persistent results. The main user path is a WebSocket turn through the application’s orchestration runner, with optional planning, approval, and delegated execution; REST routes provide registry, dashboard, history, and file operations. The graph also preserves agent health/discovery, session memory, workflow state, artifacts, and tracing. Some subsystems are represented from README or index references because their implementation was not excerpted; those links are documented rather than inferred from co-location.

Main entry points: [`websocket/websocket_handler.py`](https://github.com/adityait019/orchestrator/blob/main/websocket/websocket_handler.py) (WebSocket handler), [`database/models.py`](https://github.com/adityait019/orchestrator/blob/main/database/models.py) (PostgreSQL store), [`main.py`](https://github.com/adityait019/orchestrator/blob/main/main.py) (FastAPI app), [`routers`](https://github.com/adityait019/orchestrator/tree/main/routers) (REST routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API and sessions"]
  node_app["FastAPI app<br/>[main.py]"]
  node_ws["WebSocket handler"]
  node_rest["REST routes"]
  node_session["Session manager<br/>[session_manager.py]"]
end

subgraph group_orchestration["Orchestration"]
  node_agent["Root agent<br/>[agent.py]"]
  node_planning["Plan service"]
  node_planexec["Plan execution"]
  node_context["Context broker<br/>[context_broker.py]"]
  node_hitl["HITL callbacks<br/>[hitl_handler.py]"]
end

subgraph group_agents["Agent network"]
  node_registry["Agent registry<br/>[agent_card.py]"]
  node_loader["Agent loader<br/>[agent_loader.py]"]
  node_health["Health monitor<br/>[health_monitor.py]"]
  node_execution["Agent execution"]
  node_a2a["A2A runtime<br/>[adapter.py]"]
end

subgraph group_state["State and persistence"]
  node_state["Orchestration state"]
  node_db[("PostgreSQL store<br/>[models.py]")]
  node_json[("Local JSON store<br/>[json_store.py]")]
end

subgraph group_platform["Platform services"]
  node_events["Event processor<br/>[event_processor.py]"]
  node_files["Files and artifacts<br/>[file_service.py]"]
  node_history["Chat history"]
  node_memory["ADK memory<br/>[service.py]"]
  node_observability["Tracing<br/>[tracing.py]"]
end

node_user(("User"))
node_remote{{"Remote agents"}}

node_user -->|"sends turn"| node_ws
node_user -->|"uses API"| node_rest
node_app -->|"routes WebSocket"| node_ws
node_ws -->|"ensures session"| node_session
node_ws -->|"runs turn"| node_agent
node_agent -->|"uses callbacks"| node_hitl
node_ws -->|"requests plan"| node_planning
node_ws -->|"executes plan"| node_planexec
node_planning -.->|"gets task context"| node_context
node_planexec -->|"reads and writes"| node_state
node_app -->|"loads active agents"| node_loader
node_loader -->|"loads capabilities"| node_registry
node_health -->|"updates health"| node_db
node_loader -->|"discovers agents"| node_remote
node_execution -.->|"delegates invocation"| node_a2a
node_a2a -->|"sends A2A requests"| node_remote
node_ws -->|"processes events"| node_events
node_rest -->|"serves history"| node_history
node_rest -->|"handles uploads"| node_files
node_files -->|"stores artifact metadata"| node_db
node_session -.->|"stores conversation memory"| node_memory
node_history -->|"persists history"| node_db
node_history -->|"uses local backend"| node_json
node_ws -->|"traces turns"| node_observability
node_app -->|"configures persistence"| node_db

click node_app "https://github.com/adityait019/orchestrator/blob/main/main.py"
click node_ws "https://github.com/adityait019/orchestrator/blob/main/websocket/websocket_handler.py"
click node_rest "https://github.com/adityait019/orchestrator/tree/main/routers"
click node_session "https://github.com/adityait019/orchestrator/blob/main/session/session_manager.py"
click node_agent "https://github.com/adityait019/orchestrator/blob/main/agents/agent.py"
click node_planning "https://github.com/adityait019/orchestrator/blob/main/services/planning_service.py"
click node_planexec "https://github.com/adityait019/orchestrator/blob/main/services/plan_execution_service.py"
click node_context "https://github.com/adityait019/orchestrator/blob/main/services/context_broker.py"
click node_hitl "https://github.com/adityait019/orchestrator/blob/main/agents/hitl_handler.py"
click node_registry "https://github.com/adityait019/orchestrator/blob/main/agent_registry/agent_card.py"
click node_loader "https://github.com/adityait019/orchestrator/blob/main/services/agent_loader.py"
click node_health "https://github.com/adityait019/orchestrator/blob/main/agent_registry/health_monitor.py"
click node_execution "https://github.com/adityait019/orchestrator/blob/main/services/agent_execution_service.py"
click node_a2a "https://github.com/adityait019/orchestrator/blob/main/services/a2a_runtime/adapter.py"
click node_events "https://github.com/adityait019/orchestrator/blob/main/websocket/event_processor.py"
click node_files "https://github.com/adityait019/orchestrator/blob/main/services/file_service.py"
click node_history "https://github.com/adityait019/orchestrator/blob/main/services/chat_history_service.py"
click node_memory "https://github.com/adityait019/orchestrator/blob/main/memory_management/adk_base_memory/service.py"
click node_state "https://github.com/adityait019/orchestrator/blob/main/state/orchestration_state.py"
click node_db "https://github.com/adityait019/orchestrator/blob/main/database/models.py"
click node_json "https://github.com/adityait019/orchestrator/blob/main/database/json_store.py"
click node_observability "https://github.com/adityait019/orchestrator/blob/main/observability/tracing.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_app,node_ws,node_rest,node_session,node_user toneBlue
class node_agent,node_planning,node_planexec,node_context,node_hitl toneAmber
class node_registry,node_loader,node_health,node_execution,node_a2a toneMint
class node_state,node_db,node_json toneRose
class node_events,node_files,node_history,node_memory,node_observability,node_remote toneIndigo
```

## Components

### API and sessions

- [FastAPI app](https://github.com/adityait019/orchestrator/blob/main/main.py): `main.py`
- [WebSocket handler](https://github.com/adityait019/orchestrator/blob/main/websocket/websocket_handler.py): `websocket/websocket_handler.py`
- [REST routes](https://github.com/adityait019/orchestrator/tree/main/routers): `routers`
- [Session manager](https://github.com/adityait019/orchestrator/blob/main/session/session_manager.py): `session/session_manager.py`

### Orchestration

- [Root agent](https://github.com/adityait019/orchestrator/blob/main/agents/agent.py): `agents/agent.py`
- [Plan service](https://github.com/adityait019/orchestrator/blob/main/services/planning_service.py): `services/planning_service.py`
- [Plan execution](https://github.com/adityait019/orchestrator/blob/main/services/plan_execution_service.py): `services/plan_execution_service.py`
- [Context broker](https://github.com/adityait019/orchestrator/blob/main/services/context_broker.py): `services/context_broker.py`
- [HITL callbacks](https://github.com/adityait019/orchestrator/blob/main/agents/hitl_handler.py): `agents/hitl_handler.py`

### Agent network

- [Agent registry](https://github.com/adityait019/orchestrator/blob/main/agent_registry/agent_card.py): `agent_registry/agent_card.py`
- [Agent loader](https://github.com/adityait019/orchestrator/blob/main/services/agent_loader.py): `services/agent_loader.py`
- [Health monitor](https://github.com/adityait019/orchestrator/blob/main/agent_registry/health_monitor.py): `agent_registry/health_monitor.py`
- [Agent execution](https://github.com/adityait019/orchestrator/blob/main/services/agent_execution_service.py): `services/agent_execution_service.py`
- [A2A runtime](https://github.com/adityait019/orchestrator/blob/main/services/a2a_runtime/adapter.py): `services/a2a_runtime/adapter.py`

### State and persistence

- [Orchestration state](https://github.com/adityait019/orchestrator/blob/main/state/orchestration_state.py): `state/orchestration_state.py`
- [PostgreSQL store](https://github.com/adityait019/orchestrator/blob/main/database/models.py): `database/models.py`
- [Local JSON store](https://github.com/adityait019/orchestrator/blob/main/database/json_store.py): `database/json_store.py`

### Platform services

- [Event processor](https://github.com/adityait019/orchestrator/blob/main/websocket/event_processor.py): `websocket/event_processor.py`
- [Files and artifacts](https://github.com/adityait019/orchestrator/blob/main/services/file_service.py): `services/file_service.py`
- [Chat history](https://github.com/adityait019/orchestrator/blob/main/services/chat_history_service.py): `services/chat_history_service.py`
- [ADK memory](https://github.com/adityait019/orchestrator/blob/main/memory_management/adk_base_memory/service.py): `memory_management/adk_base_memory/service.py`
- [Tracing](https://github.com/adityait019/orchestrator/blob/main/observability/tracing.py): `observability/tracing.py`

### Other components

- **User**
- **Remote agents**

## Connections

- User → WebSocket handler: sends turn
- User → REST routes: uses API
- FastAPI app → WebSocket handler: routes WebSocket (evidence: `main.py`)
- WebSocket handler → Session manager: ensures session (evidence: `websocket/websocket_handler.py`)
- WebSocket handler → Root agent: runs turn (evidence: `websocket/websocket_handler.py`)
- Root agent → HITL callbacks: uses callbacks (evidence: `agents/agent.py`)
- WebSocket handler → Plan service: requests plan (evidence: `websocket/websocket_handler.py`)
- WebSocket handler → Plan execution: executes plan (evidence: `websocket/websocket_handler.py`)
- Plan service → Context broker: gets task context
- Plan execution → Orchestration state: reads and writes (evidence: `services/plan_execution_service.py`)
- FastAPI app → Agent loader: loads active agents (evidence: `main.py`)
- Agent loader → Agent registry: loads capabilities (evidence: `services/agent_loader.py`)
- Health monitor → PostgreSQL store: updates health (evidence: `agent_registry/health_monitor.py`)
- Agent loader → Remote agents: discovers agents (evidence: `services/agent_loader.py`)
- Agent execution → A2A runtime: delegates invocation
- A2A runtime → Remote agents: sends A2A requests
- WebSocket handler → Event processor: processes events (evidence: `websocket/websocket_handler.py`)
- REST routes → Chat history: serves history (evidence: `routers/history_router.py`)
- REST routes → Files and artifacts: handles uploads (evidence: `routers/upload_router.py`)
- Files and artifacts → PostgreSQL store: stores artifact metadata
- Session manager → ADK memory: stores conversation memory
- Chat history → PostgreSQL store: persists history (evidence: `services/chat_history_service.py`)
- Chat history → Local JSON store: uses local backend (evidence: `services/chat_history_service.py`)
- WebSocket handler → Tracing: traces turns
- FastAPI app → PostgreSQL store: configures persistence
