How pierrot-01/hackathon_epis_2026 works
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: main.py API entry · README.md README · ia_client.py Gemini client · fallback.py AI fallback
Components 21
Runtime
Executable application boundaries
- API entry · Serves the backend API and static assets; orchestrates the request flow.
backend/main.py - Risk engine · Deterministic, auditable classifier that assigns the final risk label.
backend/classifier.py - Gemini client · Calls Gemini to generate contextual explanations and recommendations.
backend/ia_client.py - AI fallback · Retrieves cached AI responses when live generation is unavailable.
backend/fallback.py - Cache builder · Generates and stores reusable AI explanations for demo/offline use.
backend/scripts/generar_cache.py - Cache tool · Convenience script for pre-generating AI responses at the repository root.
generar_cache.py - Login page · Entry screen for the static frontend.
frontend/index.html - Monitoring · Operational dashboard for student risk monitoring.
frontend/monitoreo.html - Admin panel · Administrative summary and management interface.
frontend/admin.html - Reports · Reporting and results-oriented view.
frontend/reportes.html - Students view · Student-centric listing and detail surface.
frontend/estudiantes.html
Data
Local structured inputs and cached outputs
- Students data · Primary student records used for local operation and demos.
data/estudiantes.json - Teachers data · Local teacher records supporting the application dataset.
data/docentes.json - AI cache · Persisted fallback explanations used to keep the UI working offline.
cache/respuestas_ia.json
Design
Mockups and page blueprints
- Login design · Design blueprint for the login screen.
diseño de pagina/login/code.html - Monitoring design · Blueprint for the interactive monitoring panel.
diseño de pagina/panel_de_monitoreo_interactivo/code.html - Admin design · Blueprint for the active administration panel.
diseño de pagina/panel_de_administraci_n_gesti_n_activa/code.html - Reports design · Blueprint for report generation and administration.
diseño de pagina/administraci_n_generaci_n_de_reportes/code.html - Students design · Blueprint for the student management surface.
diseño de pagina/administraci_n_gesti_n_de_estudiantes/code.html
Other components
- README · Repository overview and operating notes.
README.md - Start script · Convenience launcher for local execution on Unix-like systems.
start.sh
Connections 24
- 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.