# devgomesai/ollama-cloud-crewai-research-assistant architecture

> Architecture diagram of the GitHub repository devgomesai/ollama-cloud-crewai-research-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/devgomesai/ollama-cloud-crewai-research-assistant
- Repository: https://github.com/devgomesai/ollama-cloud-crewai-research-assistant

## Overview

##### Project Type and Purpose
- This is a “full-stack” AI research assistant with a primary CLI interface and an optional HTTP API layer (“FastAPI”) for future extensions.
- It orchestrates a multi-agent workflow (Research Agent → Reporting Agent) via CrewAI, executing local LLM calls through Ollama and auxiliary web-scraping tools, then outputs timestamped Markdown reports.

##### Main Components
a. User Interfaces
- CLI (Rich-powered terminal UI)
- Optional HTTP API (FastAPI endpoint in src/api/api.py)
b. Orchestrator
- CrewAI engine (ResearchCrew in src/agent/src/agent/crew.py)
c. Agents
- Research Agent: gathers data using search/browsing tools
- Reporting Analyst Agent: synthesizes findings into markdown
d. Tools Layer
- DuckDuckGo Search, Website Browser (requests + BeautifulSoup), Current Time tool (src/agent/src/agent/tools/tools.py)
e. LLM Service
- Local Ollama server (configured by BASE_URL in .env)
f. Configuration
- YAML files in src/agent/src/agent/config/agents.yaml & tasks.yaml
- Pydantic settings (env vars in .env)
g. Persistence & Output
- Markdown reports in output/ (timestamp-named files)
- HTML template placeholder in src/templates/index.html

##### Relationships & Data Flow
- User → (CLI or HTTP API) → CrewAI Orchestrator → Agents (in sequence) → Tools Layer & Ollama → Agent outputs → Orchestrator → “output/” storage + CLI/API response
- Config files feed into Orchestrator at startup (agent roles, tasks)

##### Architectural Patterns & Principles
- Modular multi-agent pipeline (separation of concerns)
- Dependency injection of tools & LLM endpoint via configuration
- Clear separation between UI, orchestration logic, agent implementations, tools, external integrations, and data persistence

##### Technologies & Frameworks to Annotate
- Python 3.13 runtime
- CrewAI (agent orchestration)
- Ollama (local LLM execution)
- Rich (CLI UI)
- FastAPI (HTTP API)
- Pydantic (config management)
- Requests + BeautifulSoup (web scraping)
- LangChain (LLM utilities)

##### Elements
- Clear labels on all components
- Notes on config inputs (YAML, .env) feeding into Orchestrator

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers as subgraphs
    subgraph "User Interface" 
        direction TB
        CLI["CLI (Rich UI)"]:::ui
        HTTP_API["HTTP API (FastAPI)"]:::ui
    end

    subgraph "Orchestration Layer"
        direction TB
        Orchestrator["ResearchCrew Orchestrator\n(src/agent/src/agent/crew.py)"]:::logic
    end

    subgraph "Agents Layer"
        direction TB
        ResearchAgent["Research Agent"]:::logic
        ReportingAgent["Reporting Analyst Agent"]:::logic
    end

    subgraph "Tools Layer"
        direction TB
        Tools["Tools Layer\n(src/agent/src/agent/tools/tools.py)"]:::tool
    end

    subgraph "LLM Service"
        direction TB
        Ollama["Ollama LLM Service"]:::external
    end

    subgraph "External Services"
        direction TB
        DuckDuckGo["DuckDuckGo Search"]:::external
        Websites["Website Browser"]:::external
    end

    subgraph "Configuration"
        direction TB
        AgentsConfig["agents.yaml"]:::config
        TasksConfig["tasks.yaml"]:::config
        EnvFile[".env"]:::config
    end

    subgraph "Persistence & Output"
        direction TB
        Output["Markdown Reports\n(output/)"]:::storage
        HTMLTemplate["HTML Template\n(src/templates/index.html)"]:::storage
    end

    subgraph "Tests"
        direction TB
        Tests["Test Suite\n(src/tests/test.py)"]:::misc
    end

    %% Connections
    CLI -->|"start workflow"| Orchestrator
    HTTP_API -->|"start workflow"| Orchestrator

    AgentsConfig -.->|"load agent roles"| Orchestrator
    TasksConfig -.->|"load tasks"| Orchestrator
    EnvFile -.->|"load BASE_URL"| Orchestrator

    Orchestrator -->|"invoke ResearchAgent"| ResearchAgent
    ResearchAgent -->|"use tools / LLM"| Tools
    ResearchAgent -->|"use tools / LLM"| Ollama

    Tools -->|"HTTP search queries"| DuckDuckGo
    Tools -->|"HTTP requests"| Websites

    ReportingAgent -->|"synthesize markdown"| Orchestrator

    Orchestrator -->|"write report"| Output
    Orchestrator -->|"serve response"| CLI
    Orchestrator -->|"serve response"| HTTP_API

    %% Legend (as notes)
    classDef ui fill:#D0E8FF,stroke:#1E70BF,color:#000;
    classDef logic fill:#DFFFD0,stroke:#5BA829,color:#000;
    classDef tool fill:#FFE8B0,stroke:#DB9E00,color:#000;
    classDef external fill:#F0F0F0,stroke:#888888,color:#000;
    classDef storage fill:#FFF4B8,stroke:#E1A300,color:#000;
    classDef config fill:#E8D0FF,stroke:#8B2EB8,color:#000;
    classDef misc fill:#F8D0D0,stroke:#E02E2E,color:#000;

    %% Click events
    click HTTP_API "https://github.com/devgomesai/ollama-cloud-crewai-research-assistant/blob/main/src/api/api.py"
    click Orchestrator "https://github.com/devgomesai/ollama-cloud-crewai-research-assistant/blob/main/src/agent/src/agent/crew.py"
    click AgentsConfig "https://github.com/devgomesai/ollama-cloud-crewai-research-assistant/blob/main/src/agent/src/agent/config/agents.yaml"
    click TasksConfig "https://github.com/devgomesai/ollama-cloud-crewai-research-assistant/blob/main/src/agent/src/agent/config/tasks.yaml"
    click Tools "https://github.com/devgomesai/ollama-cloud-crewai-research-assistant/blob/main/src/agent/src/agent/tools/tools.py"
    click EnvFile "https://github.com/devgomesai/ollama-cloud-crewai-research-assistant/blob/main/.env"
    click Output "https://github.com/devgomesai/ollama-cloud-crewai-research-assistant/tree/main/output/"
    click HTMLTemplate "https://github.com/devgomesai/ollama-cloud-crewai-research-assistant/blob/main/src/templates/index.html"
    click Tests "https://github.com/devgomesai/ollama-cloud-crewai-research-assistant/blob/main/src/tests/test.py"
```
