# shalha-mucha18/ragmed architecture

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

- Interactive diagram: https://gitdiagram.com/shalha-mucha18/ragmed
- Repository: https://github.com/shalha-mucha18/ragmed

## Overview

##### Project Type and Purpose
- This is a full-stack RAG-enabled chat application for the medical domain.
- Frontend: Streamlit chat UI for uploading PDFs and asking questions.
- Backend: FastAPI service that handles PDF ingestion, vector embedding, Pinecone DB integration, and LLM invocation.
- Purpose: Allow users to upload private medical documents, index them semantically, and get accurate LLM-generated answers grounded in their own data.

##### File Structure
- Top-level:
- client/      → Streamlit frontend
- server/      → FastAPI backend
- main.py      → Entrypoint orchestrating client and server (if any glue logic)
- client/
- app.py       → Streamlit application startup
- components/  → chatUI, history, upload widgets
- utils/api.py → HTTP calls to backend
- config.py    → client-side configuration (API URLs, keys)
- server/
- main.py              → FastAPI app initialization
- routes/              → API endpoints (upload_pdfs, ask_question)
- modules/             → Core business logic
– pdf_manage.py    → PDF parsing & chunking
– vectorstore.py   → Pinecone integration
– llm.py           → LLM (Groq LLaMA3-70B) calls
– query_manage.py  → Retrieval + generation orchestration
- middlewares/         → Exception handling
- uploaded_files/      → Raw PDF storage
- logger.py            → Custom logging
- test.py              → Basic tests
- Config/build files:
- pyproject.toml, requirements.txt, .gitignore

##### README for Additional Insights
- RAG pipeline with:
1. PDF upload → semantic chunking
2. Embeddings via Google GenAI / BGE
3. Indexing & retrieval in Pinecone
4. Contextual answer generation by LLaMA3-70B
- Tech Stack highlights exactly these components.

a. Main Components
- Client (Streamlit UI)
- API Gateway / FastAPI Server
- PDF Storage (uploaded_files)
- PDF Processor (pdf_manage module)
- Embedding Service (Google GenAI / BGE)
- Vector Database (Pinecone – vectorstore module)
- Retrieval & Orchestration (query_manage module)
- LLM Engine (Groq LLaMA3-70B via llm module)
- Logging & Middleware
b. Relationships & Interactions
1. User interacts with Streamlit UI → HTTP request to FastAPI endpoint
2. Upload flow:
- upload_pdfs route → pdf_manage splits & preprocesses PDF → send chunks to Embedding Service → vectorstore indexes chunks in Pinecone → store raw PDF
3. Query flow:
- ask_question route → query_manage retrieves top-k chunks from Pinecone → llm module receives context + question → LLM generates answer → returned to client
4. Middlewares wrap each request for error handling & logging
c. Architectural Patterns / Design Principles
- Separation of concerns: clear divisions between UI, API layer, business logic modules, data persistence.
- API-First: all interactions via defined FastAPI routes.
- Modular RAG pipeline: ingest → embed → store → retrieve → generate.
- Pluggable external services: Pinecone, Google GenAI, Groq LLaMA.
d. Technologies / Frameworks
- Streamlit (client)
- FastAPI (server)
- LangChain (orchestrator library)
- Pinecone (Vector DB)
- Google Generative AI / BGE (Embeddings)
- Groq LLaMA3-70B (LLM)
- Python 3.11

##### Detail Without Over-Splitting
- Essential components (UI, API, business logic, data storage, external services).
- Avoid drawing every single file; instead, group by responsibility.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        UI["Streamlit UI"]:::frontend
        ChatUI["Chat Interface Component"]:::frontend
        UploadWidget["Upload Widget Component"]:::frontend
        History["Chat History Component"]:::frontend
        APIUtils["HTTP Utilities"]:::frontend
        Config["Client Configuration"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        Orchestrator["API Entry Point / Orchestrator"]:::backend
        FastAPIApp["FastAPI App Initialization"]:::backend
        subgraph "Routes"
            direction TB
            UploadRoute["Upload PDFs Endpoint"]:::backend
            AskRoute["Ask Question Endpoint"]:::backend
        end
        subgraph "Modules"
            direction TB
            PDFManage["PDF Ingestion & Chunking Module"]:::backend
            VectorStore["Embedding & Pinecone Integration Module"]:::backend
            QueryManage["Retrieval & Generation Orchestration Module"]:::backend
            LLMInvoke["LLM Invocation Module"]:::backend
        end
        Middleware["Exception Handling Middleware"]:::backend
        Logger["Custom Logging Utility"]:::backend
        Storage["Raw PDF Storage Directory"]:::backend
        Tests["Basic Backend Tests"]:::backend
    end

    %% External Services
    subgraph "External Systems"
        direction TB
        EmbeddingService["Google GenAI / BGE"]:::external
        PineconeDB["Pinecone Vector DB"]:::external
        LLMEngine["Groq LLaMA3-70B Engine"]:::external
    end

    %% User Interaction
    User["User"]:::external

    %% Connections - Upload Flow (dashed blue)
    User -->|"uploads PDF"| UI
    UI -->|"calls upload() (HTTP)"| APIUtils
    APIUtils -->|"POST /upload_pdfs"| FastAPIApp
    FastAPIApp -->|"routes through"| UploadRoute
    UploadRoute -->|"<chunk PDF>"| PDFManage
    PDFManage -->|"send chunks"| EmbeddingService
    EmbeddingService -->|"embeddings"| VectorStore
    VectorStore -->|"index chunks"| PineconeDB
    UploadRoute -->|"store raw file"| Storage

    %% Connections - Query Flow (solid green)
    User -->|"asks question"| UI
    UI -->|"calls ask_question() (HTTP)"| APIUtils
    APIUtils -->|"POST /ask_question"| FastAPIApp
    FastAPIApp -->|"routes through"| AskRoute
    AskRoute -->|"retrieve chunks"| QueryManage
    QueryManage -->|"query top-k"| PineconeDB
    QueryManage -->|"prepare context"| LLMInvoke
    LLMInvoke -->|"invoke LLM"| LLMEngine
    LLMEngine -->|"answer"| LLMInvoke
    LLMInvoke -->|"response"| QueryManage
    QueryManage -->|"return answer"| AskRoute

    %% Cross-cutting Concerns
    FastAPIApp --> Middleware
    Middleware --> Logger

    %% Orchestration Entry
    Orchestrator --> FastAPIApp

    %% Tests
    Tests --> FastAPIApp

    %% Click Events
    click UI "https://github.com/shalha-mucha18/ragmed/blob/main/client/app.py"
    click ChatUI "https://github.com/shalha-mucha18/ragmed/blob/main/client/components/chatUI/chatUI.py"
    click UploadWidget "https://github.com/shalha-mucha18/ragmed/blob/main/client/components/upload.py"
    click History "https://github.com/shalha-mucha18/ragmed/blob/main/client/components/history.py"
    click APIUtils "https://github.com/shalha-mucha18/ragmed/blob/main/client/utils/api.py"
    click Config "https://github.com/shalha-mucha18/ragmed/blob/main/client/config.py"
    click Orchestrator "https://github.com/shalha-mucha18/ragmed/blob/main/main.py"
    click FastAPIApp "https://github.com/shalha-mucha18/ragmed/blob/main/server/main.py"
    click UploadRoute "https://github.com/shalha-mucha18/ragmed/blob/main/server/routes/upload_pdfs.py"
    click AskRoute "https://github.com/shalha-mucha18/ragmed/blob/main/server/routes/ask_qestion.py"
    click PDFManage "https://github.com/shalha-mucha18/ragmed/blob/main/server/modules/pdf_manage.py"
    click VectorStore "https://github.com/shalha-mucha18/ragmed/blob/main/server/modules/vectorstore.py"
    click LLMInvoke "https://github.com/shalha-mucha18/ragmed/blob/main/server/modules/llm.py"
    click QueryManage "https://github.com/shalha-mucha18/ragmed/blob/main/server/modules/query_mange.py"
    click Middleware "https://github.com/shalha-mucha18/ragmed/blob/main/server/middlewares/exception_handlers.py"
    click Logger "https://github.com/shalha-mucha18/ragmed/blob/main/server/logger.py"
    click Storage "https://github.com/shalha-mucha18/ragmed/tree/main/server/uploaded_files/"
    click Tests "https://github.com/shalha-mucha18/ragmed/blob/main/server/test.py"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000;
    classDef backend fill:#90EE90,stroke:#000;
    classDef external fill:#DDA0DD,stroke:#000;
    classDef dashedArrow stroke-dasharray: 5 5,stroke:#1E90FF;
    classDef solidArrow stroke:#228B22;
```
