How sofia-cantu/datatonoxxo works
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