How adityait019/orchestrator works
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_handler.py WebSocket handler · models.py PostgreSQL store · main.py FastAPI app · routers REST routes
Components 24
API and sessions
- FastAPI app
main.py - WebSocket handler
websocket/websocket_handler.py - REST routes
routers - Session manager
session/session_manager.py
Orchestration
- Root agent
agents/agent.py - Plan service
services/planning_service.py - Plan execution
services/plan_execution_service.py - Context broker
services/context_broker.py - HITL callbacks
agents/hitl_handler.py
Agent network
- Agent registry
agent_registry/agent_card.py - Agent loader
services/agent_loader.py - Health monitor
agent_registry/health_monitor.py - Agent execution
services/agent_execution_service.py - A2A runtime
services/a2a_runtime/adapter.py
State and persistence
- Orchestration state
state/orchestration_state.py - PostgreSQL store
database/models.py - Local JSON store
database/json_store.py
Platform services
- Event processor
websocket/event_processor.py - Files and artifacts
services/file_service.py - Chat history
services/chat_history_service.py - ADK memory
memory_management/adk_base_memory/service.py - Tracing
observability/tracing.py
Other components
- User
- Remote agents
Connections 25
- User → WebSocket handler: sends turn
- User → REST routes: uses API
- FastAPI app → WebSocket handler: routes WebSocket
main.py - WebSocket handler → Session manager: ensures session
websocket/websocket_handler.py - WebSocket handler → Root agent: runs turn
websocket/websocket_handler.py - Root agent → HITL callbacks: uses callbacks
agents/agent.py - WebSocket handler → Plan service: requests plan
websocket/websocket_handler.py - WebSocket handler → Plan execution: executes plan
websocket/websocket_handler.py - Plan service → Context broker: gets task context
- Plan execution → Orchestration state: reads and writes
services/plan_execution_service.py - FastAPI app → Agent loader: loads active agents
main.py - Agent loader → Agent registry: loads capabilities
services/agent_loader.py - Health monitor → PostgreSQL store: updates health
agent_registry/health_monitor.py - Agent loader → Remote agents: discovers agents
services/agent_loader.py - Agent execution → A2A runtime: delegates invocation
- A2A runtime → Remote agents: sends A2A requests
- WebSocket handler → Event processor: processes events
websocket/websocket_handler.py - REST routes → Chat history: serves history
routers/history_router.py - REST routes → Files and artifacts: handles uploads
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
services/chat_history_service.py - Chat history → Local JSON store: uses local backend
services/chat_history_service.py - WebSocket handler → Tracing: traces turns
- FastAPI app → PostgreSQL store: configures persistence