Spaces:
Running
Running
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