# pierrot-01/hackathon_epis_2026 architecture

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

- Interactive diagram: https://gitdiagram.com/pierrot-01/hackathon_epis_2026
- Repository: https://github.com/pierrot-01/hackathon_epis_2026

## Overview

1. **System purpose**
   This repo is a school-risk early warning MVP for teachers/tutors. Its core architectural idea is a strict split between a **deterministic risk classifier** and an **AI-generated pedagogical explanation/recommendation layer**.

2. **Top-level runtime boundary**
   The application is split into a **Python backend** and a **static frontend**. The backend runs a FastAPI service on `localhost:8000`, while the frontend is a set of HTML pages that present login, monitoring, administration, and reporting views.

3. **Backend core services**
   `backend/main.py` is the API entry point and also serves static assets. It orchestrates the main request flow: load student data, classify risk, obtain an explanation, and return results to the UI.

4. **Deterministic decision engine**
   `backend/classifier.py` contains the auditable rule engine that assigns the risk state. The README indicates the output categories include **🟢/🟡/🔴** and **⚪ dato insuficiente**, with the classifier responsible for the final risk label and not the AI.

5. **Generative explanation layer**
   `backend/ia_client.py` connects to **Google Gemini API** (`gemini-2.0-flash`). Its job is not to decide risk, but to generate the contextual narrative and recommendations that accompany the deterministic classification.

6. **Offline resilience and fallback**
   `backend/fallback.py` manages local cached responses in `cache/respuestas_ia.json`. If the Gemini API is unavailable, rate-limited, or the system is run without connectivity, the app falls back to cached AI responses so the UI still works.

7. **Data layer**
   The repository keeps local JSON datasets under `data/`, including `estudiantes.json` and `docentes.json`. These act as the app’s primary structured input for demos and local operation, instead of a database service.

8. **Frontend surfaces**
   `frontend/index.html`, `monitoreo.html`, `admin.html`, `reportes.html`, and `estudiantes.html` map to the main user-facing screens. They represent the operational views for login, real-time monitoring, administrative summaries, reports, and student-centric listing.

9. **Design artifacts vs. runtime**
   The `diseño de pagina/` directory contains page design blueprints and HTML mockups, not the live application runtime. These files are useful for understanding intended screen structure and navigation, but the executable app is the `frontend/` + `backend/` pair.

10. **Precomputation workflow**
   `generar_cache.py` and `backend/scripts/generar_cache.py` are used to pre-generate AI explanations and persist them into the cache. This supports demo readiness and reduces dependence on live API calls during use.

11. **Startup and environment**
   `start.sh` is the convenience launcher for Linux/macOS, and `backend/.env.example` documents the required environment variable for the Gemini API key. The architecture assumes a local developer setup with Python and pip, plus optional pre-cached AI responses for offline use.

12. **Main data flow**
   User opens a frontend page → frontend requests data from the FastAPI backend → backend loads student records from JSON → classifier determines the risk level → AI client generates or retrieves an explanation → fallback/cache ensures continuity → frontend renders the result in the monitoring/admin/reporting views.

Main entry points: [`backend/main.py`](https://github.com/pierrot-01/hackathon_epis_2026/blob/main/backend/main.py) (API entry), [`README.md`](https://github.com/pierrot-01/hackathon_epis_2026/blob/main/README.md) (README), [`backend/ia_client.py`](https://github.com/pierrot-01/hackathon_epis_2026/blob/main/backend/ia_client.py) (Gemini client), [`backend/fallback.py`](https://github.com/pierrot-01/hackathon_epis_2026/blob/main/backend/fallback.py) (AI fallback)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_backend_main["API entry<br/>FastAPI app<br/>[main.py]"]
  node_classifier{{"Risk engine<br/>Rule classifier<br/>[classifier.py]"}}
  node_ia_client["Gemini client<br/>LLM connector<br/>[ia_client.py]"]
  node_fallback[("AI fallback<br/>Cache loader<br/>[fallback.py]")]
  node_cache_gen["Cache builder<br/>Precompute script<br/>[generar_cache.py]"]
  node_root_cache_gen["Cache tool<br/>CLI script<br/>[generar_cache.py]"]
  node_frontend_index["Login page<br/>HTML view<br/>[index.html]"]
  node_frontend_monitoreo["Monitoring<br/>HTML view<br/>[monitoreo.html]"]
  node_frontend_admin["Admin panel<br/>HTML view<br/>[admin.html]"]
  node_frontend_reportes["Reports<br/>HTML view<br/>[reportes.html]"]
  node_frontend_estudiantes["Students view<br/>HTML view<br/>[estudiantes.html]"]
end

subgraph group_data["Data"]
  node_students_data[("Students data<br/>JSON dataset<br/>[estudiantes.json]")]
  node_teachers_data[("Teachers data<br/>JSON dataset<br/>[docentes.json]")]
  node_ai_cache[("AI cache<br/>Cached responses<br/>[respuestas_ia.json]")]
end

subgraph group_design["Design"]
  node_design_login["Login design<br/>Mockup<br/>[code.html]"]
  node_design_monitoring["Monitoring design<br/>Mockup<br/>[code.html]"]
  node_design_admin["Admin design<br/>Mockup<br/>[code.html]"]
  node_design_reports["Reports design<br/>Mockup<br/>[code.html]"]
  node_design_students["Students design<br/>Mockup<br/>[code.html]"]
end

node_readme["README<br/>Docs<br/>[README.md]"]
node_start_script["Start script<br/>Launcher<br/>[start.sh]"]

node_frontend_index -->|"requests"| node_backend_main
node_frontend_monitoreo -->|"requests"| node_backend_main
node_frontend_admin -->|"requests"| node_backend_main
node_frontend_reportes -->|"requests"| node_backend_main
node_frontend_estudiantes -->|"requests"| node_backend_main
node_backend_main -->|"loads"| node_students_data
node_backend_main -->|"loads"| node_teachers_data
node_backend_main -->|"classifies"| node_classifier
node_backend_main -->|"explains"| node_ia_client
node_backend_main -->|"falls back"| node_fallback
node_ia_client -->|"cache lookup"| node_fallback
node_fallback -->|"reads"| node_ai_cache
node_cache_gen -->|"writes"| node_ai_cache
node_root_cache_gen -->|"invokes"| node_cache_gen
node_backend_main -.->|"launched by"| node_start_script
node_readme -.->|"documents"| node_backend_main
node_readme -.->|"documents"| node_classifier
node_readme -.->|"documents"| node_ia_client
node_readme -.->|"documents"| node_frontend_monitoreo
node_design_login -.->|"guides"| node_frontend_index
node_design_monitoring -.->|"guides"| node_frontend_monitoreo
node_design_admin -.->|"guides"| node_frontend_admin
node_design_reports -.->|"guides"| node_frontend_reportes
node_design_students -.->|"guides"| node_frontend_estudiantes

click node_backend_main "https://github.com/pierrot-01/hackathon_epis_2026/blob/main/backend/main.py"
click node_classifier "https://github.com/pierrot-01/hackathon_epis_2026/blob/main/backend/classifier.py"
click node_ia_client "https://github.com/pierrot-01/hackathon_epis_2026/blob/main/backend/ia_client.py"
click node_fallback "https://github.com/pierrot-01/hackathon_epis_2026/blob/main/backend/fallback.py"
click node_cache_gen "https://github.com/pierrot-01/hackathon_epis_2026/blob/main/backend/scripts/generar_cache.py"
click node_root_cache_gen "https://github.com/pierrot-01/hackathon_epis_2026/blob/main/generar_cache.py"
click node_frontend_index "https://github.com/pierrot-01/hackathon_epis_2026/blob/main/frontend/index.html"
click node_frontend_monitoreo "https://github.com/pierrot-01/hackathon_epis_2026/blob/main/frontend/monitoreo.html"
click node_frontend_admin "https://github.com/pierrot-01/hackathon_epis_2026/blob/main/frontend/admin.html"
click node_frontend_reportes "https://github.com/pierrot-01/hackathon_epis_2026/blob/main/frontend/reportes.html"
click node_frontend_estudiantes "https://github.com/pierrot-01/hackathon_epis_2026/blob/main/frontend/estudiantes.html"
click node_students_data "https://github.com/pierrot-01/hackathon_epis_2026/blob/main/data/estudiantes.json"
click node_teachers_data "https://github.com/pierrot-01/hackathon_epis_2026/blob/main/data/docentes.json"
click node_ai_cache "https://github.com/pierrot-01/hackathon_epis_2026/blob/main/cache/respuestas_ia.json"
click node_design_login "https://github.com/pierrot-01/hackathon_epis_2026/blob/main/diseño de pagina/login/code.html"
click node_design_monitoring "https://github.com/pierrot-01/hackathon_epis_2026/blob/main/diseño de pagina/panel_de_monitoreo_interactivo/code.html"
click node_design_admin "https://github.com/pierrot-01/hackathon_epis_2026/blob/main/diseño de pagina/panel_de_administraci_n_gesti_n_activa/code.html"
click node_design_reports "https://github.com/pierrot-01/hackathon_epis_2026/blob/main/diseño de pagina/administraci_n_generaci_n_de_reportes/code.html"
click node_design_students "https://github.com/pierrot-01/hackathon_epis_2026/blob/main/diseño de pagina/administraci_n_gesti_n_de_estudiantes/code.html"
click node_readme "https://github.com/pierrot-01/hackathon_epis_2026/blob/main/README.md"
click node_start_script "https://github.com/pierrot-01/hackathon_epis_2026/blob/main/start.sh"

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_backend_main,node_classifier,node_ia_client,node_fallback,node_cache_gen,node_root_cache_gen,node_frontend_index,node_frontend_monitoreo,node_frontend_admin,node_frontend_reportes,node_frontend_estudiantes toneBlue
class node_students_data,node_teachers_data,node_ai_cache toneAmber
class node_design_login,node_design_monitoring,node_design_admin,node_design_reports,node_design_students toneMint
class node_readme,node_start_script toneNeutral
```

## Components

### Runtime

Executable application boundaries

- [API entry](https://github.com/pierrot-01/hackathon_epis_2026/blob/main/backend/main.py): FastAPI app · Serves the backend API and static assets; orchestrates the request flow. · `backend/main.py`
- [Risk engine](https://github.com/pierrot-01/hackathon_epis_2026/blob/main/backend/classifier.py): Rule classifier · Deterministic, auditable classifier that assigns the final risk label. · `backend/classifier.py`
- [Gemini client](https://github.com/pierrot-01/hackathon_epis_2026/blob/main/backend/ia_client.py): LLM connector · Calls Gemini to generate contextual explanations and recommendations. · `backend/ia_client.py`
- [AI fallback](https://github.com/pierrot-01/hackathon_epis_2026/blob/main/backend/fallback.py): Cache loader · Retrieves cached AI responses when live generation is unavailable. · `backend/fallback.py`
- [Cache builder](https://github.com/pierrot-01/hackathon_epis_2026/blob/main/backend/scripts/generar_cache.py): Precompute script · Generates and stores reusable AI explanations for demo/offline use. · `backend/scripts/generar_cache.py`
- [Cache tool](https://github.com/pierrot-01/hackathon_epis_2026/blob/main/generar_cache.py): CLI script · Convenience script for pre-generating AI responses at the repository root. · `generar_cache.py`
- [Login page](https://github.com/pierrot-01/hackathon_epis_2026/blob/main/frontend/index.html): HTML view · Entry screen for the static frontend. · `frontend/index.html`
- [Monitoring](https://github.com/pierrot-01/hackathon_epis_2026/blob/main/frontend/monitoreo.html): HTML view · Operational dashboard for student risk monitoring. · `frontend/monitoreo.html`
- [Admin panel](https://github.com/pierrot-01/hackathon_epis_2026/blob/main/frontend/admin.html): HTML view · Administrative summary and management interface. · `frontend/admin.html`
- [Reports](https://github.com/pierrot-01/hackathon_epis_2026/blob/main/frontend/reportes.html): HTML view · Reporting and results-oriented view. · `frontend/reportes.html`
- [Students view](https://github.com/pierrot-01/hackathon_epis_2026/blob/main/frontend/estudiantes.html): HTML view · Student-centric listing and detail surface. · `frontend/estudiantes.html`

### Data

Local structured inputs and cached outputs

- [Students data](https://github.com/pierrot-01/hackathon_epis_2026/blob/main/data/estudiantes.json): JSON dataset · Primary student records used for local operation and demos. · `data/estudiantes.json`
- [Teachers data](https://github.com/pierrot-01/hackathon_epis_2026/blob/main/data/docentes.json): JSON dataset · Local teacher records supporting the application dataset. · `data/docentes.json`
- [AI cache](https://github.com/pierrot-01/hackathon_epis_2026/blob/main/cache/respuestas_ia.json): Cached responses · Persisted fallback explanations used to keep the UI working offline. · `cache/respuestas_ia.json`

### Design

Mockups and page blueprints

- [Login design](https://github.com/pierrot-01/hackathon_epis_2026/blob/HEAD/dise%C3%B1o%20de%20pagina/login/code.html): Mockup · Design blueprint for the login screen. · `diseño de pagina/login/code.html`
- [Monitoring design](https://github.com/pierrot-01/hackathon_epis_2026/blob/HEAD/dise%C3%B1o%20de%20pagina/panel_de_monitoreo_interactivo/code.html): Mockup · Blueprint for the interactive monitoring panel. · `diseño de pagina/panel_de_monitoreo_interactivo/code.html`
- [Admin design](https://github.com/pierrot-01/hackathon_epis_2026/blob/HEAD/dise%C3%B1o%20de%20pagina/panel_de_administraci_n_gesti_n_activa/code.html): Mockup · Blueprint for the active administration panel. · `diseño de pagina/panel_de_administraci_n_gesti_n_activa/code.html`
- [Reports design](https://github.com/pierrot-01/hackathon_epis_2026/blob/HEAD/dise%C3%B1o%20de%20pagina/administraci_n_generaci_n_de_reportes/code.html): Mockup · Blueprint for report generation and administration. · `diseño de pagina/administraci_n_generaci_n_de_reportes/code.html`
- [Students design](https://github.com/pierrot-01/hackathon_epis_2026/blob/HEAD/dise%C3%B1o%20de%20pagina/administraci_n_gesti_n_de_estudiantes/code.html): Mockup · Blueprint for the student management surface. · `diseño de pagina/administraci_n_gesti_n_de_estudiantes/code.html`

### Other components

- [README](https://github.com/pierrot-01/hackathon_epis_2026/blob/main/README.md): Docs · Repository overview and operating notes. · `README.md`
- [Start script](https://github.com/pierrot-01/hackathon_epis_2026/blob/main/start.sh): Launcher · Convenience launcher for local execution on Unix-like systems. · `start.sh`

## Connections

- Login page → API entry: requests · Frontend screens call the API for data and results.
- Monitoring → API entry: requests · Monitoring view pulls current risk information.
- Admin panel → API entry: requests · Admin view retrieves summaries and student state.
- Reports → API entry: requests · Reports view asks backend for report data.
- Students view → API entry: requests · Student view loads structured records and statuses.
- API entry → Students data: loads · Primary student dataset input.
- API entry → Teachers data: loads · Teacher dataset input.
- API entry → Risk engine: classifies · Delegates the final risk label to the rule engine.
- API entry → Gemini client: explains · Requests pedagogical narrative and recommendations.
- API entry → AI fallback: falls back · Uses cached responses when live AI is unavailable.
- Gemini client → AI fallback: cache lookup · Fallback path for unavailable or rate-limited AI calls.
- AI fallback → AI cache: reads · Loads persisted AI responses from local cache.
- Cache builder → AI cache: writes · Precomputes and stores reusable explanations.
- Cache tool → Cache builder: invokes · Repository-level helper for cache generation.
- API entry → Start script: launched by · Local startup helper can boot the backend runtime.
- README → API entry: documents · Explains the backend entry point and flow.
- README → Risk engine: documents · Describes the deterministic classification rule set.
- README → Gemini client: documents · Describes the Gemini explanation layer.
- README → Monitoring: documents · Describes the main frontend views.
- Login design → Login page: guides · Mockup informs the implemented login page.
- Monitoring design → Monitoring: guides · Mockup informs the monitoring page.
- Admin design → Admin panel: guides · Mockup informs the admin page.
- Reports design → Reports: guides · Mockup informs the reports page.
- Students design → Students view: guides · Mockup informs the students page.
