# coder-teddy/ai-support-agent architecture

> Architecture diagram of the GitHub repository coder-teddy/ai-support-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/coder-teddy/ai-support-agent
- Repository: https://github.com/coder-teddy/ai-support-agent

## Overview

##### Project Type and Purpose
- This is a single‐service, full-stack “AI Support Agent” CLI/daemon built in Node.js.
- Its purpose is to scrape website content, convert it into vector embeddings via OpenAI, store/search in a vector DB (ChromaDB), and answer user queries semantically.

##### Core Components
a. Web Scraper Module
- Implements Axios + Cheerio (in index.js)
- Fetches HTML from target URLs
b. Text Processor & Chunker
- Splits raw HTML/text into manageable chunks (`textChunks()` logic)
c. Embedding Service
- Calls OpenAI API (`text-embedding-3-small`) to convert chunks → vectors
d. Vector Database
- ChromaDB running in Docker (defined in docker-compose.yml)
e. Query Handler
- Accepts user input (CLI or API hook)
- Embeds query, performs semantic search over ChromaDB
f. Response Generator
- Ranks top N results, synthesizes answer in natural language
g. External Services
- Target website(s) being scraped
- OpenAI API endpoint

##### Relationships & Data Flow
1. Start: User invokes `node index.js` → triggers Scraper
2. Scraper fetches HTML from External Website(s)
3. Processor extracts text, splits into chunks
4. Embedding Service sends each chunk to OpenAI API → receives embeddings
5. Embeddings are written to ChromaDB (Docker container)
6. On user query: Query Handler embeds query via OpenAI → gets query vector
7. Vector DB performs similarity search → returns closest documents
8. Response Generator collates and returns best answer

##### Architectural Patterns & Principles
- Single-process pipeline with modular stages (Scraper → Embedder → DB → Search → Response)
- Separation of concerns: extraction, transformation, storage, retrieval
- Infrastructure as code: Docker Compose for vector DB
- External API integration: OpenAI for embeddings

##### Additional Notes
- If expanding into REST or chat widgets, overlay an “API Gateway” fronting the Query Handler.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External user invocation
    UserCLI["User CLI"]:::external
    %% Internal processing modules
    WebScraper["Web Scraper (Axios/Cheerio)"]:::internal
    TextChunker["Text Processor & Chunker"]:::internal
    EmbeddingService["Embedding Service (OpenAI)"]:::internal
    QueryHandler["Query Handler"]:::internal
    ResponseGenerator["Response Generator"]:::internal
    %% External services
    OpenAI["OpenAI API"]:::external
    %% Dockerized database
    subgraph "Docker"
        ChromaDB["ChromaDB"]:::db
    end
    %% Configuration & docs
    Config["package.json"]:::config
    Docs["README.md"]:::config

    %% Data and control flows
    UserCLI -->|invokes CLI| WebScraper
    WebScraper -->|fetched HTML| TextChunker
    TextChunker -->|text chunks| EmbeddingService
    EmbeddingService -->|embeddings| ChromaDB
    UserCLI -->|query| QueryHandler
    QueryHandler -->|embed query| OpenAI
    OpenAI -->|query vector| QueryHandler
    QueryHandler -->|semantic search| ChromaDB
    ChromaDB -->|results| ResponseGenerator
    ResponseGenerator -->|answer| UserCLI

    %% Click Events
    click WebScraper "https://github.com/coder-teddy/ai-support-agent/blob/main/index.js"
    click TextChunker "https://github.com/coder-teddy/ai-support-agent/blob/main/index.js"
    click EmbeddingService "https://github.com/coder-teddy/ai-support-agent/blob/main/index.js"
    click QueryHandler "https://github.com/coder-teddy/ai-support-agent/blob/main/index.js"
    click ResponseGenerator "https://github.com/coder-teddy/ai-support-agent/blob/main/index.js"
    click ChromaDB "https://github.com/coder-teddy/ai-support-agent/blob/main/docker-compose.yml"
    click Config "https://github.com/coder-teddy/ai-support-agent/blob/main/package.json"
    click Docs "https://github.com/coder-teddy/ai-support-agent/blob/main/README.md"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:1
    classDef external fill:#FFA500,stroke:#333,stroke-width:1
    classDef db fill:#90EE90,stroke:#333,stroke-width:1
    classDef config fill:#E0E0E0,stroke:#333,stroke-width:1
```
