# jclezamap/calificar architecture

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

- Interactive diagram: https://gitdiagram.com/jclezamap/calificar
- Repository: https://github.com/jclezamap/calificar

## Overview

##### Tipo y propósito del proyecto (según README + tree)
Este repo **no es una app full-stack**; es principalmente una **librería Python distribuida por PyPI** (`pyproject.toml`, `src/calificar`, `*.egg-info`) cuyo objetivo es:

- Permitir que estudiantes (en **Jupyter/Colab**) **registren respuestas** de un taller.
- **Calcular/validar** resultados localmente (al menos estructura de puntos/nota).
- **Enviar/registrar** la calificación en un **sistema remoto del docente** (“Esto enviará tus datos al servidor”).
- Validar funciones con `evafunciones(URL, GRUPO)` usando una **URL tipo GitHub** como fuente de referencia/validación.

Además, el repo incluye **material académico/datasets** en `Big_Data/Taller_*` (muchos `Tema_*.md`, `respuestas.json`, `.csv`, `.xlsx`) que son *contenido y datos* más que runtime del paquete.

**Implicación para el diagrama:** el “sistema” a diagramar no es solo código; es el ecosistema: *Notebook/usuario + paquete calificar + servicios externos (API docente, GitHub) + artefactos de talleres/datos + canal de distribución (PyPI).*

##### Runtime del paquete
- `src/calificar/__init__.py`
Punto de entrada del paquete (exposición de API pública: `taller`, `evafunciones`, etc. según README).
- `src/calificar/core.py`
Núcleo lógico: aquí probablemente viven clases/funciones `taller`, `evafunciones`, validaciones, serialización, networking HTTP, etc. (es el componente central a descomponer en el diagrama).

##### Distribución/Release
- `pyproject.toml`
Build system y dependencias (clave para el diagrama de “supply chain”).
- `publicar.bat`
Script de publicación (flujo de release).
- `src/calificar.egg-info/*`
Metadatos de packaging (no es arquitectura runtime, pero sí indica “paquete installable”).

##### Contenido de talleres / fixtures / ejemplos
- `Big_Data/README.md`, `Big_Data/Taller_1..3/*`
Documentación, enunciados, datasets y `respuestas.json` (posibles claves/expected outputs o templates).
- `enunciados.json`, `TALLERES.md`
Posible índice/metadata de talleres y enunciados.

**Implicación para el diagrama:** separa “producto” (librería) vs “contenido” (talleres/datos) vs “infra de publicación” (PyPI).

##### Qué relaciones/interacciones se deducen del README
Flujos principales:

##### Inicialización
- Notebook/Colab → `calificar.taller(CODIGO, GRUPO, NOMBRE_TALLER, NUM_PREGUNTAS)`
- Se crea un objeto “Taller” con estado en memoria (vector/lista de respuestas).

##### Registro de respuestas
- Notebook → `Taller.respuestas(indice, resultado)`
- Estado local: `Taller.resp` (inspección).

##### Calificación/registro remoto
- Notebook → `Taller.calificar()`
- Paquete → **Servidor remoto del docente** (API) para:
- validar puntos (0/1 por ítem),
- calcular nota,
- registrar intento,
- devolver mensaje (incluye “tiempo restante”, lo que sugiere que el servidor guarda ventanas de tiempo/cierre).

##### Validación de funciones
- Notebook → `cr.evafunciones(URL, GRUPO)`
- `eva.validar("nombre_funcion")` genera “código secreto”.
- Esto sugiere que:
- el validador obtiene referencia desde una **URL** (probablemente GitHub/raw),
- ejecuta o compara outputs (o llama a un servicio) y retorna token/código.

**Implicación para el diagrama:** hay al menos dos integraciones externas:
- **Grading/Notas API (Docente)**
- **Repositorio/URL de referencia (GitHub u otra fuente)**

##### Diagrama 1 — *System Context* (máximo nivel, “qué es y con qué habla”)
**Componentes a poner (cajas):**
- **Estudiante** (actor)
- **Notebook Runtime** (Jupyter/Colab/Python kernel)
- **Librería `calificar`** (instalada vía pip)
- **Servidor de Calificaciones (Docente)** (externo)
- **Repositorio de Taller/Referencia (GitHub URL)** (externo)
- (Opcional) **PyPI** como canal de distribución

**Relaciones (flechas):**
- Estudiante → Notebook: escribe soluciones y ejecuta celdas
- Notebook → `calificar`: invoca `taller()`, `respuestas()`, `calificar()`, `evafunciones()`
- `calificar` → Servidor Docente: POST/HTTP “registro de respuestas / obtención de nota / ventana de tiempo”
- `calificar` → GitHub URL: GET/HTTP “descarga referencia/metadata para validación”
- PyPI → Notebook: `pip install calificar`

**Detalle importante a etiquetar en las flechas:**
- Tipo de datos: `{CODIGO, GRUPO, NOMBRE_TALLER, respuestas[], timestamp}` hacia servidor
- Respuesta del servidor: `{vector puntos[], nota, mensaje, deadline/tiempo_restante}`

**Por qué este diagrama es clave aquí:** el principal riesgo/arquitectura está en integraciones y flujos de datos, no en microservicios internos.

##### Diagrama 2 — *Container/Runtime View* (dentro del lado “cliente”)
Aquí “contenedores” no son Docker; son **módulos runtime**.

**Cajas recomendadas:**
- **User Code (Notebook cells)**
- **`calificar` package**
- `__init__.py` (API pública)
- `core.py` (lógica)
- **Local Memory State**
- objeto Taller (respuestas en RAM)
- configuración (código(s), grupo, id taller, num preguntas)
- **HTTP Client** (puede ser `requests` u otro; si no se ve en el tree, dibújalo como “HTTP client (dependency)”)
- **Remote Grading API**
- **Remote Reference Source (GitHub/raw)**

**Flechas:**
- User Code → API pública (`taller`, `evafunciones`)
- Taller.respuestas() → Local Memory State (mutación)
- Taller.calificar() → HTTP Client → Remote Grading API
- evafunciones.validar() → HTTP Client → Remote Reference Source (y/o Remote API si aplica) → devuelve “secret code”

**Etiquetas a añadir:**
- “sync call” (bloqueante) vs “async” (probablemente sync)
- “serialization: JSON” hacia el servidor (altamente probable, dado `respuestas.json` y uso típico)

##### Diagrama 3 — *Component View* (dentro de `core.py`)
Aunque solo ves `core.py`, puedes y debes separarlo conceptualmente en componentes (aunque estén en un solo archivo hoy). “No sobrepensar” aquí significa **partirlo en piezas funcionales**:

**Subcomponentes a dibujar (como bloques dentro de `calificar.core`):**
##### Taller Factory / Constructor
- crea instancia con metadata: `CODIGO`, `GRUPO`, `NOMBRE_TALLER`, `NUM_PREGUNTAS`
##### Answer Store
- estructura de almacenamiento `resp` (lista/dict)
- validaciones de índice, tipo, rango
##### Scoring/Grading Orchestrator
- arma payload
- llama endpoint remoto
- interpreta respuesta (puntos, nota, mensaje)
##### Networking Layer
- construcción de URL endpoints
- retries/timeouts (si existen; si no, dibujar como “debería” o “implícito”)
##### Function Validator (`evafunciones`)
- manejo de URL de referencia
- introspección de función por nombre (lookup en namespace)
- comparación/validación
- generación del “código secreto”

**Interacciones internas:**
- Taller.respuestas() → Answer Store
- Taller.calificar() → Scoring Orchestrator → Networking Layer → Remote Grading API
- evafunciones.validar() → Function Validator → Networking Layer → GitHub URL → retorna token

**Por qué dibujar esto aunque esté en un archivo:** porque el diagrama debe reflejar responsabilidades y contratos, no necesariamente la organización actual del código.

##### Pautas específicas para este tipo de proyecto (librería + servicio externo)
- **Enfatiza contratos de API** y **data flow** (payloads, tokens, códigos secretos, tiempos).
- Distingue claramente **“local evaluation/collection”** vs **“authoritative grading”** (servidor).
- Incluye **límites de confianza**:
- Cliente (estudiante) es no-confiable
- Servidor docente es autoridad
- Explicita **fuentes externas** (GitHub URL) porque cambian el comportamiento del validador y son puntos de fallo.

Si quieres un diagrama aún más “real”: agrega un bloque “Docente/Administración” y “DB/Storage” detrás del “Servidor Docente” (aunque no esté en el repo). Está justificado por el README: “registrar sus calificaciones”.

##### Elementos visuales que debes exigir en el diagrama
- **Labels claros** (ej. “Remote Grading API”, “Function Reference Repo”, “Notebook Runtime”).
- **Flechas direccionales** con verbos: “submit answers”, “fetch reference”, “return grade”.
- Azul: componentes locales (Notebook, calificar)
- Rojo/Naranja: servicios externos (Grading API, GitHub)
- Verde: artefactos/paquetes (PyPI, wheel/sdist)
- Gris: datos/contenido (Big_Data datasets, enunciados.json)

##### Qué NO olvidar (detalle “esencial”)
- El objeto **Taller** como entidad central de estado (respuestas, metadata, nota).
- El flujo `evafunciones` como camino alterno al de “respuestas numéricas”.
- La dependencia de **tiempo/cierre de taller** (servidor devuelve “tiempo restante”): sugiere que el servidor mantiene reglas y calendario.
- El canal de distribución (**PyPI**) y el flujo de publicación (`publicar.bat`, `pyproject.toml`) si el diagrama incluye lifecycle.

##### Entregable recomendado (rápido y preciso)
Dibuja 3 láminas:
##### Componentes de core (Taller/AnswerStore/GradingOrchestrator/Networking/Validator)

Con eso capturas “tantos componentes como sea posible” sin inventar microservicios, y el diagrama queda fiel al propósito real del repo.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================================================
  %% Diagram: Ecosistema calificar (C4-ish: Context + Runtime + Components + Release/Content)
  %% Oriented vertically (TD) and grouped in subgraphs
  %% =========================================================

  %% -------------------------
  %% ACTORS / EXTERNALS
  %% -------------------------
  Student["Estudiante"]:::actor
  Notebook["Notebook Runtime\n(Jupyter/Colab + Python kernel)"]:::local

  PyPI[("PyPI Registry\n(wheels/sdist)")]:::dist
  GitHub["Repositorio/URL de referencia\n(GitHub raw u otra fuente)"]:::external
  GradingAPI["Servidor de Calificaciones (Docente)\nRemote Grading API"]:::external

  subgraph "Servidor Docente (fuera del repo)"
    TeacherAdmin["Docente/Administración"]:::external
    TeacherDB[("Storage/DB\n(intentos, notas, ventanas de tiempo)")]:::db
  end

  %% -------------------------
  %% REPO / SUPPLY CHAIN & CONTENT
  %% -------------------------
  subgraph "Repo (este proyecto)"
    RepoDocs["Documentación"]:::docs
    Readme["README (uso en Notebook/Colab)"]:::docs
    TalleresMd["Guía/índice de talleres"]:::docs
    EnunciadosJson["Metadata enunciados.json"]:::content

    Release["Distribución/Release"]:::dist
    PyProject["pyproject.toml\n(build, dependencias)"]:::dist
    PublicarBat["publicar.bat\n(publicación)"]:::dist
    EggInfo["calificar.egg-info\n(metadatos packaging)"]:::dist

    subgraph "Contenido académico / datasets (no runtime)"
      BigDataDir["Big_Data/"]:::content
      BigDataReadme["Big_Data/README.md"]:::content

      subgraph "Taller 1"
        T1Dir["Big_Data/Taller_1/"]:::content
        T1Resp["respuestas.json (T1)"]:::content
      end

      subgraph "Taller 2"
        T2Dir["Big_Data/Taller_2/"]:::content
        T2Datos["datos_reto.csv (T2)"]:::content
        T2Resp["respuestas.json (T2)"]:::content
      end

      subgraph "Taller 3"
        T3Dir["Big_Data/Taller_3/"]:::content
        T3Datos["Reporte_Crudo.csv (T3)"]:::content
        T3Resp["respuestas.json (T3)"]:::content
      end
    end

    subgraph "Librería Python (runtime installable)"
      CalificarPkg["Paquete Python: calificar"]:::pkg
      InitPy["API pública\n(__init__.py)\n(taller, evafunciones, ...)"]:::pkg
      CorePy["Core\n(core.py)"]:::core

      subgraph "Componentes conceptuales dentro de core.py"
        TallerFactory["Taller Factory/Constructor\n(CODIGO, GRUPO, NOMBRE_TALLER, NUM_PREGUNTAS)"]:::core
        AnswerStore["Answer Store\n(resp en RAM + validaciones)"]:::core
        GradeOrch["Scoring/Grading Orchestrator\n(payload, parse response)"]:::core
        NetLayer["Networking Layer\n(HTTP, endpoints, JSON)"]:::core
        FuncValidator["Function Validator\n(evafunciones + validar(func))\n(secret code)"]:::core
      end

      subgraph "Estado local (en memoria)"
        TallerObj["Objeto Taller\n(metadata + resp[] + nota/puntos)"]:::state
      end

      HttpClient["HTTP Client (dep.)\n(ej: requests)"]:::dep
    end
  end

  %% =========================================================
  %% CONTEXT VIEW (System Context)
  %% =========================================================
  Student -->|"escribe_soluciones_y_ejecuta_celdas"| Notebook
  Notebook -->|"pip_install"| PyPI
  Notebook -->|"import_y_llama_API\n(taller/evafunciones)"| CalificarPkg

  CalificarPkg -->|"submit_answers_JSON\n{CODIGO,GRUPO,taller,respuestas[],timestamp}"| GradingAPI
  GradingAPI -->|"return_grade\n{puntos[],nota,mensaje,tiempo_restante}"| CalificarPkg

  CalificarPkg -->|"fetch_reference_HTTP_GET\n(URL tipo GitHub)"| GitHub

  GradingAPI -->|"persist_intentos_y_reglas_de_tiempo"| TeacherDB
  TeacherAdmin -->|"administra_talleres_y_calificaciones"| GradingAPI

  %% =========================================================
  %% RUNTIME / CONTAINER VIEW (client-side modules)
  %% =========================================================
  Notebook -->|"taller(CODIGO,GRUPO,NOMBRE_TALLER,NUM_PREGUNTAS)"| InitPy
  InitPy -->|"crea_instancia"| CorePy
  CorePy -->|"instancia_y_estado"| TallerObj

  Notebook -->|"Taller.respuestas(i,resultado)"| TallerObj
  TallerObj -->|"mutate_resp[]/validar_indice_tipo_rango"| AnswerStore

  Notebook -->|"Taller.calificar()"| TallerObj
  TallerObj -->|"arma_payload"| GradeOrch
  GradeOrch -->|"usa"| NetLayer
  NetLayer -->|"HTTP_sync_JSON"| HttpClient
  HttpClient -->|"POST_submit_answers"| GradingAPI
  GradingAPI -->|"respuesta(puntos,nota,mensaje,deadline)"| HttpClient
  HttpClient -->|"parse_response"| NetLayer
  NetLayer -->|"actualiza_resultados"| GradeOrch
  GradeOrch -->|"set_nota_y_puntos_en_estado"| TallerObj

  Notebook -->|"evafunciones(URL,GRUPO)"| InitPy
  InitPy -->|"factory_validador"| FuncValidator
  FuncValidator -->|"validar(nombre_funcion)"| FuncValidator
  FuncValidator -->|"usa"| NetLayer
  NetLayer -->|"GET_reference"| HttpClient
  HttpClient -->|"download_ref/metadata"| GitHub
  FuncValidator -->|"return_secret_code"| Notebook

  %% =========================================================
  %% COMPONENT VIEW (inside core.py, conceptual)
  %% =========================================================
  CorePy -->|"define"| TallerFactory
  CorePy -->|"define"| AnswerStore
  CorePy -->|"define"| GradeOrch
  CorePy -->|"define"| NetLayer
  CorePy -->|"define"| FuncValidator

  TallerFactory -->|"build_Taller"| TallerObj
  TallerObj -->|"delegates_respuestas()"| AnswerStore
  TallerObj -->|"delegates_calificar()"| GradeOrch
  GradeOrch -->|"calls"| NetLayer
  FuncValidator -->|"calls"| NetLayer

  %% =========================================================
  %% CONTENT RELATIONSHIPS (academic materials)
  %% =========================================================
  Readme -->|"documenta_flujos_de_uso"| Notebook
  TalleresMd -->|"indice_de_contenido"| BigDataDir
  EnunciadosJson -->|"metadata_para_enunciados"| BigDataDir

  BigDataDir -->|"incluye"| T1Dir
  BigDataDir -->|"incluye"| T2Dir
  BigDataDir -->|"incluye"| T3Dir
  T1Dir -->|"fixtures/esperados"| T1Resp
  T2Dir -->|"datasets"| T2Datos
  T2Dir -->|"fixtures/esperados"| T2Resp
  T3Dir -->|"datasets"| T3Datos
  T3Dir -->|"fixtures/esperados"| T3Resp
  BigDataReadme -->|"describe_datasets"| BigDataDir

  %% =========================================================
  %% RELEASE FLOW (supply chain)
  %% =========================================================
  PyProject -->|"build_config"| Release
  PublicarBat -->|"publish_flow"| Release
  Release -->|"upload"| PyPI
  EggInfo -->|"packaging_metadata"| Release
  CalificarPkg -->|"distributed_as"| PyPI

  %% =========================================================
  %% Click events (from component_mapping)
  %% =========================================================
  click CalificarPkg "https://github.com/jclezamap/calificar/tree/main/src/calificar/"
  click InitPy "https://github.com/jclezamap/calificar/blob/main/src/calificar/__init__.py"
  click CorePy "https://github.com/jclezamap/calificar/blob/main/src/calificar/core.py"
  click PyProject "https://github.com/jclezamap/calificar/blob/main/pyproject.toml"
  click PublicarBat "https://github.com/jclezamap/calificar/blob/main/publicar.bat"
  click EggInfo "https://github.com/jclezamap/calificar/tree/main/src/calificar.egg-info/"
  click Readme "https://github.com/jclezamap/calificar/blob/main/README.md"
  click TalleresMd "https://github.com/jclezamap/calificar/blob/main/TALLERES.md"
  click EnunciadosJson "https://github.com/jclezamap/calificar/blob/main/enunciados.json"
  click BigDataDir "https://github.com/jclezamap/calificar/tree/main/Big_Data/"
  click T1Dir "https://github.com/jclezamap/calificar/tree/main/Big_Data/Taller_1/"
  click T2Dir "https://github.com/jclezamap/calificar/tree/main/Big_Data/Taller_2/"
  click T3Dir "https://github.com/jclezamap/calificar/tree/main/Big_Data/Taller_3/"
  click BigDataReadme "https://github.com/jclezamap/calificar/blob/main/Big_Data/README.md"
  click T1Resp "https://github.com/jclezamap/calificar/blob/main/Big_Data/Taller_1/respuestas.json"
  click T2Datos "https://github.com/jclezamap/calificar/blob/main/Big_Data/Taller_2/datos_reto.csv"
  click T2Resp "https://github.com/jclezamap/calificar/blob/main/Big_Data/Taller_2/respuestas.json"
  click T3Datos "https://github.com/jclezamap/calificar/blob/main/Big_Data/Taller_3/Reporte_Crudo.csv"
  click T3Resp "https://github.com/jclezamap/calificar/blob/main/Big_Data/Taller_3/respuestas.json"

  %% =========================================================
  %% Styles (color is critical)
  %% =========================================================
  classDef actor fill:#E6F0FF,stroke:#2B6CB0,stroke-width:2px,color:#102A43
  classDef local fill:#DCEEFB,stroke:#2C5282,stroke-width:2px,color:#102A43
  classDef pkg fill:#C3DAFE,stroke:#2B6CB0,stroke-width:2px,color:#102A43
  classDef core fill:#BEE3F8,stroke:#2A4365,stroke-width:2px,color:#102A43
  classDef state fill:#E9D8FD,stroke:#6B46C1,stroke-width:2px,color:#2D1B69
  classDef dep fill:#E2E8F0,stroke:#4A5568,stroke-width:2px,color:#1A202C
  classDef external fill:#FED7D7,stroke:#C53030,stroke-width:2px,color:#742A2A
  classDef db fill:#FBD38D,stroke:#B7791F,stroke-width:2px,color:#4A2C0A
  classDef dist fill:#C6F6D5,stroke:#2F855A,stroke-width:2px,color:#1C4532
  classDef content fill:#EDF2F7,stroke:#718096,stroke-width:2px,color:#1A202C
  classDef docs fill:#FAF089,stroke:#B7791F,stroke-width:2px,color:#4A2C0A
```
