# pr0mila/groqstreamchain architecture

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

- Interactive diagram: https://gitdiagram.com/pr0mila/groqstreamchain
- Repository: https://github.com/pr0mila/groqstreamchain

## Overview

##### Project type and purpose
- This is a full-stack, real-time AI chat application (“GroqStreamChain”) built with FastAPI (backend), WebSockets (real-time communication), LangChain + Groq (LLM service), and a minimal HTML/CSS/JS frontend.

##### File structure
- Top-level:
- server.py – FastAPI app with HTTP & WebSocket routes
- config.py & system_prompts.py – environment/configuration and prompt templates
- models/chat.py – Pydantic models for request/response schemas
- services/llm_service.py – abstraction over the Groq & LangChain client
- static/ & templates/ – frontend assets (HTML, JS, CSS)
- test_groq.py – standalone script to validate Groq API connectivity
- No external database, so sessions are ephemeral/in‐memory within the running server.

##### Key insights from README
- Real-time streaming: WebSocket connection for bi-directional, low-latency chat.
- Chunked LLM responses: streamed back through the same socket.
- Clean separation: presentation (static/, templates/) vs. API layer (server.py) vs. LLM service (services/llm_service.py).

##### Main components
a. Frontend (Browser)
- index.html + main.js establishes a WebSocket to the backend
- Renders messages, shows typing indicators, streams incoming chunks
b. API Layer (FastAPI / server.py)
- HTTP endpoint to serve the HTML page
- WebSocket endpoint to receive user messages & push LLM replies
- Manages chat sessions (in-memory or by session ID)
c. Business Logic / Service Layer
- llm_service.py orchestrates calls to the Groq/LangChain client
- system_prompts.py provides prompt templates
- config.py supplies API key & model name from environment (.env)
d. External LLM Provider
- Groq API (via LangChain’s Groq integration)
- Streams token chunks back to llm_service
e. Test Harness (Optional)
- test_groq.py independently tests connectivity to Groq API
- Can be shown as a side-branch for validation, not on the critical path

##### Relationships and data flow
1. Browser loads index.html from FastAPI HTTP route
2. main.js opens WebSocket → FastAPI server
3. User message → WebSocket “message” event → server.py receives payload (chat model)
4. server.py calls llm_service.generate_response(…)
5. llm_service uses LangChain + Groq client → Groq API
6. Groq streams token chunks → llm_service forwards each chunk
7. server.py pushes each chunk through WebSocket → browser UI renders stream
8. End of stream closes the loop; client shows complete message

##### Architectural patterns & design principles
- Layered architecture:
- Presentation (static + templates)
- API/Controller (FastAPI endpoints)
- Service (LLM orchestration)
- Configuration (config & prompts)
- Single responsibility: each module has a focused job
- Streaming architecture: asynchronous, non-blocking WebSockets for chunked data
- Externalize configuration: .env for API keys & model names

##### Technologies & frameworks
- Frontend: HTML5, vanilla JS (WebSocket API), CSS
- Backend: FastAPI (async), Uvicorn (ASGI), Pydantic models
- AI Service: LangChain, Groq Python client
- Utilities: python-dotenv for config, Jinja2 for templating

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend App"
        direction TB
        Browser["Browser"]:::client
        HTML["index.html"]:::frontend
        JS["main.js"]:::frontend
        CSS["style.css"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend App"
        direction TB
        HTTP["HTTP GET Endpoint"]:::api
        WS["WebSocket Endpoint"]:::api
        Server["FastAPI App (server.py)"]:::api
        Models["Chat Pydantic Models"]:::model
        Service["LLM Service"]:::service
        Config["Configuration (config.py)"]:::config
        Prompts["Prompt Templates (system_prompts.py)"]:::config
    end

    %% External & Tools
    GroqAPI["Groq API (via LangChain)"]:::external
    TestHarness["test_groq.py"]:::tool

    %% Data Flow
    Browser -->|"HTTP GET /"| HTTP
    HTTP -->|serves index.html| HTML
    HTML -->|loads JS & CSS| JS
    HTML -->|loads JS & CSS| CSS

    JS -->|"WebSocket Connect"| WS
    JS -->|"send user message"| WS
    WS -->|"receives message"| Server
    Server -->|"uses Models"| Models
    Server -->|"calls generate_response()"| Service
    Service -->|"uses Config & Prompts"| Config
    Service -->|"uses Config & Prompts"| Prompts
    Service -->|"API call"| GroqAPI
    GroqAPI -->|"stream token chunks"| Service
    Service -->|"stream chunks"| Server
    Server -->|"send chunks"| WS
    WS -->|"stream chunks"| JS

    %% Test Harness Side Branch
    TestHarness -->|"validates connectivity"| GroqAPI

    %% Click Events
    click HTML "https://github.com/pr0mila/groqstreamchain/blob/main/templates/index.html"
    click JS "https://github.com/pr0mila/groqstreamchain/blob/main/static/js/main.js"
    click CSS "https://github.com/pr0mila/groqstreamchain/blob/main/static/css/style.css"
    click Server "https://github.com/pr0mila/groqstreamchain/blob/main/server.py"
    click Models "https://github.com/pr0mila/groqstreamchain/blob/main/models/chat.py"
    click Service "https://github.com/pr0mila/groqstreamchain/blob/main/services/llm_service.py"
    click Config "https://github.com/pr0mila/groqstreamchain/blob/main/config.py"
    click Prompts "https://github.com/pr0mila/groqstreamchain/blob/main/system_prompts.py"
    click TestHarness "https://github.com/pr0mila/groqstreamchain/blob/main/test_groq.py"

    %% Styles
    classDef client fill:#B3D4FC,stroke:#333;
    classDef frontend fill:#E0F7FA,stroke:#333;
    classDef api fill:#D4F4DD,stroke:#333;
    classDef service fill:#FFE3B3,stroke:#333;
    classDef external fill:#E5D4F4,stroke:#333;
    classDef config fill:#FFF2B3,stroke:#333;
    classDef model fill:#F0F0F0,stroke:#333;
    classDef tool fill:#D8D8D8,stroke:#333;
```
