# pogjester/company-research-agent architecture

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

- Interactive diagram: https://gitdiagram.com/pogjester/company-research-agent
- Repository: https://github.com/pogjester/company-research-agent

## Overview

##### Project Type and Purpose
- This is a full-stack web application—a multi-agent AI research platform that gathers, filters, and compiles company research into a structured report.
- Frontend: React (Vite + TypeScript + Tailwind) for real-time UI and progress streaming.
- Backend: Python FastAPI orchestrating a pipeline of specialized “nodes” (researchers, collector, curator, briefing, editor).
- External services: Tavily AI search, Google Gemini API, OpenAI API, (optional) MongoDB persistence.

##### File Structure
- Top-level:
- application.py / langgraph_entry.py — FastAPI entrypoints.
- backend/ — business logic:
– classes/ (state, graph orchestration)
– nodes/ (researcher nodes, processing nodes: collector, curator, briefing, editor)
– services/ (mongodb connector, PDF generator, WebSocket manager)
– utils/ (reference handling, general helpers)
- ui/ — React app: src/components, styles, utils, Vite config, .env examples.
- docker-compose.yml, Dockerfile — containerized deployment for both backend and frontend.
- Key config: requirements.txt, package-lock.json, docker-compose.yml.

##### README Insights
- Agentic pipeline: CompanyAnalyzer, IndustryAnalyzer, FinancialAnalyst, NewsScanner → Collector → Curator → Briefing (Gemini 2.0 Flash) → Editor (GPT-4.1-mini).
- Real-time streaming via WebSocketManager in backend/services.
- Dual-model approach for context-heavy vs precision formatting.
- Optional MongoDB for job persistence.

## Diagram (Mermaid)

```mermaid
flowchart TD
    direction TB

    subgraph "Docker Compose"
        direction TB
        subgraph "Frontend Service (5174)"
            direction TB
            Browser["Browser"]:::frontend
            UI["React UI"]:::frontend
            PKG["package.json"]:::service
            VITE["vite.config.ts"]:::service
            ENV[".env.development.example"]:::service
        end

        subgraph "Backend Service (8000)"
            direction TB
            API["FastAPI API"]:::backend
            ENTRY["langgraph_entry.py"]:::backend
            APP["application.py"]:::backend
            WS["WebSocket Manager"]:::service
            MDB["MongoDB"]:::db
            PDF["PDF Service"]:::service

            subgraph "State & Orchestration"
                direction TB
                State["State Graph"]:::backend
                Graph["Pipeline Orchestrator"]:::service
            end

            subgraph "Pipeline Agents"
                direction TB
                A1["CompanyAnalyzer"]:::node
                A2["IndustryAnalyzer"]:::node
                A3["FinancialAnalyst"]:::node
                A4["NewsScanner"]:::node
                Coll["Collector"]:::node
                Cur["Curator"]:::node
                Brf["Briefing"]:::node
                Edt["Editor"]:::node
                Enr["Enricher"]:::node
                Grd["Grounding"]:::node
            end

            subgraph "Utilities"
                direction TB
                UT1["utils.py"]:::backend
                UT2["references.py"]:::backend
            end
        end

        subgraph "Configs"
            direction TB
            CFG1["Dockerfile"]:::service
            CFG2["docker-compose.yml"]:::service
            CFG3["requirements.txt"]:::service
            CFG4["package-lock.json"]:::service
        end
    end

    subgraph "External AI Services"
        direction TB
        Tavily["Tavily AI Search"]:::external
        Gemini["Google Gemini API"]:::external
        OpenAI["OpenAI API"]:::external
    end

    %% Connections
    Browser -->|uses| UI
    UI -->|HTTP POST /research| API
    UI -->|WS connect| WS
    API -->|enqueue job| State
    State -->|update graph| Graph
    Graph --> A1
    Graph --> A2
    Graph --> A3
    Graph --> A4
    A1 -->|research data| Coll
    A2 -->|research data| Coll
    A3 -->|research data| Coll
    A4 -->|research data| Coll
    Coll -->|docs| Cur
    Cur -->|filtered docs| Brf
    Brf -->|summaries| Edt
    Edt -->|final markdown| API
    API -->|persist| MDB
    API -->|request PDF| PDF

    A1 -->|calls| Tavily
    A2 -->|calls| Tavily
    A3 -->|calls| Tavily
    A4 -->|calls| Tavily
    Brf -->|calls| Gemini
    Edt -->|calls| OpenAI

    Cur -.->|stream document_kept| WS
    Brf -.->|stream briefing_start| WS
    Edt -.->|stream report_chunk| WS

    %% Click Events
    click UI "https://github.com/pogjester/company-research-agent/tree/main/ui/"
    click PKG "https://github.com/pogjester/company-research-agent/blob/main/ui/package.json"
    click VITE "https://github.com/pogjester/company-research-agent/blob/main/ui/vite.config.ts"
    click ENV "https://github.com/pogjester/company-research-agent/blob/main/ui/.env.development.example"
    click ENTRY "https://github.com/pogjester/company-research-agent/blob/main/langgraph_entry.py"
    click APP "https://github.com/pogjester/company-research-agent/blob/main/application.py"
    click Graph "https://github.com/pogjester/company-research-agent/blob/main/backend/graph.py"
    click State "https://github.com/pogjester/company-research-agent/blob/main/backend/classes/state.py"
    click A1 "https://github.com/pogjester/company-research-agent/blob/main/backend/nodes/researchers/company.py"
    click A2 "https://github.com/pogjester/company-research-agent/blob/main/backend/nodes/researchers/industry.py"
    click A3 "https://github.com/pogjester/company-research-agent/blob/main/backend/nodes/researchers/financial.py"
    click A4 "https://github.com/pogjester/company-research-agent/blob/main/backend/nodes/researchers/news.py"
    click Coll "https://github.com/pogjester/company-research-agent/blob/main/backend/nodes/collector.py"
    click Cur "https://github.com/pogjester/company-research-agent/blob/main/backend/nodes/curator.py"
    click Brf "https://github.com/pogjester/company-research-agent/blob/main/backend/nodes/briefing.py"
    click Edt "https://github.com/pogjester/company-research-agent/blob/main/backend/nodes/editor.py"
    click Enr "https://github.com/pogjester/company-research-agent/blob/main/backend/nodes/enricher.py"
    click Grd "https://github.com/pogjester/company-research-agent/blob/main/backend/nodes/grounding.py"
    click MDB "https://github.com/pogjester/company-research-agent/blob/main/backend/services/mongodb.py"
    click PDF "https://github.com/pogjester/company-research-agent/blob/main/backend/services/pdf_service.py"
    click WS "https://github.com/pogjester/company-research-agent/blob/main/backend/services/websocket_manager.py"
    click UT1 "https://github.com/pogjester/company-research-agent/blob/main/backend/utils/utils.py"
    click UT2 "https://github.com/pogjester/company-research-agent/blob/main/backend/utils/references.py"
    click CFG1 "https://github.com/pogjester/company-research-agent/tree/main/Dockerfile"
    click CFG2 "https://github.com/pogjester/company-research-agent/blob/main/docker-compose.yml"
    click CFG3 "https://github.com/pogjester/company-research-agent/blob/main/requirements.txt"
    click CFG4 "https://github.com/pogjester/company-research-agent/blob/main/package-lock.json"

    %% Styles
    classDef frontend fill:#E8F1FA,stroke:#005B96,color:#005B96
    classDef backend fill:#F0F0F0,stroke:#333, color:#333
    classDef service fill:#FFF4E5,stroke:#D9822B,color:#D9822B
    classDef node fill:#E5F7E0,stroke:#28A745,color:#28A745
    classDef db fill:#E5E5FF,stroke:#5555FF,color:#5555FF
    classDef external fill:#FDECEF,stroke:#D93025,color:#D93025
```
