# hoangsonww/agentic-ai-pipeline architecture

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

- Interactive diagram: https://gitdiagram.com/hoangsonww/agentic-ai-pipeline
- Repository: https://github.com/hoangsonww/agentic-ai-pipeline

## Overview

##### Project Type and Purpose
- This is a **full-stack, agentic AI platform** with a primary Research & Outreach Agent.
- It combines a **FastAPI+SSE web UI**, a **CLI**, a **LangGraph-driven multi-stage agent**, **memory stores** (SQLite & ChromaDB), **atomic tools**, **client SDKs**, and **companion pipelines** (Agentic-RAG, Agentic-Coding).
- It includes complete DevOps/infrastructure code (Docker, Ansible, Terraform, Kubernetes, AWS CD/CFN, GitHub Actions).

##### File Structure
- Top-level “src/agentic_ai/” contains the core 7-layer agent logic:
- Experience (app.py + web/)
- Discovery, Composition, Reasoning, Tools, Memory, Infrastructure.
- “web/” holds the static chat UI (Vue3 via CDN).
- “clients/” contains TypeScript and Python SDKs.
- Two side-car pipelines: “Agentic-RAG-Pipeline/” and “Agentic-Coding-Pipeline/” with their own agents, graph runners, and tools.
- An “mcp/” micro-service exposes a shared control plane (HTTP/SSE) for all pipelines.
- “ansible/”, “aws/”, “k8s/”, “hashicorp/terraform/” orchestrate deployment.
- “Makefile” and “scripts/” automate setup, ingestion, testing, and deployment.

##### README Insights on Architecture
- **7-Layer Architecture**: Experience → Discovery → Composition → Reasoning → Tools/API → Memory/Feedback → Infrastructure.
- **LangGraph Agent Graph**: A state machine with PLAN→DECIDE→ACT→TOOLS→REFLECT→FINALIZE.
- **Atomic Tools**: web_search, web_fetch, kb_search, calculator, file_write, emailer.
- **Memory**: SQLite for messages, ChromaDB for vector KB.
- **External Services**: OpenAI/Anthropic LLMs, DuckDuckGo Search.

- **Frontend**:
- Web UI (browser)
- CLI & SDKs (Python, TS)
- **API Server**: FastAPI/Uvicorn
- **Agent Core**: LangGraph runner (graph.py + layers/*)
- **Tool Layer**: modules under tools/ (webtools, ops, knowledge)
- **Memory Layer**: SQLite store, ChromaDB vector store
- **Companion Pipelines**: Agentic-RAG, Agentic-Coding, each with its own agent graph & tools
- **MCP Server**: centralized HTTP/SSE control plane (mcp/server.py)
- **External Systems**: OpenAI, Anthropic, DuckDuckGo, SMTP (mock), file system for artifacts
- **Infrastructure**: Rate limiter, logging, config (infra/), plus Docker, Ansible, Terraform, k8s

- User → Web UI/CLI → FastAPI (Experience)
- FastAPI → Rate limiter → Agent graph entry
- Agent graph steps → Tool calls → External APIs or Memory → results back into graph
- Agent final output → SSE stream → UI/CLI → persists to SQLite & file system
- Ingestion CLI → Memory vector store (ChromaDB)
- Companion pipelines & MCP → reuse the same tools, memory, and control plane

c. Architectural Patterns & Principles
- **Layered Architecture**: clear separation of concerns in 7 layers
- **Single-action per step**: each DECIDE/ACT binds one tool call
- **Event-driven/SSE streaming**: incremental updates to the UI/CLI
- **Micro-service hooks**: mcp server and side-pipelines treated as peer services
- **Infrastructure as Code**: Docker/Ansible/Terraform/K8s manifests

d. Key Technologies & Frameworks
- FastAPI, Uvicorn, SSE
- LangGraph (state machine orchestrator)
- LangChain (tool abstractions for RAG)
- OpenAI & Anthropic LLMs
- SQLite + SQLAlchemy, ChromaDB
- Docker, Ansible, Terraform, Kubernetes
- Vue.js (UI), TypeScript & Python (SDKs)
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        UI["Web UI<br/>(Browser)"]:::frontend
        CLI["CLI"]:::frontend
        PySDK["Python SDK"]:::frontend
        TSSDK["TypeScript SDK"]:::frontend
    end

    %% API Server
    API["FastAPI/Uvicorn<br/>(Experience Layer)"]:::backend

    %% Infrastructure Side Modules
    subgraph "Infra Modules"
        direction TB
        RateLimiter["Rate Limiter"]:::infra
        Logging["Logging"]:::infra
    end

    %% Agent Core
    subgraph "Agent Core (LangGraph Runner)" 
        direction TB
        GraphRunner["graph.py<br/>(LangGraph Runner)"]:::core
        subgraph "Layers"
            direction TB
            Composition["Composition Layer"]:::core
            Reasoning["Reasoning Layer"]:::core
            ToolsLayer["Tools Layer"]:::core
            MemoryLayer["Memory Layer"]:::core
        end
    end

    %% Atomic Tools
    subgraph "Atomic Tools" 
        direction TB
        ContentGen["content_generation"]:::tool
        Knowledge["knowledge_search"]:::tool
        Ops["ops (emailer, file_write)"]:::tool
        SocialMedia["social_media_tools"]:::tool
        WebTools["webtools (search/fetch)"]:::tool
    end

    %% LLM Clients
    LLMClients["OpenAI/Anthropic Clients"]:::external

    %% Memory Stores
    subgraph "Memory Stores" 
        direction TB
        SQLite["SQLite Store"]:::storage
        ChromaDB["ChromaDB Vector Store"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI API"]:::cloud
        Anthropic["Anthropic API"]:::cloud
        DuckDuckGo["DuckDuckGo Search"]:::cloud
        SMTP["SMTP (Mock)"]:::cloud
        FileSystem["File System"]:::storage
    end

    %% Companion Pipelines
    subgraph "Companion Pipelines"
        direction TB
        subgraph "Agentic-RAG Pipeline"
            direction TB
            RAGApp["app.py"]:::backend
            RAGServices["services.py"]:::backend
        end
        subgraph "Agentic-Coding Pipeline"
            direction TB
            CodingRun["run.py"]:::backend
            CodingPipeline["pipeline.py"]:::backend
        end
    end

    %% MCP Server
    MCP["MCP Server<br/>(HTTP/SSE)"]:::backend

    %% Infrastructure as Code
    subgraph "Infrastructure as Code"
        direction TB
        Ansible["Ansible"]:::infra
        AWS["AWS CD/CFN/ECS"]:::infra
        K8s["Kubernetes Manifests"]:::infra
        Terraform["Terraform"]:::infra
        CICD["GitHub Actions"]:::infra
        Scripts["Build & Automation Scripts"]:::infra
        DockerDef["Docker & Compose"]:::infra
    end

    %% Connections
    UI -->|"HTTP/WS/SSE"| API
    CLI -->|"API Calls"| API
    PySDK -->|"API Calls"| API
    TSSDK -->|"API Calls"| API

    API -->|applies| RateLimiter
    API -->|logs to| Logging
    API -->|"invoke"| GraphRunner

    RateLimiter --> GraphRunner
    Logging --> GraphRunner

    GraphRunner --> Composition
    Composition --> Reasoning
    Reasoning --> ToolsLayer
    ToolsLayer --> MemoryLayer

    ToolsLayer --> ContentGen
    ToolsLayer --> Knowledge
    ToolsLayer --> Ops
    ToolsLayer --> SocialMedia
    ToolsLayer --> WebTools

    GraphRunner -->|uses| LLMClients
    LLMClients --> OpenAI
    LLMClients --> Anthropic

    MemoryLayer --> SQLite
    MemoryLayer --> ChromaDB

    SQLite --> FileSystem
    ChromaDB --> FileSystem

    ContentGen --> OpenAI
    Knowledge --> DuckDuckGo
    WebTools --> DuckDuckGo
    Ops --> SMTP
    SocialMedia --> DuckDuckGo

    GraphRunner -->|outputs| API
    API -->|SSE Stream| UI

    IngestCLI["Ingestion CLI"]:::frontend
    IngestCLI --> ChromaDB

    RAGApp -->|reuse| ToolsLayer
    RAGApp -->|reuse| MemoryLayer
    RAGApp -->|calls| MCP
    CodingRun -->|reuse| ToolsLayer
    CodingRun -->|reuse| MemoryLayer
    CodingRun -->|calls| MCP

    MCP --> ToolsLayer
    MCP --> MemoryLayer

    API -.->|deployed via| Ansible
    API -.->|deployed via| AWS
    API -.->|deployed via| K8s
    API -.->|deployed via| Terraform
    CICD -.-> API
    Scripts -.-> API
    DockerDef -.-> API

    %% Click Events
    click UI "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/web/app.js"
    click UI "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/web/index.html"
    click UI "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/web/styles.css"
    click UI "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/web/social_media.html"
    click CLI "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/src/agentic_ai/cli.py"
    click PySDK "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/clients/python/agentic_ai_client/client.py"
    click PySDK "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/clients/python/agentic_ai_client/__main__.py"
    click TSSDK "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/clients/ts/src/client.ts"
    click TSSDK "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/clients/ts/src/index.ts"
    click API "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/src/agentic_ai/app.py"
    click GraphRunner "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/src/agentic_ai/graph.py"
    click Composition "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/src/agentic_ai/layers/composition.py"
    click Reasoning "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/src/agentic_ai/layers/reasoning.py"
    click ToolsLayer "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/src/agentic_ai/layers/tools.py"
    click MemoryLayer "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/src/agentic_ai/layers/memory.py"
    click ContentGen "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/src/agentic_ai/tools/content_generation.py"
    click Knowledge "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/src/agentic_ai/tools/knowledge.py"
    click Ops "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/src/agentic_ai/tools/ops.py"
    click SocialMedia "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/src/agentic_ai/tools/social_media_tools.py"
    click WebTools "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/src/agentic_ai/tools/webtools.py"
    click SQLite "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/src/agentic_ai/memory/sql_store.py"
    click ChromaDB "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/src/agentic_ai/memory/vector_store.py"
    click LLMClients "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/src/agentic_ai/llm/clients.py"
    click RateLimiter "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/src/agentic_ai/infra/rate_limit.py"
    click Logging "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/src/agentic_ai/infra/logging.py"
    click MCP "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/mcp/server.py"
    click MCP "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/mcp/schemas.py"
    click MCP "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/mcp/tools/files.py"
    click MCP "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/mcp/tools/kb.py"
    click MCP "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/mcp/tools/web.py"
    click Ansible "https://github.com/hoangsonww/agentic-ai-pipeline/tree/master/ansible/"
    click AWS "https://github.com/hoangsonww/agentic-ai-pipeline/tree/master/aws/cfn/"
    click AWS "https://github.com/hoangsonww/agentic-ai-pipeline/tree/master/aws/codebuild/"
    click AWS "https://github.com/hoangsonww/agentic-ai-pipeline/tree/master/aws/codepipeline/"
    click AWS "https://github.com/hoangsonww/agentic-ai-pipeline/tree/master/aws/ecs/"
    click K8s "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/k8s/deployment.yaml"
    click K8s "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/k8s/service.yaml"
    click K8s "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/k8s/ingress.yaml"
    click Terraform "https://github.com/hoangsonww/agentic-ai-pipeline/tree/master/hashicorp/terraform/"
    click CICD "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/.github/workflows/ci.yml"
    click CICD "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/.github/workflows/release.yml"
    click CICD "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/.github/workflows/monorepo-ci.yml"
    click CICD "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/.github/workflows/smoke-api.yml"
    click Scripts "https://github.com/hoangsonww/agentic-ai-pipeline/tree/master/scripts/"
    click DockerDef "https://github.com/hoangsonww/agentic-ai-pipeline/tree/master/Dockerfile"
    click DockerDef "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/.dockerignore"
    click DockerDef "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/compose.yaml"
    click DockerDef "https://github.com/hoangsonww/agentic-ai-pipeline/blob/master/compose.override.yaml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#1E70BF,color:#1E70BF;
    classDef backend fill:#E0F8E0,stroke:#28A745,color:#28A745;
    classDef core fill:#E8F4FF,stroke:#0056B3,color:#0056B3;
    classDef tool fill:#FFF4E5,stroke:#FF8C00,color:#FF8C00;
    classDef storage fill:#F5E1E0,stroke:#A52A2A,color:#A52A2A;
    classDef internet fill:#F0F0F0,stroke:#666666,color:#666666;
    classDef infra fill:#EDEDED,stroke:#888888,color:#888888;
    classDef cloud fill:#F0F8FF,stroke:#4682B4,color:#4682B4;
```
