# qizhengzhong111/agent_orchestrator architecture

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

- Interactive diagram: https://gitdiagram.com/qizhengzhong111/agent_orchestrator
- Repository: https://github.com/qizhengzhong111/agent_orchestrator

## Overview

##### Project type and purpose
- This is a backend-centric, multi-agent orchestration service written in Python. It exposes a FastAPI endpoint, uses LangGraph to drive a graph-based workflow, and routes natural-language user requests to one of three agents (data preparation, reconciliation, fallback). It also integrates with external services (Azure OpenAI).

##### File structure
- DemoData/ (CSV files used by two agents)
- config.json (agent-specific settings, e.g., model names, parameters)
- acquire_access_token.py (module to fetch OAuth tokens for Azure OpenAI)
- langgraph_lite.py (defines StateGraph, router node, agents, conditional edges, graph.compile())
- multiagentchat.py (FastAPI app exposing a POST /multiagentchat endpoint)
- requirements.txt, README.md

##### README for insights
- Confirms three agents behind a router node in a graph, compiled into multiagent_app
- FastAPI service on port 8001
- `.env` holds OPENAI_API_KEY for Azure integration
- DemoData feeds the finance-specific agents

a. Main components
- User / Frontend (or any HTTP client)
- FastAPI Service (multiagentchat.py)
- Orchestration Engine (langgraph_lite.py → StateGraph)
– Router Node
– data_preparation Agent
– reconciliation Agent
– fallback Agent
- Configuration / Token modules
– config.json
– acquire_access_token.py / .env
- Data Store (DemoData CSV files)
- External Service (Azure OpenAI API)

b. Relationships & data flows
1. User sends JSON {"input": "..."} → FastAPI endpoint
2. FastAPI calls multiagent_app.invoke({"input": ...})
3. Orchestration Engine’s router node examines input → chooses agent
4. Chosen agent may:
- Read/write DemoData CSVs
- Call acquire_access_token.py to get token
- Invoke Azure OpenAI with token + prompt
5. Agent returns result → graph returns to FastAPI → HTTP response

c. Architectural patterns / principles
- Workflow / state-graph pattern (LangGraph)
- Modular agents behind a single entry point
- Clear separation of concerns: API layer, orchestration layer, agents, configuration, data, external services

d. Key technologies
- Python 3.x, FastAPI (HTTP service)
- LangGraph (workflow engine)
- Azure OpenAI (LLM calls)
- CSV file store for demo data

##### Detail
- Don’t just show “Backend” as a block—break it into FastAPI, orchestration engine, token module, each agent, config, and DemoData.
- Entry points, data stores, external dependencies, and workflow transitions precisely.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    User["User / HTTP Client"]:::external

    %% API Layer
    FastAPI["FastAPI Service<br/>multiagentchat.py"]:::compute

    %% Orchestration Layer
    Router["Router Node<br/>(StateGraph)"]:::compute

    %% Agents
    DataPrep["Data Preparation Agent"]:::compute
    Recon["Reconciliation Agent"]:::compute
    Fallback["Fallback Agent"]:::compute

    %% Data & Config
    subgraph "Config & Support"
        direction TB
        Config["Configuration Store<br/>config.json"]:::data
        TokenModule["Token Acquisition Module<br/>acquire_access_token.py"]:::data
        requirements["Requirements<br/>requirements.txt"]:::data
        readme["Documentation<br/>README.md"]:::data
    end

    subgraph "Demo Data Store"
        direction TB
        DemoDataDir["DemoData/"]:::data
        PrimaryCSV["BaseReconDemoDataPrimary.csv"]:::data
        SecondaryCSV["BaseReconDemoDataSecondary.csv"]:::data
    end

    %% External Service
    Azure["Azure OpenAI API"]:::external

    %% Connections
    User -->|"POST /multiagentchat"| FastAPI
    FastAPI -->|"invoke multiagent_app.invoke()"| Router

    Router -->|"if data prep"| DataPrep
    Router -->|"if reconciliation"| Recon
    Router -->|"else fallback"| Fallback

    DataPrep -->|"read/write CSV"| DemoDataDir
    Recon -->|"read/write CSV"| DemoDataDir

    DemoDataDir --> PrimaryCSV
    DemoDataDir --> SecondaryCSV

    DataPrep -->|"get token"| TokenModule
    Recon -->|"get token"| TokenModule

    TokenModule -->|"fetch OAuth token"| Azure

    DataPrep -->|"LLM call"| Azure
    Recon -->|"LLM call"| Azure
    Fallback -->|"LLM call"| Azure

    DataPrep -->|"return result"| Router
    Recon -->|"return result"| Router
    Fallback -->|"return result"| Router

    Router -->|"result payload"| FastAPI
    FastAPI -->|"HTTP response"| User

    %% Click Events
    click FastAPI "https://github.com/qizhengzhong111/agent_orchestrator/blob/main/multiagentchat.py"
    click Router "https://github.com/qizhengzhong111/agent_orchestrator/blob/main/langgraph_lite.py"
    click DataPrep "https://github.com/qizhengzhong111/agent_orchestrator/blob/main/langgraph_lite.py"
    click Recon "https://github.com/qizhengzhong111/agent_orchestrator/blob/main/langgraph_lite.py"
    click Fallback "https://github.com/qizhengzhong111/agent_orchestrator/blob/main/langgraph_lite.py"
    click Config "https://github.com/qizhengzhong111/agent_orchestrator/blob/main/config.json"
    click TokenModule "https://github.com/qizhengzhong111/agent_orchestrator/blob/main/acquire_access_token.py"
    click DemoDataDir "https://github.com/qizhengzhong111/agent_orchestrator/tree/main/DemoData/"
    click PrimaryCSV "https://github.com/qizhengzhong111/agent_orchestrator/blob/main/DemoData/BaseReconDemoDataPrimary.csv"
    click SecondaryCSV "https://github.com/qizhengzhong111/agent_orchestrator/blob/main/DemoData/BaseReconDemoDataSecondary.csv"
    click requirements "https://github.com/qizhengzhong111/agent_orchestrator/blob/main/requirements.txt"
    click readme "https://github.com/qizhengzhong111/agent_orchestrator/blob/main/README.md"

    %% Styles
    classDef compute fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef data fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
```
