# karan27q/ai-agents-orchestrator architecture

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

- Interactive diagram: https://gitdiagram.com/karan27q/ai-agents-orchestrator
- Repository: https://github.com/karan27q/ai-agents-orchestrator

## Overview

This is an AI workflow automation and multi-agent research platform. Users authenticate, then build and execute DAG workflows or request streamed research; they can also upload documents for embedding and semantic search. The graph preserves the documented workflow, research, RAG, authorization, tracking, and real-time capabilities. Several subsystems are represented from the README and source index rather than sampled implementation; those links are omitted where call ownership is not evidenced.

Main entry points: [`backend/main.py`](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/main.py) (FastAPI application), [`frontend/app.js`](https://github.com/karan27q/ai-agents-orchestrator/blob/main/frontend/app.js) (Web application), [`backend/models.py`](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/models.py) (Domain models), [`backend/workflow_engine.py`](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/workflow_engine.py) (DAG execution engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_webapp["Web application<br/>[app.js]"]
  node_authview["Sign-in view<br/>[auth.js]"]
  node_dashboard["Dashboard<br/>[dashboard.js]"]
  node_home["Home view<br/>[home.js]"]
  node_workflowui["Workflow editor<br/>[workflows.js]"]
  node_researchui["Research view<br/>[research.js]"]
  node_filesui["Files manager<br/>[files.js]"]
  node_searchui["Search view<br/>[search.js]"]
end

subgraph group_api["API and access"]
  node_api["FastAPI application<br/>[main.py]"]
  node_authroutes["Authentication routes<br/>[auth.py]"]
  node_auth["JWT and role access<br/>[auth.py]"]
  node_iamroutes["IAM routes<br/>[iam.py]"]
  node_iam["IAM services<br/>[iam.py]"]
end

subgraph group_automation["Workflow and agents"]
  node_workflowroutes["Workflow routes<br/>[workflows.py]"]
  node_engine["DAG execution engine<br/>[workflow_engine.py]"]
  node_agentroutes["Agent routes<br/>[agents.py]"]
  node_agents["Research agents<br/>[agents.py]"]
  node_cache["LLM cache<br/>[llm_cache.py]"]
  node_errors["Execution error handling<br/>[error_handler.py]"]
end

subgraph group_knowledge["Knowledge and search"]
  node_fileroutes["File routes<br/>[files.py]"]
  node_vectors["Vector store<br/>[vector_store.py]"]
  node_searchroutes["Search routes<br/>[search.py]"]
end

subgraph group_platform["Persistence and operations"]
  node_models["Domain models<br/>[models.py]"]
  node_database[("Relational database<br/>[database.py]")]
  node_queue["Task queue<br/>[task_queue.py]"]
  node_taskroutes["Task monitoring routes<br/>[tasks.py]"]
  node_notifications["Notification routes<br/>[notifications.py]"]
  node_wsroutes["WebSocket routes<br/>[ws.py]"]
  node_wsmanager["Connection manager<br/>[ws_manager.py]"]
  node_obsroutes["Observability routes<br/>[observability.py]"]
end

node_user(("Platform user"))
node_gemini["Google Gemini"]

node_user -->|"uses"| node_webapp
node_webapp -->|"renders"| node_authview
node_webapp -->|"renders"| node_dashboard
node_webapp -->|"renders"| node_home
node_webapp -->|"renders"| node_workflowui
node_webapp -->|"renders"| node_researchui
node_webapp -->|"renders"| node_filesui
node_webapp -->|"renders"| node_searchui
node_webapp -->|"calls API"| node_api
node_api -->|"registers"| node_authroutes
node_api -->|"registers"| node_workflowroutes
node_api -->|"registers"| node_agentroutes
node_api -->|"registers"| node_fileroutes
node_api -->|"registers"| node_searchroutes
node_api -->|"registers"| node_notifications
node_api -->|"registers"| node_wsroutes
node_api -->|"registers"| node_obsroutes
node_api -->|"registers"| node_taskroutes
node_api -->|"registers"| node_iamroutes
node_authroutes -->|"uses"| node_auth
node_iamroutes -->|"uses"| node_iam
node_workflowroutes -->|"executes"| node_engine
node_agentroutes -->|"invokes"| node_agents
node_agents -->|"uses"| node_cache
node_fileroutes -->|"indexes files"| node_vectors
node_fileroutes -->|"enqueues work"| node_queue
node_searchroutes -->|"searches vectors"| node_vectors
node_taskroutes -->|"queries tasks"| node_queue
node_notifications -->|"sends messages"| node_wsmanager
node_wsroutes -->|"manages sockets"| node_wsmanager
node_engine -->|"uses"| node_errors
node_auth -->|"queries users"| node_models
node_iam -->|"uses"| node_models
node_engine -->|"loads workflow"| node_models
node_vectors -->|"uses chunks"| node_models
node_queue -->|"stores task state"| node_models
node_authroutes -->|"opens session"| node_database
node_workflowroutes -->|"opens session"| node_database
node_database -->|"defines base"| node_models
node_engine -.->|"generates text"| node_gemini
node_agents -.->|"researches with"| node_gemini
node_researchui -.->|"requests research"| node_agentroutes

click node_webapp "https://github.com/karan27q/ai-agents-orchestrator/blob/main/frontend/app.js"
click node_authview "https://github.com/karan27q/ai-agents-orchestrator/blob/main/frontend/components/auth.js"
click node_dashboard "https://github.com/karan27q/ai-agents-orchestrator/blob/main/frontend/components/dashboard.js"
click node_home "https://github.com/karan27q/ai-agents-orchestrator/blob/main/frontend/components/home.js"
click node_workflowui "https://github.com/karan27q/ai-agents-orchestrator/blob/main/frontend/components/workflows.js"
click node_researchui "https://github.com/karan27q/ai-agents-orchestrator/blob/main/frontend/components/research.js"
click node_filesui "https://github.com/karan27q/ai-agents-orchestrator/blob/main/frontend/components/files.js"
click node_searchui "https://github.com/karan27q/ai-agents-orchestrator/blob/main/frontend/components/search.js"
click node_api "https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/main.py"
click node_authroutes "https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/routes/auth.py"
click node_auth "https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/auth.py"
click node_iamroutes "https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/routes/iam.py"
click node_iam "https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/iam.py"
click node_workflowroutes "https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/routes/workflows.py"
click node_engine "https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/workflow_engine.py"
click node_agentroutes "https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/routes/agents.py"
click node_agents "https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/agents.py"
click node_cache "https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/llm_cache.py"
click node_errors "https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/error_handler.py"
click node_fileroutes "https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/routes/files.py"
click node_vectors "https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/vector_store.py"
click node_searchroutes "https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/routes/search.py"
click node_models "https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/models.py"
click node_database "https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/database.py"
click node_queue "https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/task_queue.py"
click node_taskroutes "https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/routes/tasks.py"
click node_notifications "https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/routes/notifications.py"
click node_wsroutes "https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/routes/ws.py"
click node_wsmanager "https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/ws_manager.py"
click node_obsroutes "https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/routes/observability.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_webapp,node_authview,node_dashboard,node_home,node_workflowui,node_researchui,node_filesui,node_searchui,node_user toneBlue
class node_api,node_authroutes,node_auth,node_iamroutes,node_iam toneAmber
class node_workflowroutes,node_engine,node_agentroutes,node_agents,node_cache,node_errors toneMint
class node_fileroutes,node_vectors,node_searchroutes toneRose
class node_models,node_database,node_queue,node_taskroutes,node_notifications,node_wsroutes,node_wsmanager,node_obsroutes,node_gemini toneIndigo
```

## Components

### Web client

- [Web application](https://github.com/karan27q/ai-agents-orchestrator/blob/main/frontend/app.js): `frontend/app.js`
- [Sign-in view](https://github.com/karan27q/ai-agents-orchestrator/blob/main/frontend/components/auth.js): `frontend/components/auth.js`
- [Dashboard](https://github.com/karan27q/ai-agents-orchestrator/blob/main/frontend/components/dashboard.js): `frontend/components/dashboard.js`
- [Home view](https://github.com/karan27q/ai-agents-orchestrator/blob/main/frontend/components/home.js): `frontend/components/home.js`
- [Workflow editor](https://github.com/karan27q/ai-agents-orchestrator/blob/main/frontend/components/workflows.js): `frontend/components/workflows.js`
- [Research view](https://github.com/karan27q/ai-agents-orchestrator/blob/main/frontend/components/research.js): `frontend/components/research.js`
- [Files manager](https://github.com/karan27q/ai-agents-orchestrator/blob/main/frontend/components/files.js): `frontend/components/files.js`
- [Search view](https://github.com/karan27q/ai-agents-orchestrator/blob/main/frontend/components/search.js): `frontend/components/search.js`

### API and access

- [FastAPI application](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/main.py): `backend/main.py`
- [Authentication routes](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/routes/auth.py): `backend/routes/auth.py`
- [JWT and role access](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/auth.py): `backend/auth.py`
- [IAM routes](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/routes/iam.py): `backend/routes/iam.py`
- [IAM services](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/iam.py): `backend/iam.py`

### Workflow and agents

- [Workflow routes](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/routes/workflows.py): `backend/routes/workflows.py`
- [DAG execution engine](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/workflow_engine.py): `backend/workflow_engine.py`
- [Agent routes](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/routes/agents.py): `backend/routes/agents.py`
- [Research agents](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/agents.py): `backend/agents.py`
- [LLM cache](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/llm_cache.py): `backend/llm_cache.py`
- [Execution error handling](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/error_handler.py): `backend/error_handler.py`

### Knowledge and search

- [File routes](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/routes/files.py): `backend/routes/files.py`
- [Vector store](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/vector_store.py): `backend/vector_store.py`
- [Search routes](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/routes/search.py): `backend/routes/search.py`

### Persistence and operations

- [Domain models](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/models.py): `backend/models.py`
- [Relational database](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/database.py): `backend/database.py`
- [Task queue](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/task_queue.py): `backend/task_queue.py`
- [Task monitoring routes](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/routes/tasks.py): `backend/routes/tasks.py`
- [Notification routes](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/routes/notifications.py): `backend/routes/notifications.py`
- [WebSocket routes](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/routes/ws.py): `backend/routes/ws.py`
- [Connection manager](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/ws_manager.py): `backend/ws_manager.py`
- [Observability routes](https://github.com/karan27q/ai-agents-orchestrator/blob/main/backend/routes/observability.py): `backend/routes/observability.py`

### Other components

- **Platform user**
- **Google Gemini**

## Connections

- Platform user → Web application: uses (evidence: `README.md`)
- Web application → Sign-in view: renders (evidence: `frontend/app.js`)
- Web application → Dashboard: renders (evidence: `frontend/app.js`)
- Web application → Home view: renders (evidence: `frontend/app.js`)
- Web application → Workflow editor: renders (evidence: `frontend/app.js`)
- Web application → Research view: renders (evidence: `frontend/app.js`)
- Web application → Files manager: renders (evidence: `frontend/app.js`)
- Web application → Search view: renders (evidence: `frontend/app.js`)
- Web application → FastAPI application: calls API (evidence: `frontend/app.js`)
- FastAPI application → Authentication routes: registers (evidence: `backend/main.py`)
- FastAPI application → Workflow routes: registers (evidence: `backend/main.py`)
- FastAPI application → Agent routes: registers (evidence: `backend/main.py`)
- FastAPI application → File routes: registers (evidence: `backend/main.py`)
- FastAPI application → Search routes: registers (evidence: `backend/main.py`)
- FastAPI application → Notification routes: registers (evidence: `backend/main.py`)
- FastAPI application → WebSocket routes: registers (evidence: `backend/main.py`)
- FastAPI application → Observability routes: registers (evidence: `backend/main.py`)
- FastAPI application → Task monitoring routes: registers (evidence: `backend/main.py`)
- FastAPI application → IAM routes: registers (evidence: `backend/main.py`)
- Authentication routes → JWT and role access: uses (evidence: `backend/routes/auth.py`)
- IAM routes → IAM services: uses (evidence: `backend/routes/iam.py`)
- Workflow routes → DAG execution engine: executes (evidence: `backend/routes/workflows.py`)
- Agent routes → Research agents: invokes (evidence: `backend/routes/agents.py`)
- Research agents → LLM cache: uses (evidence: `backend/agents.py`)
- File routes → Vector store: indexes files (evidence: `backend/routes/files.py`)
- File routes → Task queue: enqueues work (evidence: `backend/routes/files.py`)
- Search routes → Vector store: searches vectors (evidence: `backend/routes/search.py`)
- Task monitoring routes → Task queue: queries tasks (evidence: `backend/routes/tasks.py`)
- Notification routes → Connection manager: sends messages (evidence: `backend/routes/notifications.py`)
- WebSocket routes → Connection manager: manages sockets (evidence: `backend/routes/ws.py`)
- DAG execution engine → Execution error handling: uses (evidence: `backend/workflow_engine.py`)
- JWT and role access → Domain models: queries users (evidence: `backend/auth.py`)
- IAM services → Domain models: uses (evidence: `backend/iam.py`)
- DAG execution engine → Domain models: loads workflow (evidence: `backend/workflow_engine.py`)
- Vector store → Domain models: uses chunks (evidence: `backend/vector_store.py`)
- Task queue → Domain models: stores task state (evidence: `backend/task_queue.py`)
- Authentication routes → Relational database: opens session (evidence: `backend/routes/auth.py`)
- Workflow routes → Relational database: opens session (evidence: `backend/routes/workflows.py`)
- Relational database → Domain models: defines base (evidence: `backend/database.py`)
- DAG execution engine → Google Gemini: generates text
- Research agents → Google Gemini: researches with
- Research view → Agent routes: requests research
