# vanshajr/chatsynth architecture

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

- Interactive diagram: https://gitdiagram.com/vanshajr/chatsynth
- Repository: https://github.com/vanshajr/chatsynth

## Overview

##### Project type and purpose
- ChatSynth is a monolithic Python/Streamlit “full-stack” web application that:
– Builds a structured user profile (JSON)
– Generates a FAISS vector index from that profile
– Provides a RAG-style chat interface (rag_chatbot.py)
– Deploys a new chatbot repo to GitHub via one-click integration

##### File structure
- app.py – orchestrator entry point, implements Steps 1–4 via Streamlit UI
- deployed_files/
– rag_chatbot.py – the standalone chat app code pushed to user’s GitHub repo
– requirements.txt – dependencies for the deployed chatbot
- requirements.txt – dependencies for the builder app

##### Extract key architecture notes from README
- Streamlit front end + orchestration
- FAISS vector store for knowledge retrieval
- External LLM services (Groq Cloud, HuggingFace)
- GitHub API for one-click deployment

##### Main components & interactions
a. Frontend (Streamlit UI)
– Built in app.py – renders forms and buttons for each step
– Collects user inputs (profile data, tokens, repo name)
b. Profile Processor
– Validates form inputs, emits structured JSON
– Saves JSON to local storage (temp file or memory)
c. FAISS Index Builder
– Reads JSON, uses HuggingFace embeddings to build FAISS index
– Persists index locally (folder or file)
d. Chat Handler (RAG Service)
– rag_chatbot.py logic:
- Retrieves top-k docs from FAISS
- Calls LLMs (Groq Cloud API, HuggingFace model)
- Streams chat responses back to UI
e. Deployment Service (GitHub Deployer)
– Uses GitHub API + user’s tokens
– Generates new repo: pushes rag_chatbot.py + requirements.txt
– Returns URL for one-click Streamlit deployment

##### External services & data stores
- External LLM Services: Groq Cloud API, HuggingFace Inference API
- GitHub API – create repo + push code
- Local storage: JSON profile files, FAISS index files

##### Architectural patterns & principles
– Monolith subdivided into “layers”: UI layer, business-logic layer, data-layer
– Clear separation of concerns: profile build → indexing → retrieval/chat → deployment
– Externalize all long-running or stateful operations (vector store, GitHub push)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Index Layer
    subgraph "Build & Index"
        UI["Streamlit UI<br/>(app.py)"]:::internal
        Profile["Profile Processor<br/>(app.py)"]:::internal
        JSONStore[(Profile JSON Store)]:::datastore
        FAISSBuilder["FAISS Index Builder<br/>(app.py)"]:::internal
        FAISSStore[(FAISS Index Store)]:::datastore

        UI -->|"collects inputs"| Profile
        Profile -->|"JSON →"| JSONStore
        UI -->|"triggers indexing"| FAISSBuilder
        FAISSBuilder -->|"embeddings & vectors →"| FAISSStore
    end

    %% Serve & Deploy Layer
    subgraph "Serve & Deploy"
        ChatHandler["Chat Handler<br/>(rag_chatbot.py)"]:::internal
        LLM1(["Groq Cloud API"]):::external
        LLM2(["HuggingFace API"]):::external
        Deployment["Deployment Service<br/>(app.py)"]:::internal
        GitHubAPI(["GitHub API"]):::external
        NewRepo[/New Repo<br/>code + requirements/]:::datastore

        UI -->|"chat request"| ChatHandler
        ChatHandler -->|"reads index"| FAISSStore
        ChatHandler -->|"calls"| LLM1
        ChatHandler -->|"calls"| LLM2
        LLM1 -->|"response"| ChatHandler
        LLM2 -->|"response"| ChatHandler
        ChatHandler -->|"streams response"| UI

        UI -->|"deploy request"| Deployment
        Deployment -->|"uses tokens"| GitHubAPI
        GitHubAPI -->|"push code"| NewRepo
    end

    %% Deployed Chatbot Package
    subgraph "Deployed Chatbot Package"
        DeployedCode["rag_chatbot.py"]:::internal
        ReqDeployed[(requirements.txt)]:::datastore
        DeployedCode --> ReqDeployed
    end

    %% Dependencies
    ReqApp[(requirements.txt)]:::datastore

    %% Click Events
    click UI "https://github.com/vanshajr/chatsynth/blob/main/app.py"
    click Profile "https://github.com/vanshajr/chatsynth/blob/main/app.py"
    click FAISSBuilder "https://github.com/vanshajr/chatsynth/blob/main/app.py"
    click Deployment "https://github.com/vanshajr/chatsynth/blob/main/app.py"
    click ChatHandler "https://github.com/vanshajr/chatsynth/blob/main/deployed_files/rag_chatbot.py"
    click ReqApp "https://github.com/vanshajr/chatsynth/blob/main/requirements.txt"
    click ReqDeployed "https://github.com/vanshajr/chatsynth/blob/main/deployed_files/requirements.txt"

    %% Styles
    classDef internal fill:#add8e6,stroke:#000,stroke-width:1px
    classDef datastore fill:#d3d3d3,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#90ee90,stroke:#000,stroke-width:1px
```
