# mihirkothari04/ai-newsroom-team architecture

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

- Interactive diagram: https://gitdiagram.com/mihirkothari04/ai-newsroom-team
- Repository: https://github.com/mihirkothari04/ai-newsroom-team

## Overview

##### Project Type and Purpose
- This is a backend‐only, multi-agent orchestration system written in Python.
- Purpose: automate the end-to-end workflow of “newsroom” tasks—gathering, writing, fact-checking, and optionally editing—by coordinating specialized AI agents via a message‐passing architecture.

##### File Structure Analysis
- src/agents: implementations of GatherBot, WriterBot, FactCheckBot (+ optional EditorBot).
- src/messaging: the central MessageBus, message definitions, and integration helpers.
- src/orchestrator: NewsroomOrchestrator and its StateManager, which kick off tasks and track progress.
- src/tools: external-integration clients (LLM, News API, web scraper).
- docs/: design and usage docs (API, deployment, examples).
- tests/: unit, integration, and end-to-end workflow tests.
- demo.sh, requirements.txt, todo.md, README.md.

##### Core Architectural Pattern
- Message-passing / Publish-Subscribe model.
- Orchestrator publishes “new task” messages → Agents subscribe, process, and publish result messages → Orchestrator/state manager collates outputs.

##### Main Components
a. Orchestrator
- “NewsroomOrchestrator” + “StateManager”
- Role: Accepts client API calls, creates tasks, publishes initial messages, monitors completion.
b. Message Bus
- Central pub/sub broker implemented in src/messaging/message_bus.py
- Handles topic registration, message routing, and delivery guarantees.
c. Agents
- GatherBot
- WriterBot
- FactCheckBot
- (Optional) EditorBot
- Each: subscribes to specific message types, processes payloads, uses tools, publishes results.
d. Tools / External Services
- LLM Client (e.g., OpenAI)
- News API (e.g., newsapi.org)
- Web scraper (custom or third-party)
- These are invoked by agents to fetch or generate content.
e. Clients / Consumers
- CLI/demo script (demo.sh) or any external client that invokes the orchestrator API.
f. Data Persistence (optional)
- StateManager may persist to file, in-memory store, or database (if extended).
- For now: shown as in-memory within StateManager.

##### Relationships and Data Flow
- External Client → Orchestrator.create_task() → Orchestrator publishes “TaskCreated” message to MessageBus.
- GatherBot listens for “TaskCreated” → uses News API + WebScraper → publishes “GatherComplete” with structured data.
- WriterBot listens for “GatherComplete” → uses LLM Client → publishes “WriteComplete” with draft article.
- FactCheckBot listens for “WriteComplete” → uses News API + credibility logic → publishes “FactCheckComplete” with accuracy report.
- (Optional) EditorBot listens for “FactCheckComplete” → publishes “EditComplete”.
- Orchestrator/state manager listens for final completion messages → aggregates results → client polls Orchestrator.get_task_results().

##### Key Architectural Patterns and Principles
- Loose coupling via MessageBus (publish/subscribe)
- Single Responsibility: each agent handles a discrete phase
- Extensibility: plug in new agents by subscribing to message types
- Asynchronous workflow enabling parallelism

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Client
    subgraph "External Client" 
        CLI["CLI / demo.sh"]:::external
    end

    %% Orchestrator Layer
    subgraph "Orchestrator Layer"
        ORC["NewsroomOrchestrator\n(src/orchestrator/orchestrator.py)"]:::orchestrator
        SM["StateManager\n(src/orchestrator/state_manager.py)"]:::orchestrator
    end

    %% Infrastructure
    subgraph "Messaging Infrastructure"
        MB["MessageBus\n(src/messaging/message_bus.py)"]:::infra
        MD["Message Definitions\n(src/messaging/message.py)"]:::infra
        MI["Agent Integration\n(src/messaging/agent_integration.py)"]:::infra
    end

    %% Agents
    subgraph "Agents"
        GB["GatherBot\n(src/agents/gatherbot/gatherbot.py)"]:::agent
        WB["WriterBot\n(src/agents/writerbot/writerbot.py)"]:::agent
        FB["FactCheckBot\n(src/agents/factcheckbot/factcheckbot.py)"]:::agent
        EB["EditorBot\nOptional"]:::agent
    end

    %% Tools
    subgraph "Tools / External Services"
        LLM["LLM Client\n(src/tools/llm_client.py)"]:::tool
        API["News API\n(src/tools/news_api.py)"]:::tool
        SCR["Web Scraper\n(src/tools/web_scraper.py)"]:::tool
    end

    %% Documentation & Tests
    subgraph "Documentation"
        DOC1["API Doc\n(docs/api_documentation.md)"]:::docs
        DOC2["Deployment Guide\n(docs/deployment_guide.md)"]:::docs
        DOC3["Usage Examples\n(docs/usage_examples.md)"]:::docs
        README["README.md"]:::docs
    end

    subgraph "Tests"
        UT["Unit Tests\n(tests/unit_tests.py)"]:::test
        IT["Integration Tests\n(tests/integration_tests.py)"]:::test
        E2E["E2E Tests\n(tests/workflow_test.py)"]:::test
    end

    %% Connections
    CLI -->|"create_task()"| ORC
    ORC -->|"publish TaskCreated"| MB
    MB -->|"TaskCreated"| GB
    GB -->|"invoke"| API
    GB -->|"invoke"| SCR
    GB -->|"publish GatherComplete"| MB
    MB -->|"GatherComplete"| WB
    WB -->|"invoke"| LLM
    WB -->|"publish WriteComplete"| MB
    MB -->|"WriteComplete"| FB
    FB -->|"invoke"| API
    FB -->|"publish FactCheckComplete"| MB
    MB -->|"FactCheckComplete"| EB
    EB -.->|"publish EditComplete"| MB
    MB -->|"final events"| SM
    SM -->|"aggregates"| ORC
    ORC -->|"get_task_results()"| CLI

    %% Click Events
    click ORC "https://github.com/mihirkothari04/ai-newsroom-team/blob/main/src/orchestrator/orchestrator.py"
    click SM "https://github.com/mihirkothari04/ai-newsroom-team/blob/main/src/orchestrator/state_manager.py"
    click MB "https://github.com/mihirkothari04/ai-newsroom-team/blob/main/src/messaging/message_bus.py"
    click MD "https://github.com/mihirkothari04/ai-newsroom-team/blob/main/src/messaging/message.py"
    click MI "https://github.com/mihirkothari04/ai-newsroom-team/blob/main/src/messaging/agent_integration.py"
    click GB "https://github.com/mihirkothari04/ai-newsroom-team/blob/main/src/agents/gatherbot/gatherbot.py"
    click WB "https://github.com/mihirkothari04/ai-newsroom-team/blob/main/src/agents/writerbot/writerbot.py"
    click FB "https://github.com/mihirkothari04/ai-newsroom-team/blob/main/src/agents/factcheckbot/factcheckbot.py"
    click LLM "https://github.com/mihirkothari04/ai-newsroom-team/blob/main/src/tools/llm_client.py"
    click API "https://github.com/mihirkothari04/ai-newsroom-team/blob/main/src/tools/news_api.py"
    click SCR "https://github.com/mihirkothari04/ai-newsroom-team/blob/main/src/tools/web_scraper.py"
    click CLI "https://github.com/mihirkothari04/ai-newsroom-team/blob/main/demo.sh"
    click DOC1 "https://github.com/mihirkothari04/ai-newsroom-team/blob/main/docs/api_documentation.md"
    click DOC2 "https://github.com/mihirkothari04/ai-newsroom-team/blob/main/docs/deployment_guide.md"
    click DOC3 "https://github.com/mihirkothari04/ai-newsroom-team/blob/main/docs/usage_examples.md"
    click README "https://github.com/mihirkothari04/ai-newsroom-team/blob/main/README.md"
    click UT "https://github.com/mihirkothari04/ai-newsroom-team/blob/main/tests/unit_tests.py"
    click IT "https://github.com/mihirkothari04/ai-newsroom-team/blob/main/tests/integration_tests.py"
    click E2E "https://github.com/mihirkothari04/ai-newsroom-team/blob/main/tests/workflow_test.py"

    %% Styles
    classDef orchestrator fill:#cfe2f3,stroke:#6c8ebf,stroke-width:2px
    classDef infra fill:#fde9d9,stroke:#df9000,stroke-width:2px
    classDef agent fill:#d9ead3,stroke:#6aa84f,stroke-width:2px
    classDef tool fill:#ead1dc,stroke:#a64d79,stroke-width:2px
    classDef external fill:#eeeeee,stroke:#666666,stroke-width:1px
    classDef docs fill:#f3f3f3,stroke:#999999,stroke-width:1px,stroke-dasharray: 5 5
    classDef test fill:#f9e79f,stroke:#b7950b,stroke-width:1px,stroke-dasharray: 5 5
```
