# todap/multiagent-research architecture

> Architecture diagram of the GitHub repository todap/multiagent-research, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/todap/multiagent-research
- Repository: https://github.com/todap/multiagent-research

## Overview

##### Project type and overall purpose
- This is a full-stack, single-process Python application with a Streamlit frontend and a LangChain/LangGraph-based backend orchestrator.
- Purpose: Provide an AI-driven “Company Research Assistant” that runs through multiple specialized AI agents to generate reports, interactive dashboards, and PDF exports.

##### File structure
- Top level:
- app1.py – Streamlit entry point and UI definitions
- workflow.py – LangGraph workflow orchestration code
- state.py – Shared data models (e.g., ResearchState, session info)
- Tools/ – Directory containing one Python file per AI “agent” (industryResearchTool.py, useCaseGeneratorTool.py, etc.)
- No separate “frontend”/“backend” folders, but app1.py contains UI logic, workflow.py + Tools/ contain backend logic.
- Presence of SQLite DB (via `sqlite3` in code), caching logic (24-hour validity), PDF export libs, Plotly for charts, and external API integration scripts.

##### Extract architecture details from the README
- Multi-Agent Workflow broken into seven specialized agents
- Streamlit handles UI, user auth, session management
- LangGraph orchestrates agents in workflow.py
- SQLite for user and cache persistence
- External services: OpenRouter/Local LM Studio for LLM; Tavily for web search
- Output channels: Streamlit charts (Plotly) and PDF reports (FPDF/ReportLab)

##### Main components
a. Frontend (Streamlit)
- UI Layers: Login/Register, Sidebar Navigation, Tabbed Results, Interactive Charts
- “Start Research” button → triggers backend
b. Session/Auth Layer
- Session manager with “Remember Me”
- SQLite user table + SHA-256 hashing
c. Workflow Orchestrator
- workflow.py orchestrating LangGraph graph
- Coordinates sequence of AI agents
d. AI Agent Modules (Tools/)
- IndustryResearchAgent
- UseCaseGeneratorAgent
- AIRecommendationAgent
- ResourceCollectorAgent
- CompetitorAnalysisAgent
- ImplementationPlanningAgent
- CostBenefitAgent
e. Data Storage & Caching
- SQLite database: user info, cached reports
- Cache validity logic (24h)
f. External Services
- OpenRouter API or Local LM Studio (LLM calls)
- Tavily API (web search for agent data)
g. Visualization & Reporting
- Plotly for in-UI charts
- FPDF/ReportLab for PDF export

##### Relationships and data flow
1. User clicks “Start Research” in Streamlit UI
2. UI passes parameters (company names, industry) to workflow orchestrator
3. workflow.py instantiates each agent in turn:
– Industry Research → LLM + Tavily → writes to state
– Use Case Generator → LLM → state
– … and so on for all agents
4. After each agent run, results appended to shared ResearchState
5. Results stored/cached in SQLite
6. Streamlit UI reads state to render interactive tabs and charts (Plotly)
7. On “Download PDF,” PDF exporter reads state and generates report

##### Architectural patterns & design principles
- Modular multi-agent pipeline (each tool is an independent module adhering to a common interface)
- Separation of concerns: UI vs. orchestration vs. agent implementations vs. persistence
- Cache-aside pattern for avoiding duplicate work
- Layered architecture: Presentation → Orchestration → Domain/Agents → External Dependencies → Persistence

- Rounded rectangles for UI components
- Rectangles for backend modules (orchestrator, agents)
- Clouds for external APIs
- User → UI → Orchestrator
- Orchestrator → Agent → External Service
- Agent → State/DB → UI
- UI → PDF Export

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        UI["Streamlit UI<br/>(Login/Register, Sidebar, Tabs, Charts)"]:::frontend
        Auth["Session/Auth Manager<br/>(Remember Me, SHA-256)"]:::frontend
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        Orchestrator["Workflow Orchestrator<br/>LangGraph (workflow.py)"]:::orchestrator
    end

    %% Multi-Agent Workflow
    subgraph "Multi-Agent Workflow"
        Industry["IndustryResearchAgent"]:::agent
        UseCase["UseCaseGeneratorAgent"]:::agent
        AIRec["AIRecommendationAgent"]:::agent
        Resource["ResourceCollectorAgent"]:::agent
        Competitor["CompetitorAnalysisAgent"]:::agent
        Implementation["ImplementationPlanningAgent"]:::agent
        CostBenefit["CostBenefitAgent"]:::agent
        WebSearch["Web Search Agent<br/>(Tavily)"]:::agent
    end

    %% Data Persistence
    subgraph "Data Persistence"
        State["Shared ResearchState<br/>(state.py)"]:::database
        DB["SQLite Database"]:::database
    end

    %% External Services
    subgraph "External Services"
        LLM["OpenRouter / Local LM Studio"]:::external
        Tavily["Tavily API"]:::external
    end

    %% Reporting
    subgraph "Reporting"
        Charts["Plotly Charts"]:::reporting
        PDF["PDF Exporter<br/>(FPDF/ReportLab)"]:::reporting
    end

    %% User interaction
    User[/"User"/] --> UI
    UI -->|"start_research"| Orchestrator
    UI -->|reads session| Auth

    %% Orchestration to Agents
    Orchestrator --> Industry
    Orchestrator --> UseCase
    Orchestrator --> AIRec
    Orchestrator --> Resource
    Orchestrator --> Competitor
    Orchestrator --> Implementation
    Orchestrator --> CostBenefit

    %% Agents interactions
    Industry -->|calls LLM| LLM
    Industry -->|calls Tavily| Tavily
    Industry -->|writes| State
    UseCase -->|calls LLM| LLM
    UseCase -->|writes| State
    AIRec -->|calls LLM| LLM
    AIRec -->|writes| State
    Resource -->|calls Tavily| Tavily
    Resource -->|writes| State
    Competitor -->|calls LLM| LLM
    Competitor -->|writes| State
    Implementation -->|calls LLM| LLM
    Implementation -->|writes| State
    CostBenefit -->|calls LLM| LLM
    CostBenefit -->|writes| State

    %% State and DB caching
    State -->|cache as needed| DB
    Orchestrator -->|reads/writes| State

    %% UI rendering
    UI -->|reads results| State
    UI --> Charts
    UI --> PDF
    PDF --> State

    %% Click Events
    click UI "https://github.com/todap/multiagent-research/blob/main/app1.py"
    click Auth "https://github.com/todap/multiagent-research/blob/main/state.py"
    click Orchestrator "https://github.com/todap/multiagent-research/blob/main/workflow.py"
    click Industry "https://github.com/todap/multiagent-research/blob/main/Tools/industryResearchTool.py"
    click UseCase "https://github.com/todap/multiagent-research/blob/main/Tools/useCaseGeneratorTool.py"
    click AIRec "https://github.com/todap/multiagent-research/blob/main/Tools/aiRecommendationTool.py"
    click Resource "https://github.com/todap/multiagent-research/blob/main/Tools/resourceCollectorTool.py"
    click Competitor "https://github.com/todap/multiagent-research/blob/main/Tools/competitorAnalysisTool.py"
    click Implementation "https://github.com/todap/multiagent-research/blob/main/Tools/implementationPlanningTool.py"
    click CostBenefit "https://github.com/todap/multiagent-research/blob/main/Tools/costBenefitTool.py"
    click WebSearch "https://github.com/todap/multiagent-research/blob/main/Tools/webSearchTool.py"

    %% Styles
    classDef frontend fill:#f9f,stroke:#333,stroke-width:1px
    classDef orchestrator fill:#bbf,stroke:#333,stroke-width:1px
    classDef agent fill:#bfb,stroke:#333,stroke-width:1px
    classDef database fill:#fbf,stroke:#333,stroke-width:1px
    classDef external fill:#ffb,stroke:#333,stroke-width:1px
    classDef reporting fill:#fbb,stroke:#333,stroke-width:1px
```
