# sofia-cantu/datatonoxxo architecture

> Architecture diagram of the GitHub repository sofia-cantu/datatonoxxo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sofia-cantu/datatonoxxo
- Repository: https://github.com/sofia-cantu/datatonoxxo

## Overview

##### Project type and purpose
- This is a full-stack predictive analytics web application (“Datathon con Oxxo!”) that recommends optimal new store locations by combining geospatial data, a trained XGBoost model, and a language model for strategic insights. It comprises three main layers: Data & ML artifacts, a Python/FastAPI backend, and a Next.js/React frontend.

##### File structure
- Top-level:
- DataCreation, DataExploration, DataEvaluation, MLOptimization, Models — Jupyter notebooks and serialized model files for offline data preparation, exploration, evaluation, and model tuning.
- backend — FastAPI service with Python modules (funciones.py, main.py), trained models (pickle files), and dependency definitions (requirements.txt).
- frontend — Next.js application (React) with pages, components (MapaTiendas, VentasLineChart), and configuration (tsconfig.json, package.json).
- Additional files: package.json at root (monorepo), Docker ignored, CSV files implied for data storage (no PostgreSQL).

##### README
- Describes system components: FastAPI backend, XGBoost, geospatial libs, Next.js + React + Leaflet.
- Clarifies installation steps and ports.
- No persistent DB; CSVs are used. LLM calls are made directly from the frontend. No map-tile server of our own.

a. Main Components:
1. Frontend (Next.js + React)
2. Backend (FastAPI + Python ML service)
3. Data Store (CSV files on disk)
4. ML Models (Pickle/XGBoost artifacts)
5. External Service: OpenAI LLM API
6. Static Map Layer (e.g., Leaflet using public tile provider)
b. Relationships & Interactions:
- User interacts via browser → Frontend
- Frontend → Backend (REST API calls)
- Backend loads CSVs & ML models → runs prediction → returns JSON
- Frontend also → OpenAI API for strategic recommendations
- Frontend renders map and chart components
c. Architectural Patterns:
- Clear separation of concerns (Presentation vs API vs Data)
- Stateless backend; all state lives in model files and CSVs
- Client-side LLM integration
d. Key Technologies:
- Frontend: Next.js, React, Leaflet (for maps), React-Leaflet
- Backend: FastAPI, Uvicorn, Joblib/Pickle for model loading
- ML: XGBoost, Scikit-learn, Geopandas, Shapely

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    Browser["Browser"]:::user

    %% Frontend Layer
    subgraph "Frontend Layer (frontend/)"
        direction TB
        FrontendApp["Next.js Frontend Application"]:::frontend
        Layout["Global Layout & Styles"]:::frontend
        Nueva["New Store Recommendation Page"]:::frontend
        Actual["Current Stores Display Page"]:::frontend
        MapComp["Store Map Component (Leaflet)"]:::frontend
        Chart["Sales Line Chart Component"]:::frontend
        Types["Types Definition"]:::frontend
        TSConfig["tsconfig.json"]:::frontend
        Fpkg["package.json"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer (backend/)"
        direction TB
        APIService["FastAPI Backend Service"]:::backend
        EntryPoint["API Entry Point (main.py)"]:::backend
        Utils["Utility Functions (funciones.py)"]:::backend
        Dependencies["Dependencies (requirements.txt)"]:::backend
        BPkg["package.json"]:::backend
        XGBBack["modelo_xgboost.pkl"]:::backend
        TrainedBack["modelo_entrenado.pkl"]:::backend
    end

    %% Models Directory
    subgraph "Models Directory (Models/)"
        direction TB
        NewStoreModel["Serialized XGBoost Model for New Store"]:::backend
        ModelInput["Model Input Definition Script"]:::backend
    end

    %% Offline & Exploration
    subgraph "Offline & Data Exploration"
        direction TB
        DC["DataCreation/"]:::data
        DE["DataExploration/"]:::data
        DV["DataEvaluation/"]:::data
        MO["MLOptimization/"]:::data
        OfflineModel["Offline Model Tuning Artifact"]:::data
    end

    %% Data Store
    CSV["CSV Data Store"]:::data

    %% External Services
    OpenAI["OpenAI API"]:::external

    %% Connections
    Browser -->|uses| FrontendApp
    FrontendApp -->|renders| Layout
    FrontendApp -->|routes| Nueva
    FrontendApp -->|routes| Actual
    Nueva -->|uses| MapComp
    Actual -->|uses| Chart
    FrontendApp -->|calls REST API| APIService
    APIService -->|imports| EntryPoint
    APIService -->|uses| Utils
    APIService -->|reads| CSV
    APIService -->|loads| XGBBack
    APIService -->|loads| TrainedBack
    FrontendApp -.->|LLM call| OpenAI
    APIService -->|loads| NewStoreModel
    APIService -->|uses| ModelInput
    DC --> DE
    DE --> DV
    DV --> MO
    MO --> OfflineModel

    %% Click Events Frontend
    click FrontendApp "https://github.com/sofia-cantu/datatonoxxo/tree/main/frontend/"
    click Layout "https://github.com/sofia-cantu/datatonoxxo/blob/main/frontend/src/app/layout.tsx"
    click Nueva "https://github.com/sofia-cantu/datatonoxxo/blob/main/frontend/src/app/nuevaTienda/page.tsx"
    click Actual "https://github.com/sofia-cantu/datatonoxxo/blob/main/frontend/src/app/tiendasActuales/page.tsx"
    click MapComp "https://github.com/sofia-cantu/datatonoxxo/blob/main/frontend/src/components/MapaTiendas.tsx"
    click Chart "https://github.com/sofia-cantu/datatonoxxo/blob/main/frontend/src/components/VentasLineChart.tsx"
    click Types "https://github.com/sofia-cantu/datatonoxxo/blob/main/frontend/src/types.d.ts"
    click TSConfig "https://github.com/sofia-cantu/datatonoxxo/blob/main/frontend/tsconfig.json"
    click Fpkg "https://github.com/sofia-cantu/datatonoxxo/blob/main/frontend/package.json"

    %% Click Events Backend
    click APIService "https://github.com/sofia-cantu/datatonoxxo/tree/main/backend/"
    click EntryPoint "https://github.com/sofia-cantu/datatonoxxo/blob/main/backend/main.py"
    click Utils "https://github.com/sofia-cantu/datatonoxxo/blob/main/backend/funciones.py"
    click Dependencies "https://github.com/sofia-cantu/datatonoxxo/blob/main/backend/requirements.txt"
    click BPkg "https://github.com/sofia-cantu/datatonoxxo/blob/main/backend/package.json"
    click XGBBack "https://github.com/sofia-cantu/datatonoxxo/blob/main/backend/modelo_xgboost.pkl"
    click TrainedBack "https://github.com/sofia-cantu/datatonoxxo/blob/main/backend/modelo_entrenado.pkl"

    %% Click Events Models
    click NewStoreModel "https://github.com/sofia-cantu/datatonoxxo/blob/main/Models/modelo-nueva-tienda.pkl"
    click ModelInput "https://github.com/sofia-cantu/datatonoxxo/blob/main/Models/modelo_input.py"

    %% Click Events Offline
    click DC "https://github.com/sofia-cantu/datatonoxxo/tree/main/DataCreation/"
    click DE "https://github.com/sofia-cantu/datatonoxxo/tree/main/DataExploration/"
    click DV "https://github.com/sofia-cantu/datatonoxxo/tree/main/DataEvaluation/"
    click MO "https://github.com/sofia-cantu/datatonoxxo/tree/main/MLOptimization/"
    click OfflineModel "https://github.com/sofia-cantu/datatonoxxo/blob/main/MLOptimization/modelo_xgboost.pkl"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef backend fill:#d4edda,stroke:#333,stroke-width:1px
    classDef data fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef external fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef user fill:#e2e3e5,stroke:#333,stroke-width:1px
```
