Architecture Decision Records (ADR)

This folder contains ADRs — human-readable records of important architecture decisions.

Purpose

• Keep a lightweight history of why important technical decisions were made.
• Make it easier to review, revisit and evolve decisions.

How to name ADR files

• Use a four-digit sequence and a short slug, e.g. 0001-use-postgres-for-persistence.md.

Template

• Use adr-template.md as a starting point.

Quick workflow

1. Create a new ADR with the provided script: scripts/new_adr.sh "Short title".
2. Edit the file, fill Context/Decision/Consequences.
3. Commit the ADR in the same PR that introduces the corresponding architectural change.

Guidelines

• Keep ADRs brief and focused on why, not how.
• Record alternatives considered and the trade-offs.

---

Table of contents

• Use FastAPI for the project API
• Use LangChain / LangGraph for orchestration of LLM+tool flows
• Use Docker for containerization in development/CI
• Use Docker for containerization in development/CI
• Use SQLite for graph memory storage
• Use Pydantic for data models and validation
• Use pytest for testing
• Use vLLM for high-throughput, low-latency inference where applicable
• Use Ollama for local model serving embeddings model (RAG)
• Use Qdrant for vector storage and similarity search
• ADR 0010 — Use MongoDB to store 'guía docente' JSON for the agent tool
• Use uv for virtual environments and dependency management
• Use Ruff for linting
• Use Mypy for static type checking
• Use Black for code formatting
• Use isort for import sorting
• Merge Auth Service into Gateway
• Implement Role-Based Access Control (RBAC)
• Use JWT for Stateless Authentication
• Custom Authentication Implementation
• Use React and Vite for Frontend
• Use Tailwind CSS for Styling
• Use Shadcn/ui for UI Components
• Use TanStack Query for Data Fetching
• Use React Router for Navigation
• Use Zod and React Hook Form for Forms
• Use biome for frontend linting
• Use vitest for frontend testing
• Use pydantic-settings for configuration management
• Shared MongoDB instance with separate collections per service
• Use Phoenix for LLM Observability
• Use Prometheus for Infrastructure Metrics
• Use JSON Structured Logging
• Use Grafana for Visualization
• Use AlertManager for Alerting
• Adaptive Chain-of-Thought Prompting
• K-Means vs Fuzzy C-Means for Question Clustering
• Student Knowledge Profile Schema
• Math Service como Microservicio Independiente
• Estrategia de Integración de math_investigation en Producción