# aayush-puri-01/content-optimization-agent architecture

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

- Interactive diagram: https://gitdiagram.com/aayush-puri-01/content-optimization-agent
- Repository: https://github.com/aayush-puri-01/content-optimization-agent

## Overview

##### Project Type and Purpose
- This is a backend API service (built on FastAPI) that orchestrates an intelligent “agent” to generate campaign content (hashtags, scripts, audio) by chaining multiple specialized tools and LLM calls.
- Its primary role is dynamic workflow orchestration: taking user prompts, decomposing them, invoking tool‐agents, and returning a formatted campaign.

##### File Structure
- Top‐level:
- Dockerfile/.dockerignore: containerization
- pyproject.toml / uv.lock: dependencies via `uv` package manager
- tests/, utils/: support code
- agentic_system/:
- main.py & app.py: FastAPI application entrypoint
- agent.py: glue Logic for orchestrating flows
- configs/: LLM and logging settings
- routes/agent_router.py: HTTP API endpoint for queries
- schemas/: Pydantic models for requests, agent state, workflow steps
- prompts/: prompt templates for LLM calls
- services/: each file is a tool‐agent (llm_node.py, trend_tool.py, search_tool.py, hashtag_gen.py, script_tool.py, tts_tool.py)

##### Extract Architectural Insights from README
- Central “LLM Router Node” (llm_node.py) as orchestrator
- Independent tool‐agents for trend analysis, web search, hashtag/script generation, TTS
- External dependencies: OpenAI GPT-4o-mini, SerpAPI, Tavily Search, PyTrends, Google Gemini TTS

a. Main Components
- Client (curl, UI, or SDK)
- FastAPI Server (main.py ➔ app.py ➔ agent_router)
- LLM Router Node (llm_node.py)
- Tool Agents (trend_tool, search_tool, hashtag_gen, script_tool, tts_tool)
- External Services (SerpAPI, Tavily Search API, PyTrends, OpenAI, Google Gemini TTS)
- Configuration Module (llm_config, logging_config)
b. Relationships & Interactions
1. Client sends POST /agent/query to FastAPI
2. agent_router receives request, validates via Pydantic schemas
3. Route invokes agent.py which calls LLM Router Node
4. LLM Router extracts campaign parameters, dynamically plans steps
5. For each step, LLM Router calls the appropriate Tool Agent
- Trend Analyzer ↔ PyTrends / SerpAPI
- Search Engine ↔ Tavily Search
- Hashtag Generator ↔ OpenAI LLM
- Script Generator ↔ OpenAI LLM
- TTS Generator ↔ Google Gemini TTS
6. Tool Agents return structured data to LLM Router
7. Once workflow completes, LLM Router formats final output
8. FastAPI returns JSON response to client
c. Architectural Patterns & Principles
- Orchestrator / Workflow Engine pattern (LLM Router)
- Tool‐oriented microservice modules (loosely coupled)
- Function‐calling / plugin pattern via OpenAI
- Configuration—code separation (configs/ folder)
- Schema validation (Pydantic)
d. Key Technologies & Libraries
- FastAPI for HTTP server and routing
- LangGraph / LangChain for orchestrating LLM workflows
- OpenAI GPT-4o-mini LLM for planning & content generation
- SerpAPI, PyTrends, Tavily Search, Google Gemini TTS as external data sources
- Pydantic for request/response schemas

##### Every Essential Element
- Tests/ and utils/ off to the side as “Support Modules”
- Steps in the workflow with numbered labels to show dynamic planning

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client
    Client["Client (curl/UI/SDK)"]:::external

    %% FastAPI Service
    subgraph "FastAPI Service"
        Main["main.py"]:::internal
        App["app.py"]:::internal
        Router["agent_router.py"]:::internal
    end

    %% Configuration & Schemas
    subgraph "Configuration & Schemas"
        LLMCfg["llm_config.py"]:::config
        LogCfg["logging_config.py"]:::config
        APISchemas["api_schemas.py"]:::config
        StateSchemas["agentstate_manager.py & state.py"]:::config
    end

    %% LLM Orchestrator
    subgraph "LLM Orchestrator"
        Orchestrator["agent.py"]:::orchestrator
        LLMRouter["llm_node.py"]:::orchestrator
    end

    %% Tool Agents
    subgraph "Tool Agents"
        Trend["trend_tool.py"]:::internal
        Search["search_tool.py"]:::internal
        Hashtag["hashtag_gen.py"]:::internal
        Script["script_tool.py"]:::internal
        TTS["tts_tool.py"]:::internal
    end

    %% External Services
    subgraph "External Services"
        PyTrends["PyTrends / SerpAPI"]:::external
        Tavily["Tavily Search API"]:::external
        OpenAI["OpenAI GPT-4"]:::external
        GoogleTTS["Google Gemini TTS"]:::external
    end

    %% Support Modules & Documentation
    subgraph "Support & Docs"
        Utils["utils/"]:::internal
        Tests["tests/"]:::internal
        Docs["docs/ & README.md"]:::internal
        Infra["pyproject.toml, uv.lock, Dockerfile, .dockerignore"]:::internal
    end

    %% Connections
    Client -->|"POST /agent/query"| Router
    Main --> App
    App --> Router
    Router -->|"validate request"| APISchemas
    Router -->|"invoke"| Orchestrator
    APISchemas -.-> StateSchemas
    LLMCfg --> Router
    LogCfg --> Router
    LLMCfg --> LLMRouter
    LogCfg --> LLMRouter
    Orchestrator --> LLMRouter
    LLMRouter -->|"plan step"| Trend
    LLMRouter -->|"plan step"| Search
    LLMRouter -->|"plan step"| Hashtag
    LLMRouter -->|"plan step"| Script
    LLMRouter -->|"plan step"| TTS
    Trend --> PyTrends
    Search --> Tavily
    Hashtag --> OpenAI
    Script --> OpenAI
    TTS --> GoogleTTS
    LLMRouter --> Orchestrator
    Orchestrator -->|"return result"| Router
    Router -->|"response JSON"| Client

    %% Click Events
    click Main "https://github.com/aayush-puri-01/content-optimization-agent/blob/main/agentic_system/main.py"
    click App "https://github.com/aayush-puri-01/content-optimization-agent/blob/main/agentic_system/app.py"
    click Router "https://github.com/aayush-puri-01/content-optimization-agent/blob/main/agentic_system/routes/agent_router.py"
    click Orchestrator "https://github.com/aayush-puri-01/content-optimization-agent/blob/main/agentic_system/agent.py"
    click LLMRouter "https://github.com/aayush-puri-01/content-optimization-agent/blob/main/agentic_system/services/llm_node.py"
    click Trend "https://github.com/aayush-puri-01/content-optimization-agent/blob/main/agentic_system/services/trend_tool.py"
    click Search "https://github.com/aayush-puri-01/content-optimization-agent/blob/main/agentic_system/services/search_tool.py"
    click Hashtag "https://github.com/aayush-puri-01/content-optimization-agent/blob/main/agentic_system/services/hashtag_gen.py"
    click Script "https://github.com/aayush-puri-01/content-optimization-agent/blob/main/agentic_system/services/script_tool.py"
    click TTS "https://github.com/aayush-puri-01/content-optimization-agent/blob/main/agentic_system/services/tts_tool.py"
    click LLMCfg "https://github.com/aayush-puri-01/content-optimization-agent/blob/main/agentic_system/configs/llm_config.py"
    click LogCfg "https://github.com/aayush-puri-01/content-optimization-agent/blob/main/agentic_system/configs/logging_config.py"
    click APISchemas "https://github.com/aayush-puri-01/content-optimization-agent/blob/main/agentic_system/schemas/api_schemas.py"
    click StateSchemas "https://github.com/aayush-puri-01/content-optimization-agent/blob/main/agentic_system/schemas/agentstate_manager.py"
    click Utils "https://github.com/aayush-puri-01/content-optimization-agent/tree/main/utils/"
    click Tests "https://github.com/aayush-puri-01/content-optimization-agent/tree/main/tests/"
    click Docs "https://github.com/aayush-puri-01/content-optimization-agent/tree/main/docs/"
    click Infra "https://github.com/aayush-puri-01/content-optimization-agent/blob/main/pyproject.toml"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
    classDef config fill:#FFA500,stroke:#333,stroke-width:1px
    classDef orchestrator fill:#87CEFA,stroke:#333,stroke-width:1px
```
