# oatmeal-farm-network/ag-agent architecture

> Architecture diagram of the GitHub repository oatmeal-farm-network/ag-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oatmeal-farm-network/ag-agent
- Repository: https://github.com/oatmeal-farm-network/ag-agent

## Overview

##### Project Type and Purpose
- Full-stack conversational AI chatbot for agricultural advice.
- Python backend orchestrating a multi-agent pipeline (Microsoft AutoGen + Azure OpenAI).
- React-based frontend served via Nginx.
- Persistent storage in Azure Cosmos DB.
- Integrations with external weather API.

##### File Structure
Top-level directories and roles:
- frontend/ – React SPA + Nginx.
- autogen_module/ – Definitions of AI agents and coordination logic.
- database_module/ – Cosmos DB access (retrievers, storage helpers).
- external_apis/ – Wrappers (e.g., weather_api.py).
- utilities_module/ – Shared utilities (audio, embeddings, blob).
- Backend entrypoint: backend.py + config.py (loads env, wiring).
- Dockerfile, docker-compose.yml – container definitions.

##### Key Insights from README
- Multi-agent pipeline: Expert Advisor, User Proxy, others.
- Azure OpenAI for LLM calls.
- Cosmos DB for data persistence.
- Streamlit mention in README is outdated; actual UI is React + Nginx.
- Containerized deployment.

##### Main Components & Their Interactions
A. Frontend
- React SPA (frontend/src)
- Served by Nginx (frontend/Dockerfile, nginx.conf)
- Communicates via HTTP(S) to Backend API.
B. Backend Service
- backend.py: HTTP API endpoints (e.g., /chat)
- config.py: environment variable loader
- Autogen Orchestrator (autogen_module/): spawns and coordinates AI agents
– agents.py, routeagents.py, people_tool.py, userdata_agent.py
- External API Client (external_apis/weather_api.py)
- Database Layer (database_module/): cosmos_retriever, database_tools
- Utility Layer (utilities_module/): embeddings, audio, blob storage, session storage
C. External Services
- Azure OpenAI (chat + embeddings)
- Azure Cosmos DB
- Open-Meteo (via external_apis/weather_api.py)
D. Infrastructure
- Docker containers: frontend, backend
- docker-compose.yml defines multi-container local setup
- .env for secrets injection

##### Architectural Patterns
- Monolithic backend with layered modules (Orchestration, Data Access, Utilities).
- Multi-agent workflow (chain-of-thought style).
- Clear separation of concerns: UI / API / Business logic / Persistence / External Integrations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Infrastructure Orchestration
    DockerCompose["docker-compose.yml"]:::infra
    DockerCompose -->|spins up| FrontendContainer
    DockerCompose -->|spins up| BackendContainer

    %% Frontend Container
    subgraph "Frontend Container"
        direction TB
        Nginx["Nginx Server"]:::internal
        ReactSPA["React SPA"]:::internal
    end
    click FrontendContainer "https://github.com/oatmeal-farm-network/ag-agent/tree/main/frontend/"
    click Nginx "https://github.com/oatmeal-farm-network/ag-agent/blob/main/frontend/nginx.conf"
    click ReactSPA "https://github.com/oatmeal-farm-network/ag-agent/tree/main/frontend/src/"
    click FDockerfile "https://github.com/oatmeal-farm-network/ag-agent/tree/main/frontend/Dockerfile"

    %% Backend Container
    subgraph "Backend Container"
        direction TB
        BackendAPI["Backend API (backend.py)"]:::internal
        Config["Env Loader (config.py)"]:::internal
        subgraph "Agent Orchestrator (Multi-Agent Workflow)"
            direction TB
            Agents["agents.py"]:::internal
            RouteAgents["routeagents.py"]:::internal
            PeopleTool["people_tool.py"]:::internal
            UserdataAgent["userdata_agent.py"]:::internal
        end
        ExtAPIClient["Weather API Client"]:::internal
        DBModule["Database Module"]:::internal
        Utils["Utilities"]:::internal
    end
    click BackendAPI "https://github.com/oatmeal-farm-network/ag-agent/blob/main/backend.py"
    click Config "https://github.com/oatmeal-farm-network/ag-agent/blob/main/config.py"
    click Agents "https://github.com/oatmeal-farm-network/ag-agent/blob/main/autogen_module/agents.py"
    click RouteAgents "https://github.com/oatmeal-farm-network/ag-agent/blob/main/autogen_module/routeagents.py"
    click PeopleTool "https://github.com/oatmeal-farm-network/ag-agent/blob/main/autogen_module/people_tool.py"
    click UserdataAgent "https://github.com/oatmeal-farm-network/ag-agent/blob/main/autogen_module/userdata_agent.py"
    click ExtAPIClient "https://github.com/oatmeal-farm-network/ag-agent/blob/main/external_apis/weather_api.py"
    click DBModule "https://github.com/oatmeal-farm-network/ag-agent/tree/main/database_module/"
    click DB1 "https://github.com/oatmeal-farm-network/ag-agent/blob/main/database_module/cosmos_retriever.py"
    click DB2 "https://github.com/oatmeal-farm-network/ag-agent/blob/main/database_module/database_tools.py"
    click Utils "https://github.com/oatmeal-farm-network/ag-agent/tree/main/utilities_module/"
    click U1 "https://github.com/oatmeal-farm-network/ag-agent/blob/main/utilities_module/embedding_utils.py"
    click U2 "https://github.com/oatmeal-farm-network/ag-agent/blob/main/utilities_module/audio_utils.py"
    click U3 "https://github.com/oatmeal-farm-network/ag-agent/blob/main/utilities_module/blob_utils.py"
    click U4 "https://github.com/oatmeal-farm-network/ag-agent/blob/main/utilities_module/session_storage.py"
    click RF "https://github.com/oatmeal-farm-network/ag-agent/blob/main/requirements.txt"
    click CF "https://github.com/oatmeal-farm-network/ag-agent/blob/main/constraints.txt"

    %% Cloud Services
    subgraph "Azure Services"
        direction TB
        AzureOpenAI["Azure OpenAI"]:::cloud
        AzureCosmos["Azure Cosmos DB"]:::cloud
    end

    %% Third-Party API
    subgraph "Third-Party API"
        direction TB
        OpenMeteo["Open-Meteo Weather API"]:::external
    end

    %% User Interaction Flow
    Browser["User Browser"]:::external
    Browser -->|HTTP| Nginx
    Nginx -->|serves| ReactSPA
    ReactSPA -->|HTTP POST /chat| BackendAPI

    %% Backend Workflow
    BackendAPI -->|uses| Config
    BackendAPI -->|calls| Agents
    Agents -->|SDK calls| AzureOpenAI
    Agents -->|invokes| ExtAPIClient
    ExtAPIClient -->|REST call| OpenMeteo
    Agents -->|reads/writes| DBModule
    DBModule -->|SDK calls| AzureCosmos
    Agents -->|uses| Utils
    Agents -->|returns response to| BackendAPI
    BackendAPI -->|HTTP response| ReactSPA

    %% Styles
    classDef internal fill:#cfe2f3,stroke:#036; 
    classDef cloud fill:#d9ead3,stroke:#070; 
    classDef external fill:#fce5cd,stroke:#d35400; 
    classDef infra fill:#eeeeee,stroke:#999;
```
