# ridabayi/medical-rag-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/ridabayi/medical-rag-chatbot
- Repository: https://github.com/ridabayi/medical-rag-chatbot

## Overview

##### Project Type and Purpose
- This is a full-stack RAG (Retrieval-Augmented Generation) chatbot specialized for medical content.
- It ingests medical PDFs, builds a vector index (FAISS), runs a backend API that queries an LLM, and serves a web UI.
- CI/CD is managed by Jenkins in Docker-in-Docker, with automated container image build, security scan (Trivy), push to AWS ECR, and deployment to AWS App Runner.

##### File Structure Analysis
- Top-level:
- Dockerfile / Jenkinsfile / custom_jenkins/Dockerfile: container definitions for the app and Jenkins.
- data/: raw PDF source.
- vectorstore/: persisted FAISS index.
- app/: core Python code.
- Within app/:
- application.py: Flask/FastAPI server entry point.
- common/: shared utilities (logging, exception handling).
- components/: ingest (data_loader, pdf_loader), vector build (embeddings, vector_store), retrieval (retriever), LLM integration (llm).
- config/: centralized configuration.
- templates/: HTML UI.
- setup.py & requirements.txt: packaging & dependencies.

##### README Insights
- Describes local setup, Jenkins CI pipeline, Docker, Trivy, AWS ECR, AWS App Runner.
- Highlights stages: checkout, build, scan, push, deploy.
- References AWS IAM roles and credentials.

##### Main Components
a. Frontend Web UI
- Browser → index.html served by the backend.
b. Backend API
- Flask/FastAPI application (application.py).
- Endpoints: “/chat” calls retriever & llm components.
c. Data Ingestion & Vector Store
- PDF loader → data_loader → embeddings → FAISS vector_store.
- Persisted on disk (vectorstore/db_faiss).
d. LLM Service
- External OpenAI or other LLM endpoint.
e. CI/CD Pipeline
- GitHub repo → Jenkins (custom_jenkins).
- Stages: Checkout → Docker build → Trivy scan → Push to AWS ECR → Deploy to AWS App Runner.
f. AWS Infrastructure
- ECR: container registry.
- App Runner: container deployment runtime.
- IAM: credentials for Jenkins to push/deploy.
- (Optionally) Secrets Manager for tokens.

##### Relationships & Data Flow
- Data Flow:
1. Admin drops PDF in data/ → ingestion pipeline populates FAISS.
2. User types query in UI → HTTP request to backend.
3. Backend uses retriever against FAISS → gets context.
4. Context + query sent to LLM → response returned.
5. Response sent back to UI.
- CI/CD Flow:
1. Code push to GitHub triggers Jenkins.
2. Jenkins container builds Docker image.
3. Trivy scans image; on success → tag & push to AWS ECR.
4. Jenkins invokes AWS CLI to update App Runner service.
- User → Browser → Backend.
- Backend → Vector Store & LLM.
- GitHub → Jenkins → ECR → App Runner.

##### Architectural Patterns & Design Principles
- Modular separation: ingestion, retrieval, LLM, API, UI.
- Single-responsibility components in app/components.
- Configuration centralization in app/config.
- Infrastructure as code via Dockerfiles and Jenkinsfile.
- Immutable container images and automated deployments.

##### Technologies & Frameworks
- Python (Flask or FastAPI).
- FAISS for vector search.
- OpenAI (or other) LLM API.
- Docker & Docker-in-Docker.
- Jenkins for CI/CD.
- Trivy for security scanning.
- AWS ECR & App Runner for container hosting.
- (Optionally AWS IAM, AWS CLI).

##### Advanced AWS Deployment Layer
- Jenkins container with AWS credentials deployed on-prem or in Docker.
- AWS App Runner pulling the image and running the service behind a load-balanced endpoint.
- IAM roles & policies linked to Jenkins.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User & UI"
        User["User"]:::external
        Browser["Browser"]:::frontend
        UI["Web UI<br/>index.html"]:::frontend
    end

    subgraph "Backend Services"
        API["API Server<br/>application.py"]:::frontend
        Retriever["Retriever"]:::frontend
        LLMComp["LLM Integration"]:::frontend
        Logger["Logger"]:::frontend
        Exception["Exception Handler"]:::frontend
        Config["Configuration"]:::frontend
    end

    subgraph "Data Layer"
        PDF["PDF Loader"]:::frontend
        DataLoad["Data Loader"]:::frontend
        Embeddings["Embeddings"]:::frontend
        VecModule["FAISS Module"]:::frontend
        VecStore["FAISS Index"]:::storage
    end

    subgraph "CI/CD & Deployment"
        GH["GitHub Repo"]:::ci
        Jenkins["Jenkins"]:::ci
        JenkinsDocker["Jenkins Container Setup"]:::ci
        BuildImg["Docker Build<br/>Dockerfile"]:::ci
        Trivy["Trivy Scan"]:::ci
        PushECR["Push to ECR"]:::ci
        JenkinsfileComp["Jenkinsfile"]:::ci
    end

    subgraph "AWS Cloud"
        ECR["ECR Repository"]:::external
        AppRunner["App Runner"]:::external
        IAM["IAM Roles"]:::external
        Secrets["Secrets Manager"]:::external
        ExtLLM["LLM API"]:::external
    end

    %% User & UI -> Backend
    User --> Browser
    Browser --> UI
    UI --> API

    %% Backend internals
    API --> Retriever
    API --> LLMComp
    API --> VecModule
    API -.-> Config
    API -.-> Logger
    API -.-> Exception

    %% Data ingestion pipeline
    PDF --> DataLoad
    DataLoad --> Embeddings
    Embeddings --> VecModule
    VecModule --> VecStore

    %% Retrieval & LLM calls
    Retriever --> VecStore
    LLMComp -->|"calls LLM API"| ExtLLM

    %% CI/CD flow
    GH --> Jenkins
    Jenkins --> JenkinsDocker
    Jenkins --> BuildImg
    Jenkins --> Trivy
    Trivy --> PushECR
    PushECR --> ECR
    Jenkins -->|"deploy"| AppRunner
    IAM -.-> Jenkins
    Secrets -.-> Jenkins

    %% Click Events
    click UI "https://github.com/ridabayi/medical-rag-chatbot/blob/main/app/templates/index.html"
    click API "https://github.com/ridabayi/medical-rag-chatbot/blob/main/app/application.py"
    click PDF "https://github.com/ridabayi/medical-rag-chatbot/blob/main/app/components/pdf_loader.py"
    click DataLoad "https://github.com/ridabayi/medical-rag-chatbot/blob/main/app/components/data_loader.py"
    click Embeddings "https://github.com/ridabayi/medical-rag-chatbot/blob/main/app/components/embeddings.py"
    click VecModule "https://github.com/ridabayi/medical-rag-chatbot/blob/main/app/components/vector_store.py"
    click VecStore "https://github.com/ridabayi/medical-rag-chatbot/tree/main/vectorstore/db_faiss/"
    click Retriever "https://github.com/ridabayi/medical-rag-chatbot/blob/main/app/components/retriever.py"
    click LLMComp "https://github.com/ridabayi/medical-rag-chatbot/blob/main/app/components/llm.py"
    click Logger "https://github.com/ridabayi/medical-rag-chatbot/blob/main/app/common/logger.py"
    click Exception "https://github.com/ridabayi/medical-rag-chatbot/blob/main/app/common/custom_exception.py"
    click Config "https://github.com/ridabayi/medical-rag-chatbot/blob/main/app/config/config.py"
    click JenkinsfileComp "https://github.com/ridabayi/medical-rag-chatbot/tree/main/Jenkinsfile"
    click JenkinsDocker "https://github.com/ridabayi/medical-rag-chatbot/tree/main/custom_jenkins/Dockerfile"
    click BuildImg "https://github.com/ridabayi/medical-rag-chatbot/tree/main/Dockerfile"

    %% Styles
    classDef frontend fill:#add8e6,stroke:#333,stroke-width:1px
    classDef storage fill:#90ee90,stroke:#333,stroke-width:1px
    classDef external fill:#ffa500,stroke:#333,stroke-width:1px
    classDef ci fill:#d3d3d3,stroke:#333,stroke-width:1px
```
