# namangoyal88/multi-agent-team architecture

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

- Interactive diagram: https://gitdiagram.com/namangoyal88/multi-agent-team
- Repository: https://github.com/namangoyal88/multi-agent-team

## Overview

This local-first research application turns a question into a planned, evidence-backed research package. A Streamlit user submits and monitors a job through the API; the workflow asks the NVIDIA-backed Director to plan optional stages, retrieves literature and invokes Groq specialists, optionally runs a restricted experiment, then performs mandatory verification, reporting, and evaluation with optional evidence refinement. SQLite-backed workspace and memory retain job data and prior research. The README documents the major stages and integrations; some wiring is inferred from that description because workflow and API excerpts are partial.

Main entry points: [`research_team/workflow.py`](https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/workflow.py) (LangGraph workflow), [`research_team/workspace.py`](https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/workspace.py) (Research workspace), [`research_team/api.py`](https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/api.py) (Research API), [`frontend/api_client.py`](https://github.com/namangoyal88/multi-agent-team/blob/main/frontend/api_client.py) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_dashboard["Research dashboard<br/>[streamlit_app.py]"]
  node_api_client["API client<br/>[api_client.py]"]
end

subgraph group_orchestration["Job orchestration"]
  node_api["Research API<br/>[api.py]"]
  node_jobs["Job management<br/>[jobs.py]"]
  node_services["Service wiring<br/>[services.py]"]
  node_workflow["LangGraph workflow<br/>[workflow.py]"]
end

subgraph group_research["Research execution"]
  node_director["Deep Research Director<br/>[deep_director.py]"]
  node_specialists["Specialist runner<br/>[runner.py]"]
  node_literature["Literature retrieval<br/>[toolkit.py]"]
  node_tool_adapters["Search adapters<br/>[adapters.py]"]
  node_experiments["Experiment sandbox<br/>[sandbox.py]"]
end

subgraph group_evidence["Evidence and storage"]
  node_verification["Claim verification<br/>[verification.py]"]
  node_reporting["Report and evaluation<br/>[reporting.py]"]
  node_workspace["Research workspace<br/>[workspace.py]"]
  node_memory["Research memory<br/>[memory.py]"]
  node_sqlite[("SQLite database<br/>[research_team.db]")]
end

subgraph group_providers["Models and tools"]
  node_router["Model router<br/>[router.py]"]
  node_llm_client["Chat client<br/>[client.py]"]
end

node_user(("Research user"))
node_nvidia{{"NVIDIA model service"}}
node_groq{{"Groq model service"}}
node_research_sources{{"Research source APIs"}}

node_user -->|"submits question"| node_dashboard
node_dashboard -->|"requests research"| node_api_client
node_api_client -->|"calls endpoints"| node_api
node_api -->|"manages jobs"| node_jobs
node_jobs -->|"runs workflow"| node_workflow
node_api -->|"builds services"| node_services
node_workflow -->|"requests plan"| node_director
node_workflow -->|"retrieves evidence"| node_literature
node_literature -->|"dispatches searches"| node_tool_adapters
node_tool_adapters -->|"queries sources"| node_research_sources
node_workflow -->|"runs stages"| node_specialists
node_specialists -->|"requests model call"| node_router
node_director -->|"plans and delegates"| node_nvidia
node_director -->|"uses search tools"| node_literature
node_router -->|"routes calls"| node_llm_client
node_llm_client -->|"sends chat requests"| node_groq
node_llm_client -->|"sends chat requests"| node_nvidia
node_specialists -->|"records agent runs"| node_workspace
node_workflow -.->|"runs optional experiments"| node_experiments
node_workflow -->|"verifies claims"| node_verification
node_workflow -->|"generates report and evaluation"| node_reporting
node_workflow -->|"stores job artifacts"| node_workspace
node_workflow -->|"recalls and updates"| node_memory
node_workspace -->|"reads and writes"| node_sqlite
node_memory -->|"uses persistence"| node_workspace
node_verification -->|"reads papers"| node_workspace
node_reporting -->|"uses research results"| node_workspace
node_api -->|"serves research data"| node_workspace
node_api_client -->|"fetches run views"| node_api

click node_dashboard "https://github.com/namangoyal88/multi-agent-team/blob/main/frontend/streamlit_app.py"
click node_api_client "https://github.com/namangoyal88/multi-agent-team/blob/main/frontend/api_client.py"
click node_api "https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/api.py"
click node_jobs "https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/jobs.py"
click node_services "https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/services.py"
click node_workflow "https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/workflow.py"
click node_director "https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/agents/deep_director.py"
click node_specialists "https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/agents/runner.py"
click node_literature "https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/tools/toolkit.py"
click node_tool_adapters "https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/tools/adapters.py"
click node_experiments "https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/experiments/sandbox.py"
click node_verification "https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/verification.py"
click node_reporting "https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/reporting.py"
click node_workspace "https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/workspace.py"
click node_memory "https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/memory.py"
click node_sqlite "https://github.com/namangoyal88/multi-agent-team/blob/main/data/research_team.db"
click node_router "https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/llm/router.py"
click node_llm_client "https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/llm/client.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_dashboard,node_api_client,node_user toneBlue
class node_api,node_jobs,node_services,node_workflow toneAmber
class node_director,node_specialists,node_literature,node_tool_adapters,node_experiments,node_research_sources toneMint
class node_verification,node_reporting,node_workspace,node_memory,node_sqlite toneRose
class node_router,node_llm_client,node_nvidia,node_groq toneIndigo
```

## Components

### User interface

- [Research dashboard](https://github.com/namangoyal88/multi-agent-team/blob/main/frontend/streamlit_app.py): `frontend/streamlit_app.py`
- [API client](https://github.com/namangoyal88/multi-agent-team/blob/main/frontend/api_client.py): `frontend/api_client.py`

### Job orchestration

- [Research API](https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/api.py): `research_team/api.py`
- [Job management](https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/jobs.py): `research_team/jobs.py`
- [Service wiring](https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/services.py): `research_team/services.py`
- [LangGraph workflow](https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/workflow.py): `research_team/workflow.py`

### Research execution

- [Deep Research Director](https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/agents/deep_director.py): `research_team/agents/deep_director.py`
- [Specialist runner](https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/agents/runner.py): `research_team/agents/runner.py`
- [Literature retrieval](https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/tools/toolkit.py): `research_team/tools/toolkit.py`
- [Search adapters](https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/tools/adapters.py): `research_team/tools/adapters.py`
- [Experiment sandbox](https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/experiments/sandbox.py): `research_team/experiments/sandbox.py`

### Evidence and storage

- [Claim verification](https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/verification.py): `research_team/verification.py`
- [Report and evaluation](https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/reporting.py): `research_team/reporting.py`
- [Research workspace](https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/workspace.py): `research_team/workspace.py`
- [Research memory](https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/memory.py): `research_team/memory.py`
- [SQLite database](https://github.com/namangoyal88/multi-agent-team/blob/main/data/research_team.db): `data/research_team.db`

### Models and tools

- [Model router](https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/llm/router.py): `research_team/llm/router.py`
- [Chat client](https://github.com/namangoyal88/multi-agent-team/blob/main/research_team/llm/client.py): `research_team/llm/client.py`

### Other components

- **Research user**
- **NVIDIA model service**
- **Groq model service**
- **Research source APIs**

## Connections

- Research user → Research dashboard: submits question
- Research dashboard → API client: requests research
- API client → Research API: calls endpoints
- Research API → Job management: manages jobs
- Job management → LangGraph workflow: runs workflow
- Research API → Service wiring: builds services
- LangGraph workflow → Deep Research Director: requests plan
- LangGraph workflow → Literature retrieval: retrieves evidence
- Literature retrieval → Search adapters: dispatches searches
- Search adapters → Research source APIs: queries sources
- LangGraph workflow → Specialist runner: runs stages
- Specialist runner → Model router: requests model call
- Deep Research Director → NVIDIA model service: plans and delegates
- Deep Research Director → Literature retrieval: uses search tools
- Model router → Chat client: routes calls
- Chat client → Groq model service: sends chat requests
- Chat client → NVIDIA model service: sends chat requests
- Specialist runner → Research workspace: records agent runs
- LangGraph workflow → Experiment sandbox: runs optional experiments
- LangGraph workflow → Claim verification: verifies claims
- LangGraph workflow → Report and evaluation: generates report and evaluation
- LangGraph workflow → Research workspace: stores job artifacts
- LangGraph workflow → Research memory: recalls and updates
- Research workspace → SQLite database: reads and writes
- Research memory → Research workspace: uses persistence
- Claim verification → Research workspace: reads papers
- Report and evaluation → Research workspace: uses research results
- Research API → Research workspace: serves research data
- API client → Research API: fetches run views