Services Documentation

Detailed technical documentation for each microservice in the TFG-Chatbot architecture.

Architecture Overview 

flowchart LR
    subgraph Frontend
        UI[React App :5173]
    end
    
    subgraph Backend["Backend Gateway"]
        API[FastAPI :8000]
    end
    
    subgraph AI["AI Layer"]
        Chatbot[Chatbot :8080]
        RAG[RAG Service :8081]
        Math[Math Service :8083]
    end
    
    subgraph Data
        MongoDB[(MongoDB :27017)]
        Qdrant[(Qdrant :6333)]
        Ollama[Ollama :11434]
    end
    
    UI --> API
    API --> Chatbot
    API --> Math
    Chatbot --> RAG
    Chatbot --> MongoDB
    Math --> RAG
    Math --> MongoDB
    Math --> Ollama
    RAG --> Qdrant
    RAG --> Ollama
    API --> MongoDB

Microservices

📁 Backend Gateway Service

Main API gateway with authentication, authorization, and request routing.

Document Description
README Overview and quick start
Architecture System design
API Endpoints 30+ endpoint reference
Authentication JWT, RBAC, security
Configuration Environment variables
Database MongoDB schema
Development Local setup
Deployment Production deployment

📁 Chatbot Service (NEW!)

LangGraph-powered AI conversational agent with RAG and interactive tests.

Document Description
README Overview and quick start
Architecture System design
API Endpoints Chat, test, analytics APIs
Configuration LLM providers, MongoDB
LangGraph Agent State machine, nodes, flows
Tools RAG, guias, test generation
Development Local setup, testing
Deployment Docker, production
INDEX Complete documentation index

Key Features:

  • 🧠 Multi-LLM support (Gemini, Mistral, vLLM)
  • 📚 RAG integration for document search
  • 📖 Teaching guide (guía docente) retrieval
  • 📝 Interactive test sessions with interrupts
  • 📊 Student profile tracking
  • 🔍 Phoenix observability + Prometheus metrics

� Frontend Service (NEW!)

React 19 + TypeScript + Vite user interface with role-based access.

Document Description
README Overview and quick start
Architecture Component structure, data flow
Components UI, chat, dashboard components
State Management Context, hooks, TanStack Query
Routing Routes, guards, navigation
Configuration Vite, TypeScript, Tailwind
Development Local setup, testing
Deployment Docker, nginx, production
INDEX Complete documentation index

Key Features:

  • ⚛️ React 19 with concurrent features
  • 🎨 Tailwind CSS 4 + shadcn/ui components
  • 🔐 Role-based routing (student/professor/admin)
  • 💬 Real-time chat with markdown rendering
  • 📊 Professor dashboard with analytics
  • 🔧 Admin panel for user/subject management

📄 RAG Service (NEW!)

Document processing and semantic search with Qdrant and Ollama embeddings.

Document Description
README Overview and quick start
Architecture System design and data flow
API Endpoints Complete API reference
Embeddings Ollama embedding service
Vector Store Qdrant integration
Document Processing Chunking and file loading
Configuration Environment variables
Development Local setup and testing
Deployment Docker and production
INDEX Complete documentation index

Key Features:

  • 🔍 Semantic search with Qdrant vector database
  • 🔢 Embedding generation via Ollama (nomic-embed-text)
  • 📄 Document upload and indexing (PDF, TXT, MD)
  • 🧩 Automatic text chunking for optimal retrieval
  • 📊 Prometheus metrics instrumentation
  • 🗂️ Subject-based document organization

📐 Math Service (NEW!)

Microservicio de análisis matemático: generación de FAQs automáticas y extracción de tópicos.

Document Description
README Overview and quick start
Architecture System design, components, data flow
API Endpoints Complete API reference with examples
Algorithms FCM, NMF, TF-IDF — mathematical foundations
Configuration Environment variables and settings
Development Local setup, tests, debugging
Deployment Docker, monitoring, production
INDEX Complete documentation index

Key Features:

  • 🔍 FAQ generation via Fuzzy C-Means clustering of student questions
  • 📊 Topic extraction with NMF over RAG documents
  • 🗺️ Concept map generation for professor dashboard
  • 📐 Integrates math_investigation/ algorithms (implemented from scratch)
  • 📈 Prometheus metrics + structured JSON logging
  • 🔎 Detailed health check (MongoDB, Ollama, RAG Service)

🏗️ Infrastructure (NEW!)

Docker orchestration, monitoring, logging, alerting, and CI/CD pipelines.

Document Description
README Overview and architecture
Docker Compose Service orchestration (15+ services)
Monitoring Prometheus, Grafana dashboards
Logging Loki, Promtail log aggregation
Alerting Alertmanager rules and routing
CI/CD GitHub Actions pipelines
INDEX Complete documentation index

Key Components:

  • 🐳 Docker Compose with 15+ services
  • 📈 Prometheus metrics collection
  • 📊 Grafana dashboards (system health, logs)
  • 📜 Loki + Promtail centralized logging
  • 🚨 Alertmanager with alert rules
  • 🔄 GitHub Actions (lint, test, build, security, release)
  • 🔬 Phoenix for LLM observability

Documentation Status

Service Status Docs
Backend ✅ Complete 11 files
Chatbot ✅ Complete 9 files
Frontend ✅ Complete 8 files
RAG Service ✅ Complete 10 files
Math Service ✅ Complete 1 file
Infrastructure ✅ Complete 7 files

For Developers

For DevOps

For API Consumers

Table of contents