# mathis-lambert/api architecture

> Architecture diagram of the GitHub repository mathis-lambert/api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mathis-lambert/api
- Repository: https://github.com/mathis-lambert/api

## Overview

##### Project Type and Purpose
- This is a standalone, versioned backend API microservice built with Python 3.13 and FastAPI.
- It serves as the core API infrastructure under `api.mathislambert.fr`, exposing endpoints for health checks, LLM‐powered chat, data CRUD in MongoDB, and RAG queries in Qdrant.
- It is containerized (Docker, docker‑compose), reverse‑proxied by Nginx, and integrates with external LLM (MistralAI).

##### High‑Level Architecture Components
- Clients: browsers or other services calling REST endpoints.
- Nginx Reverse Proxy: routes incoming HTTP(S) traffic to the FastAPI service.
- FastAPI/Uvicorn Container: hosts the application code (`src/api/...`).
- Router layer (`v1/routes`)
- Service layer (`v1/services`, `api/classes`, `api/utils`)
- Database connectors (`mongo_db_connector`, `qdrant_connector`)
- Databases (each in its own container via docker‑compose):
- MongoDB (NoSQL document store)
- Qdrant (vector database for RAG)
- External Service: MistralAI API for text generation.
- Networking/Orchestration: docker‑compose, environment variables, init scripts (Mongo init‑db.js, Qdrant config.yaml).

##### Component Interactions and Data Flows
- Inside FastAPI:
- Request hits versioned router (e.g., `/v1/chat`).
- Router calls service layer (e.g., `chat_service`).
- Service may call:
– MongoDB connector for data I/O
– Qdrant connector for vector retrieval
– MistralAI (external HTTPS call) for text generation
- Responses bubble back through the same layers to the client.

##### Architectural Patterns and Principles
- Layered/Clean Architecture: routers (interface) → services (business) → connectors (persistence) → external integrations.
- Dependency Injection: connectors and services instantiated in `main.py` and injected via routers.
- Containerization & Infrastructure as Code: Dockerfiles, docker‑compose, Nginx config, DB init scripts.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    Client["Client (Browser/Service)"]:::client

    %% Edge Proxy
    Nginx["Nginx Reverse Proxy"]:::proxy

    %% Application Container
    subgraph "FastAPI/Uvicorn Container" 
        direction TB

        Entry["src/api/main.py"]:::app
        subgraph "API Layer (v1 Routes)"
            direction TB
            Router["Versioned Router\n(src/api/v1/routes)"]:::app
            Endpoints["API Endpoints\n(src/api/v1/endpoints.py)"]:::app
        end

        subgraph "Business Logic Services"
            direction TB
            CheckService["Health Check Service\n(check.py)"]:::service
            ClassesService["Database Class Fetcher\n(get_classes.py)"]:::service
            DatabasesService["Database Info Service\n(get_databases.py)"]:::service
            MistralService["MistralAI Integration Service\n(mistralai_service.py)"]:::service
            RAGService["RAG Service\n(rag_service.py)"]:::service
        end

        subgraph "Security Layer"
            direction TB
            AuthUtils["API Auth Utilities\n(api_auth.py)"]:::app
            OAuth2["OAuth2 Scheme\n(oauth2_scheme.py)"]:::app
        end

        subgraph "Data Layer (Connectors)"
            direction TB
            MongoConnector["MongoDB Connector\n(mongo_db_connector.py)"]:::db
            QdrantConnector["Qdrant Connector\n(qdrant_connector.py)"]:::db
        end

        subgraph "Utilities & Classes"
            direction TB
            DBUtils["DB Connection Manager\n(ensure_database_connection.py)"]:::app
            InferenceUtils["Inference Utilities\n(inference.py)"]:::app
            Logger["Logging Utility\n(logger.py)"]:::app
            Embeddings["Embeddings Class\n(embeddings.py)"]:::app
            TextGen["Text Generation Class\n(text_generation.py)"]:::app
            InferenceTypes["Pydantic Models\n(inference_types.py)"]:::app
        end
    end

    %% Databases
    subgraph "Databases (Docker Containers)"
        direction TB
        MongoDB["MongoDB"]:::db
        Qdrant["Qdrant"]:::db
    end

    %% External Service
    MistralAI["MistralAI API"]:::external

    %% Orchestration Note
    NoteOrch["Managed by Docker‑Compose\n(Dockerfile, docker-compose.yml)"]:::note

    %% Flows
    Client -->|"HTTPS"| Nginx
    Nginx -->|"HTTP"| Entry
    Entry -->|"/v1/*"| Router
    Router -->|calls| Endpoints
    Endpoints -->|invokes| CheckService
    Endpoints -->|invokes| ClassesService
    Endpoints -->|invokes| DatabasesService
    Endpoints -->|invokes| MistralService
    Endpoints -->|invokes| RAGService

    CheckService -->|uses| MongoConnector
    ClassesService -->|uses| MongoConnector
    DatabasesService -->|uses| MongoConnector
    RAGService -->|uses| QdrantConnector
    MistralService -->|HTTPS API Call| MistralAI

    MongoConnector -->|CRUD I/O| MongoDB
    QdrantConnector -->|Vector Ops| Qdrant

    Entry -->|injects dependencies| AuthUtils
    Entry -->|injects dependencies| OAuth2

    Entry -->|uses| DBUtils
    Entry -->|uses| InferenceUtils
    Entry -->|uses| Logger
    CheckService -->|uses| Embeddings
    MistralService -->|uses| TextGen
    MistralService -->|uses| InferenceTypes

    Entry --- NoteOrch

    %% Click Events
    click Entry "https://github.com/mathis-lambert/api/blob/main/src/api/main.py"
    click Router "https://github.com/mathis-lambert/api/tree/main/src/api/v1/routes"
    click Endpoints "https://github.com/mathis-lambert/api/blob/main/src/api/v1/endpoints.py"
    click CheckService "https://github.com/mathis-lambert/api/blob/main/src/api/v1/services/check.py"
    click ClassesService "https://github.com/mathis-lambert/api/blob/main/src/api/v1/services/get_classes.py"
    click DatabasesService "https://github.com/mathis-lambert/api/blob/main/src/api/v1/services/get_databases.py"
    click MistralService "https://github.com/mathis-lambert/api/blob/main/src/api/v1/services/mistralai_service.py"
    click RAGService "https://github.com/mathis-lambert/api/blob/main/src/api/v1/services/rag_service.py"
    click AuthUtils "https://github.com/mathis-lambert/api/blob/main/src/api/v1/security/api_auth.py"
    click OAuth2 "https://github.com/mathis-lambert/api/blob/main/src/api/v1/security/oauth2_scheme.py"
    click MongoConnector "https://github.com/mathis-lambert/api/blob/main/src/api/databases/mongo_db_connector.py"
    click QdrantConnector "https://github.com/mathis-lambert/api/blob/main/src/api/databases/qdrant_connector.py"
    click DBUtils "https://github.com/mathis-lambert/api/blob/main/src/api/utils/ensure_database_connection.py"
    click InferenceUtils "https://github.com/mathis-lambert/api/blob/main/src/api/utils/inference.py"
    click Logger "https://github.com/mathis-lambert/api/blob/main/src/api/utils/logger.py"
    click Embeddings "https://github.com/mathis-lambert/api/blob/main/src/api/classes/embeddings.py"
    click TextGen "https://github.com/mathis-lambert/api/blob/main/src/api/classes/text_generation.py"
    click InferenceTypes "https://github.com/mathis-lambert/api/blob/main/src/api/types/inference_types.py"
    click Nginx "https://github.com/mathis-lambert/api/blob/main/nginx/nginx.conf"
    click NoteOrch "https://github.com/mathis-lambert/api/blob/main/docker-compose.yml"
    click NoteOrch "https://github.com/mathis-lambert/api/tree/main/Dockerfile"
    click MongoDB "https://github.com/mathis-lambert/api/blob/main/mongodb/config/init-db.js"
    click Qdrant "https://github.com/mathis-lambert/api/blob/main/qdrant/config/config.yaml"

    %% Styles
    classDef client fill:#DFF8FF,stroke:#333,stroke-width:1px
    classDef proxy fill:#E0FFD8,stroke:#333,stroke-width:1px
    classDef app fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef service fill:#B8DFFF,stroke:#333,stroke-width:1px
    classDef db fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef external fill:#E3D4FF,stroke:#333,stroke-width:1px
    classDef note fill:#F0F0F0,stroke:#999,stroke-width:1px,stroke-dasharray: 5 5
```
