# joychudasama/chat-txt architecture

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

- Interactive diagram: https://gitdiagram.com/joychudasama/chat-txt
- Repository: https://github.com/joychudasama/chat-txt

## Overview

##### Project type and purpose
- ChatTXT is a full‑stack web application for interactive AI chat over user‑uploaded TXT documents.
- Frontend is built in React/TypeScript with Tailwind and custom UI components; backend is a Python FastAPI service using Langchain, Ollama LLM, and Firebase/Firestore.

##### Main architectural components
a. Frontend
- React SPA (App.tsx, components folder)
- UI library: Shadcn/ui + Tailwind CSS
- WebSocketContext for live chat or REST calls for upload/auth/session
b. Backend
- FastAPI application (backend/app/main.py)
- API router grouping v1 endpoints (auth, chat, file_upload, session)
- Layered packages:
– core: app setup, configuration
– db: Firestore connector
– models: Pydantic request/response schemas
– prompts: prebuilt query templates (qa_prompts)
– services: business logic (file_service, rag_service, session_service, vector_store_service)
c. Data stores & external services
- Firestore: user/session data, chat history, metadata, possibly embedded vectors
- Ollama: local LLM for text completion/inference
- (Implicit) vector store via Langchain wrapper on Firestore
d. Client-browser interactions
- HTTP(S) REST calls for file upload, session management, standard chat
- WebSocket (optional) for real‑time chat UI updates

##### Relationships & data flows
- User → Frontend UI →
- POST /file_upload → backend.file_service → vector_store_service → Langchain embedding → Firestore
- POST /chat → backend.rag_service → vector_store_service (Firestone or metadata index) → Ollama LLM → response → Firestore (session & history) → frontend
- GET/POST /session → session_service → Firestore
- Frontend subscribes to WebSocketContext for streaming chat messages
- All components interact over well‑defined API endpoints

##### Architectural patterns & design principles
- Layered architecture: API routers (controllers) → services (business logic) → data layer (db/vector store)
- Dependency inversion: core/config drives service instantiation
- Separation of concerns: prompts templates are decoupled from service logic
- Extensibility: new endpoints or services can be plugged into the same router/service structure

##### Technologies & frameworks callouts
- Frontend: React, TypeScript, Vite, Tailwind, Shadcn/ui, Zod for validation
- Backend: FastAPI, Pydantic, Langchain, Ollama API, Firebase Admin SDK for Firestore
- Dev tooling: ESLint, TypeScript configs, Python requirements.txt, .env examples

- Notes on protocols (HTTP, WebSocket)
- Environment/config layer feeding into core/app_setup

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Tier
    subgraph "Client (Browser)"
        direction TB
        App["App.tsx"]:::frontend
        Components["UI Components"]:::frontend
        ShadcnUI["Shadcn/ui & Tailwind"]:::frontend
        WebSocketCtx["WebSocketContext"]:::frontend
        ChatTypes["chat.ts Types"]:::frontend
    end

    %% API Layer
    subgraph "API Layer (FastAPI)" 
        direction TB
        Main["main.py"]:::backend
        Routes["v1 Routes"]:::backend
        subgraph "Endpoints"
            direction TB
            AuthEP["auth.py"]:::backend
            ChatEP["chat.py"]:::backend
            FileEP["file_upload.py"]:::backend
            SessionEP["session.py"]:::backend
        end
        subgraph "Core"
            direction TB
            AppSetup["app_setup.py"]:::backend
            Config["config.py"]:::backend
        end
        subgraph "Models"
            direction TB
            ChatMsgModel["chat_message.py"]:::backend
            ChatRespModel["chat_response.py"]:::backend
            FileRespModel["file_upload_response.py"]:::backend
        end
        subgraph "Prompts"
            direction TB
            QAPrompts["qa_prompts.py"]:::backend
        end
        subgraph "Services"
            direction TB
            FileSvc["file_service.py"]:::backend
            RAGSvc["rag_service.py"]:::backend
            SessionSvc["session_service.py"]:::backend
            VectorSvc["vector_store_service.py"]:::backend
        end
        DBConn["firestore.py"]:::backend
    end

    %% Data & AI Services
    subgraph "Data & AI Services"
        direction TB
        Firestore["Firestore"]:::external
        Ollama["Ollama LLM"]:::external
    end

    %% Data Flows
    App -->|"HTTP POST /file_upload"| FileEP
    App -->|"HTTP POST /chat"| ChatEP
    App -->|"HTTP GET/POST /session"| SessionEP
    WebSocketCtx -->|"WebSocket"| ChatEP

    Main --> Routes
    Routes --> AuthEP
    Routes --> ChatEP
    Routes --> FileEP
    Routes --> SessionEP

    AuthEP -->|"calls"| SessionSvc
    FileEP -->|"TXT file → chunks"| FileSvc
    FileSvc --> VectorSvc
    VectorSvc -->|"embeddings"| Firestore

    ChatEP -->|"query + context"| RAGSvc
    RAGSvc --> VectorSvc
    RAGSvc --> QAPrompts
    RAGSvc --> Ollama
    Ollama --> ChatRespModel
    ChatEP -->|"response storage"| Firestore

    SessionEP --> SessionSvc
    SessionSvc --> Firestore

    Main --> AppSetup
    AppSetup --> Config
    FileEP --> ChatMsgModel
    ChatEP --> ChatMsgModel
    ChatEP --> ChatRespModel
    FileEP --> FileRespModel

    %% Click Events
    click App "https://github.com/joychudasama/chat-txt/blob/main/frontend/src/App.tsx"
    click Components "https://github.com/joychudasama/chat-txt/tree/main/frontend/src/components"
    click ShadcnUI "https://github.com/joychudasama/chat-txt/tree/main/frontend/src/components/ui"
    click WebSocketCtx "https://github.com/joychudasama/chat-txt/blob/main/frontend/src/contexts/WebSocketContext.tsx"
    click ChatTypes "https://github.com/joychudasama/chat-txt/blob/main/frontend/src/types/chat.ts"
    click Main "https://github.com/joychudasama/chat-txt/blob/main/backend/app/main.py"
    click Routes "https://github.com/joychudasama/chat-txt/blob/main/backend/app/api/v1/routes.py"
    click AuthEP "https://github.com/joychudasama/chat-txt/blob/main/backend/app/api/v1/endpoints/auth.py"
    click ChatEP "https://github.com/joychudasama/chat-txt/blob/main/backend/app/api/v1/endpoints/chat.py"
    click FileEP "https://github.com/joychudasama/chat-txt/blob/main/backend/app/api/v1/endpoints/file_upload.py"
    click SessionEP "https://github.com/joychudasama/chat-txt/blob/main/backend/app/api/v1/endpoints/session.py"
    click AppSetup "https://github.com/joychudasama/chat-txt/blob/main/backend/app/core/app_setup.py"
    click Config "https://github.com/joychudasama/chat-txt/blob/main/backend/app/core/config.py"
    click DBConn "https://github.com/joychudasama/chat-txt/blob/main/backend/app/db/firestore.py"
    click ChatMsgModel "https://github.com/joychudasama/chat-txt/blob/main/backend/app/models/chat_messge.py"
    click ChatRespModel "https://github.com/joychudasama/chat-txt/blob/main/backend/app/models/chat_response.py"
    click FileRespModel "https://github.com/joychudasama/chat-txt/blob/main/backend/app/models/file_upload_response.py"
    click QAPrompts "https://github.com/joychudasama/chat-txt/blob/main/backend/app/prompts/qa_prompts.py"
    click FileSvc "https://github.com/joychudasama/chat-txt/blob/main/backend/app/services/file_service.py"
    click RAGSvc "https://github.com/joychudasama/chat-txt/blob/main/backend/app/services/rag_service.py"
    click SessionSvc "https://github.com/joychudasama/chat-txt/blob/main/backend/app/services/session_service.py"
    click VectorSvc "https://github.com/joychudasama/chat-txt/blob/main/backend/app/services/vector_store_service.py"

    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef backend fill:#E6FFE6,stroke:#028A0F,stroke-width:1px
    classDef external fill:#FFE6CC,stroke:#FF8C00,stroke-width:1px
```
