# ramirezlzrga/ia_futured architecture

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

- Interactive diagram: https://gitdiagram.com/ramirezlzrga/ia_futured
- Repository: https://github.com/ramirezlzrga/ia_futured

## Overview

#### Purpose
IA_FUTURED predicts student dropout risk from survey data. It produces a risk percentage, likely reason, and recommendations, with MongoDB Atlas as the stated persistence/integration service.

#### Entry Points
- `main.py` is the likely application orchestrator and operational entry point.
- `generar_alumnos_en_riesgo.py` likely runs batch identification/generation of at-risk students.
- `prediccion_alumno.py` likely exposes the per-student prediction flow.

#### Model Training and Artifact Boundary
- `modelo.py` defines the ML model/training or model-loading logic.
- Serialized production artifacts separate training from inference:
  - `modelo_entrenado/modelo.pkl`
  - `modelo_entrenado/label_encoders.pkl`
- Inference must use the persisted model and matching encoders; feature encoding consistency is a critical boundary.

#### Prediction Pipeline
The core per-student flow is expected to:
1. Obtain survey/student inputs.
2. Encode categorical values using `modelo_entrenado/label_encoders.pkl`.
3. Score the input with `modelo_entrenado/modelo.pkl`.
4. Convert the score into risk percentage, probable cause, and recommendations.
5. Return or persist the resulting student-risk record.

Relevant implementation paths:
- `prediccion_alumno.py`
- `modelo.py`
- `modelo_entrenado/modelo.pkl`

#### Batch At-Risk Student Processing
`generar_alumnos_en_riesgo.py` represents a batch-oriented stage that likely applies prediction logic across a population, filters or labels high-risk students, and prepares records for downstream review or storage. It should reuse the same prediction/model-artifact path as single-student scoring to avoid divergent risk classifications.

#### Database Integration
- `conexion.py` is the MongoDB Atlas connection boundary.
- Application stages should isolate database reads/writes behind this module rather than embedding connection behavior in model code.
- MongoDB Atlas holds or exchanges survey/student data and predicted-risk outputs.

#### Runtime and Dependencies
- Python is the repository runtime, indicated by the `.py` entry modules.
- Dependencies are declared in `requerimientos.txt`.
- The repository includes prebuilt binary model artifacts, so deployment requires compatible Python/library versions for pickle deserialization.

#### Architectural Boundaries
- **Data access:** `conexion.py`
- **Model and feature transformation:** `modelo.py`, `modelo_entrenado/label_encoders.pkl`
- **Inference/application logic:** `prediccion_alumno.py`, `main.py`
- **Population/batch workflow:** `generar_alumnos_en_riesgo.py`
- **Persisted ML contract:** `modelo_entrenado/modelo.pkl`

Main entry points: [`prediccion_alumno.py`](https://github.com/ramirezlzrga/ia_futured/blob/main/prediccion_alumno.py) (Student prediction), [`generar_alumnos_en_riesgo.py`](https://github.com/ramirezlzrga/ia_futured/blob/main/generar_alumnos_en_riesgo.py) (Batch risk generation), [`conexion.py`](https://github.com/ramirezlzrga/ia_futured/blob/main/conexion.py) (MongoDB connection), [`modelo.py`](https://github.com/ramirezlzrga/ia_futured/blob/main/modelo.py) (Model logic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Python application"]
  node_main["Application orchestrator<br/>Python entry point<br/>[main.py]"]
  node_student_prediction["Student prediction<br/>Inference flow"]
  node_batch_risk["Batch risk generation<br/>Batch workflow"]
  node_requirements["Dependencies<br/>Python requirements<br/>[requerimientos.txt]"]
end

subgraph group_ml["ML contract"]
  node_model_logic["Model logic<br/>Training and loading<br/>[modelo.py]"]
  node_model_artifact["Trained model<br/>Pickle artifact<br/>[modelo.pkl]"]
  node_encoders["Label encoders<br/>Pickle artifact<br/>[label_encoders.pkl]"]
end

subgraph group_data["Data integration"]
  node_db_connection["MongoDB connection<br/>Data-access boundary<br/>[conexion.py]"]
  node_mongodb_atlas[("MongoDB Atlas<br/>Persistence service")]
  node_student_surveys[("Student survey data<br/>Input records")]
  node_risk_record["Student risk record<br/>Prediction output"]
end

node_main -->|"orchestrates"| node_student_prediction
node_main -->|"runs"| node_batch_risk
node_student_prediction -->|"encodes inputs"| node_encoders
node_student_prediction -->|"scores student"| node_model_artifact
node_batch_risk -->|"reuses scoring"| node_student_prediction
node_model_logic -->|"trains or loads"| node_model_artifact
node_model_logic -->|"creates or loads"| node_encoders
node_requirements -.->|"runtime libraries"| node_model_logic
node_db_connection -->|"connects"| node_mongodb_atlas
node_mongodb_atlas -->|"provides"| node_student_surveys
node_student_prediction -->|"reads and writes"| node_db_connection
node_batch_risk -->|"reads and writes"| node_db_connection
node_student_prediction -->|"produces"| node_risk_record
node_batch_risk -->|"produces"| node_risk_record
node_db_connection -->|"persists"| node_risk_record

click node_main "https://github.com/ramirezlzrga/ia_futured/blob/main/main.py"
click node_student_prediction "https://github.com/ramirezlzrga/ia_futured/blob/main/prediccion_alumno.py"
click node_batch_risk "https://github.com/ramirezlzrga/ia_futured/blob/main/generar_alumnos_en_riesgo.py"
click node_requirements "https://github.com/ramirezlzrga/ia_futured/blob/main/requerimientos.txt"
click node_model_logic "https://github.com/ramirezlzrga/ia_futured/blob/main/modelo.py"
click node_model_artifact "https://github.com/ramirezlzrga/ia_futured/blob/main/modelo_entrenado/modelo.pkl"
click node_encoders "https://github.com/ramirezlzrga/ia_futured/blob/main/modelo_entrenado/label_encoders.pkl"
click node_db_connection "https://github.com/ramirezlzrga/ia_futured/blob/main/conexion.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_student_prediction,node_batch_risk,node_requirements toneBlue
class node_model_logic,node_model_artifact,node_encoders toneAmber
class node_db_connection,node_mongodb_atlas,node_student_surveys,node_risk_record toneMint
```

## Components

### Python application

- [Application orchestrator](https://github.com/ramirezlzrga/ia_futured/blob/main/main.py): Python entry point · `main.py`
- [Student prediction](https://github.com/ramirezlzrga/ia_futured/blob/main/prediccion_alumno.py): Inference flow · Produces risk, probable cause, and recommendations. · `prediccion_alumno.py`
- [Batch risk generation](https://github.com/ramirezlzrga/ia_futured/blob/main/generar_alumnos_en_riesgo.py): Batch workflow · Scores a population and identifies at-risk students. · `generar_alumnos_en_riesgo.py`
- [Dependencies](https://github.com/ramirezlzrga/ia_futured/blob/main/requerimientos.txt): Python requirements · Compatible library versions are required to deserialize model pickles. · `requerimientos.txt`

### ML contract

Persisted artifacts keep training and inference compatible.

- [Model logic](https://github.com/ramirezlzrga/ia_futured/blob/main/modelo.py): Training and loading · Defines model training or persisted-model loading. · `modelo.py`
- [Trained model](https://github.com/ramirezlzrga/ia_futured/blob/main/modelo_entrenado/modelo.pkl): Pickle artifact · `modelo_entrenado/modelo.pkl`
- [Label encoders](https://github.com/ramirezlzrga/ia_futured/blob/main/modelo_entrenado/label_encoders.pkl): Pickle artifact · Categorical encoding must match model training. · `modelo_entrenado/label_encoders.pkl`

### Data integration

- [MongoDB connection](https://github.com/ramirezlzrga/ia_futured/blob/main/conexion.py): Data-access boundary · Isolates Atlas connectivity from model code. · `conexion.py`
- **MongoDB Atlas**: Persistence service · Stores or exchanges student surveys and risk outputs.
- **Student survey data**: Input records
- **Student risk record**: Prediction output · Risk percentage, likely reason, and recommendations.

## Connections

- Application orchestrator → Student prediction: orchestrates
- Application orchestrator → Batch risk generation: runs
- Student prediction → Label encoders: encodes inputs
- Student prediction → Trained model: scores student
- Batch risk generation → Student prediction: reuses scoring
- Model logic → Trained model: trains or loads
- Model logic → Label encoders: creates or loads
- Dependencies → Model logic: runtime libraries
- MongoDB connection → MongoDB Atlas: connects
- MongoDB Atlas → Student survey data: provides
- Student prediction → MongoDB connection: reads and writes
- Batch risk generation → MongoDB connection: reads and writes
- Student prediction → Student risk record: produces
- Batch risk generation → Student risk record: produces
- MongoDB connection → Student risk record: persists