# hamidrezak324/cag architecture

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

- Interactive diagram: https://gitdiagram.com/hamidrezak324/cag
- Repository: https://github.com/hamidrezak324/cag

## Overview

##### Project Type and Purpose
- This is a backend‐focused, containerized API service (FastAPI) for calculating Compound Annual Growth Rate (CAGR) from CSV stock data.
- Key external pieces: Redis (caching), ChromaDB (vector storage), Hugging Face NLP models, and Docker for deployment.

##### Main Architectural Components
a. Client (e.g., browser, Postman)
b. Docker Container (boundary “wall” representing the running environment)
- FastAPI service (app.py)
- Redis cache
- ChromaDB data store (chroma_db folder + sqlite)
- Dataset volume (mounted folder containing CSVs)
c. External NLP Model (Hugging Face)

##### Relationships and Data Flows
- Client → HTTP request → FastAPI
- FastAPI → check Redis cache → return cached result or compute
- FastAPI → read from dataset (CSV) → compute CAGR
- FastAPI → store/query vectors → ChromaDB
- FastAPI → call Hugging Face model for any NLP preprocessing
- FastAPI → write result → Redis for future cache
- FastAPI → HTTP response → Client

##### Architectural Patterns and Principles
- Layered: API layer, caching layer, storage layer, external AI service
- Containerization: all core services run inside one Docker image/container
- Separation of concerns: each component has a single responsibility

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Client["🖥️ Client (Browser/Postman)"]:::client

    %% Docker Container Boundary
    subgraph "🐳 Docker Container"
        direction TB
        FastAPI["🦄 FastAPI Service"]:::api
        Redis["📦 Redis Cache"]:::redis
        Dataset["📁 CSV Dataset (volume)"]:::storage
        ChromaDB["🗄️ ChromaDB Vector Store"]:::storage
        Dockerfile["Dockerfile"]:::config
        Req["requirements.txt"]:::config
    end

    %% External NLP Model
    HF["😊 Hugging Face NLP Model"]:::ai

    %% Connections
    Client -->|"HTTP POST /cagr"| FastAPI
    FastAPI <-->|"GET/SET cache"| Redis
    FastAPI -->|"read CSV"| Dataset
    FastAPI <-->|"vector storage & retrieval"| ChromaDB
    HF -->|"NLP inference"| FastAPI

    %% Click Events
    click FastAPI "https://github.com/hamidrezak324/cag/blob/main/app.py"
    click Dockerfile "https://github.com/hamidrezak324/cag/tree/main/Dockerfile"
    click Req "https://github.com/hamidrezak324/cag/blob/main/requirements.txt"
    click ChromaDB "https://github.com/hamidrezak324/cag/tree/main/chroma_db/"
    click Dataset "https://github.com/hamidrezak324/cag/tree/main/dataset/"

    %% Styles
    classDef client fill:#a0d8ef,stroke:#006d9c,color:#000
    classDef api fill:#c8daff,stroke:#0b409c,color:#000
    classDef redis fill:#ffd6d6,stroke:#d92626,color:#000
    classDef storage fill:#d6ffe0,stroke:#20a020,color:#000
    classDef ai fill:#ffe0b2,stroke:#d97e00,color:#000
    classDef config fill:#e0e0e0,stroke:#888888,color:#000
```
