# RagBot API - Architecture Diagrams ## System Architecture ``` ┌─────────────────────────────────────────────────────────────────┐ │ RagBot API Server │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────┐ ┌──────────────────────────┐ │ │ │ Cloud LLM API │◄─────────────┤ FastAPI Server │ │ │ │ (Groq/Gemini) │ LLM Calls │ Port: 8000 │ │ │ │ │ │ │ │ │ │ Models: │ │ Endpoints: │ │ │ │ - LLaMA 3.3-70B│ │ - /api/v1/health │ │ │ │ - Gemini Flash │ │ - /api/v1/biomarkers │ │ │ │ (or Ollama) │ │ - /api/v1/analyze/* │ │ │ └─────────────────┘ └───────────┬──────────────┘ │ │ │ │ │ ┌───────────▼──────────────┐ │ │ │ RagBot Core System │ │ │ │ (Imported Package) │ │ │ │ │ │ │ │ - 6 Specialist Agents │ │ │ │ - LangGraph Workflow │ │ │ │ - FAISS Vector Store │ │ │ │ - 2,609 medical chunks │ │ │ └──────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ ▲ │ HTTP Requests (JSON) │ │ ┌───────────┴────────────┐ │ Your Backend Server │ │ (Node.js/Python/etc) │ │ Port: 3000 │ │ │ │ - Receives frontend │ │ requests │ │ - Calls RagBot API │ │ - Returns results │ └───────────┬────────────┘ │ │ ┌───────────▼────────────┐ │ Your Frontend │ │ (React/Vue/etc) │ │ │ │ - User inputs data │ │ - Displays results │ │ - Shows analysis │ └────────────────────────┘ ``` --- ## 📡 Request Flow ### Natural Language Analysis Flow ``` User Types: "My glucose is 185 and HbA1c is 8.2" │ ▼ ┌────────────────────┐ │ Frontend (React) │ │ User Interface │ └─────────┬──────────┘ │ POST /api/analyze ▼ ┌────────────────────┐ │ Your Backend │ │ (Express/Flask) │ └─────────┬──────────┘ │ POST /api/v1/analyze/natural ▼ ┌─────────────────────────────────────┐ │ RagBot API (FastAPI) │ │ │ │ 1. Receive request │ │ {"message": "glucose 185..."} │ │ │ │ 2. Extract biomarkers │ │ ┌──────────────────┐ │ │ │ Extraction │ │ │ │ Service │ │ │ │ (LLM: llama3.1) │ │ │ └────────┬─────────┘ │ │ ▼ │ │ {"Glucose": 185, "HbA1c": 8.2} │ │ │ │ 3. Predict disease │ │ ┌──────────────────┐ │ │ │ Rule-based │ │ │ │ Predictor │ │ │ └────────┬─────────┘ │ │ ▼ │ │ {"disease": "Diabetes", ...} │ │ │ │ 4. Run RAG Workflow │ │ ┌──────────────────┐ │ │ │ RagBot Service │ │ │ │ (6 agents) │ │ │ └────────┬─────────┘ │ │ ▼ │ │ Full analysis response │ │ │ │ 5. Format response │ │ - Biomarker flags │ │ - Safety alerts │ │ - Recommendations │ │ - Disease explanation │ │ - Conversational summary │ │ │ └─────────┬───────────────────────────┘ │ JSON Response ▼ ┌────────────────────┐ │ Your Backend │ │ Processes data │ └─────────┬──────────┘ │ JSON Response ▼ ┌────────────────────┐ │ Frontend │ │ Displays results │ └────────────────────┘ ``` --- ## 🔄 Component Interaction ``` ┌───────────────────────────────────────────────────┐ │ FastAPI Application │ │ (app/main.py) │ │ │ │ ┌─────────────────────────────────────────────┐ │ │ │ Route Handlers │ │ │ │ │ │ │ │ /health /biomarkers /analyze/* │ │ │ │ │ │ │ │ │ │ └────┼───────────────┼──────────────┼─────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌─────────┐ ┌─────────┐ ┌──────────────┐ │ │ │ Health │ │Biomarker│ │ Analyze │ │ │ │ Route │ │ Route │ │ Route │ │ │ └─────────┘ └─────────┘ └──────┬───────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────┐ │ │ │ Services Layer │ │ │ │ │ │ │ │ ┌───────────────┐ │ │ │ │ │ Extraction │ │ │ │ │ │ Service │ │ │ │ │ └───────┬───────┘ │ │ │ │ │ │ │ │ │ ┌───────▼───────┐ │ │ │ │ │ RagBot │ │ │ │ │ │ Service │ │ │ │ │ └───────┬───────┘ │ │ │ └──────────┼─────────┘ │ │ │ │ └─────────────────────────────────────┼───────────┘ │ ▼ ┌────────────────────────┐ │ RagBot Core System │ │ (src/workflow.py) │ │ │ │ ┌──────────────────┐ │ │ │ 6 Agent Workflow │ │ │ │ (LangGraph) │ │ │ └──────────────────┘ │ │ │ │ ┌──────────────────┐ │ │ │ Vector Store │ │ │ │ (FAISS) │ │ │ └──────────────────┘ │ └────────────────────────┘ ``` --- ## 📊 Data Flow ### Request → Response Journey ``` 1. INPUT (from user) ┌─────────────────────────────────┐ │ "My glucose is 185 and HbA1c │ │ is 8.2, I'm 52 years old" │ └─────────────────────────────────┘ │ ▼ 2. EXTRACTION (LLM Processing) ┌─────────────────────────────────┐ │ Biomarkers: │ │ - Glucose: 185.0 │ │ - HbA1c: 8.2 │ │ Context: │ │ - age: 52 │ └─────────────────────────────────┘ │ ▼ 3. PREDICTION (Rule-based) ┌─────────────────────────────────┐ │ Disease: Diabetes │ │ Confidence: 0.87 (87%) │ │ Probabilities: │ │ - Diabetes: 87% │ │ - Heart Disease: 8% │ │ - Others: 5% │ └─────────────────────────────────┘ │ ▼ 4. WORKFLOW (6 Agents Execute) ┌─────────────────────────────────┐ │ Agent 1: Biomarker Analyzer │ │ ✓ Validates 2 biomarkers │ │ ✓ Flags: 2 out of range │ │ ✓ Alerts: 2 critical │ └─────────────────────────────────┘ ┌─────────────────────────────────┐ │ Agent 2: Disease Explainer (RAG)│ │ ✓ Retrieved 5 medical docs │ │ ✓ Citations: 5 sources │ │ ✓ Pathophysiology explained │ └─────────────────────────────────┘ ┌─────────────────────────────────┐ │ Agent 3: Biomarker Linker (RAG) │ │ ✓ Linked 2 key drivers │ │ ✓ Evidence from literature │ └─────────────────────────────────┘ ┌─────────────────────────────────┐ │ Agent 4: Guidelines (RAG) │ │ ✓ Retrieved 3 guidelines │ │ ✓ Recommendations: 5 actions │ └─────────────────────────────────┘ ┌─────────────────────────────────┐ │ Agent 5: Confidence Assessor │ │ ✓ Reliability: MODERATE │ │ ✓ Evidence: STRONG │ │ ✓ Limitations: 2 noted │ └─────────────────────────────────┘ ┌─────────────────────────────────┐ │ Agent 6: Response Synthesizer │ │ ✓ Compiled all findings │ │ ✓ Structured output │ │ ✓ Conversational summary │ └─────────────────────────────────┘ │ ▼ 5. OUTPUT (to user) ┌─────────────────────────────────┐ │ Full JSON Response: │ │ │ │ - prediction │ │ - biomarker_flags │ │ - safety_alerts │ │ - key_drivers │ │ - disease_explanation │ │ - recommendations │ │ - confidence_assessment │ │ - agent_outputs │ │ - conversational_summary │ │ │ │ Processing time: 3.5 seconds │ └─────────────────────────────────┘ ``` --- ## 🎯 API Endpoint Map ``` RagBot API Root: http://localhost:8000 │ ├── / GET API info │ ├── /docs GET Swagger UI │ ├── /redoc GET ReDoc │ └── /api/v1/ │ ├── /health GET System status │ Returns: { │ status: "healthy", │ ollama_status: "connected", │ vector_store_loaded: true │ } │ ├── /biomarkers GET List all biomarkers │ Returns: { │ biomarkers: [...], │ total_count: 24 │ } │ └── /analyze/ │ ├── /natural POST Natural language │ Input: { │ message: "glucose 185...", │ patient_context: {...} │ } │ Output: Full analysis │ ├── /structured POST Direct biomarkers │ Input: { │ biomarkers: {...}, │ patient_context: {...} │ } │ Output: Full analysis │ └── /example GET Demo case Output: Full analysis ``` --- ## 🔌 Integration Points ``` ┌────────────────────────────────────────────────┐ │ Your Application Stack │ ├────────────────────────────────────────────────┤ │ │ │ Frontend (React/Vue/Angular) │ │ ┌──────────────────────────────────────────┐ │ │ │ User inputs: "glucose 185, HbA1c 8.2" │ │ │ │ Button click: "Analyze" │ │ │ └──────────────┬───────────────────────────┘ │ │ │ HTTP POST │ │ ▼ │ │ Backend (Node.js/Python/Java) │ │ ┌──────────────────────────────────────────┐ │ │ │ Endpoint: POST /api/analyze │ │ │ │ │ │ │ │ Code: │ │ │ │ const result = await fetch( │ │ │ │ 'http://localhost:8000/api/v1/ │ │ │ │ analyze/natural', │ │ │ │ {body: {message: userInput}} │ │ │ │ ); │ │ │ │ │ │ │ │ return result.data; │ │ │ └──────────────┬───────────────────────────┘ │ │ │ HTTP POST │ │ ▼ │ │ ┌──────────────────────────────────────────┐ │ │ │ RagBot API (localhost:8000) │◄─┼─ This is what we built! │ │ │ │ │ │ - Extracts biomarkers │ │ │ │ - Runs analysis │ │ │ │ - Returns JSON │ │ │ └──────────────┬───────────────────────────┘ │ │ │ JSON Response │ │ ▼ │ │ Backend processes and returns to frontend │ │ │ │ │ ▼ │ │ Frontend displays results to user │ │ │ └────────────────────────────────────────────────┘ ``` --- ## 💾 File Structure ``` api/ │ ├── app/ # Application code │ ├── __init__.py │ ├── main.py # FastAPI app (entry point) │ │ │ ├── models/ # Data schemas │ │ ├── __init__.py │ │ └── schemas.py # Pydantic models │ │ │ ├── routes/ # API endpoints │ │ ├── __init__.py │ │ ├── health.py # Health check │ │ ├── biomarkers.py # List biomarkers │ │ └── analyze.py # Analysis endpoints │ │ │ └── services/ # Business logic │ ├── __init__.py │ ├── extraction.py # Natural language extraction │ └── ragbot.py # Workflow orchestration │ ├── .env # Configuration ├── .env.example # Template ├── .gitignore # Git ignore rules ├── requirements.txt # Python dependencies ├── Dockerfile # Container image ├── docker-compose.yml # Deployment config │ └── Documentation/ ├── README.md # Complete guide ├── GETTING_STARTED.md # Quick start ├── QUICK_REFERENCE.md # Cheat sheet └── ARCHITECTURE.md # This file ``` --- **Created:** November 23, 2025 **Purpose:** Visual guide to RagBot API architecture **For:** Understanding system design and integration points