Arquitectura de referencia — Plataforma de Datos Académicos
Versión 1.0 · 5.º semestre
1. Objetivo
Construir una plataforma de datos que tome la información académica de sus fuentes, la valide, la guarde en una base de datos institucional, la procese en un lakehouse y la publique como indicadores para una aplicación web.
La arquitectura sigue el patrón estándar de una plataforma de datos empresarial:
FUENTES → INGESTA → BASE OPERACIONAL → LAKEHOUSE → SERVICIO → CONSUMO
Cada capa tiene un dueño, una entrada, una salida y un contrato. Ninguna capa se salta a otra.
2. Vista de contexto
flowchart LR
F["Fuentes<br/>sistemas académicos<br/>(exportaciones CSV)"]
P["Plataforma de Datos Académicos"]
U1["Coordinador académico"]
U2["Tutor"]
U3["Docente"]
F -->|archivos diarios| P
P -->|indicadores y alertas| U1
P -->|estudiantes en riesgo| U2
P -->|rendimiento de sus cursos| U3
3. Arquitectura por capas
flowchart LR
subgraph L0["0 · Fuentes"]
SRC[/"CSV diarios<br/>semestres, cursos, estudiantes,<br/>notas, asistencia"/]
end
subgraph L1["1 · Ingesta y calidad — Prof. Isael"]
J1["Job 1<br/>ingesta-academica"]
J2["Job 2<br/>exportacion-lakehouse"]
end
subgraph L2["2 · Base operacional — Prof. Canales"]
ORA[("Oracle<br/>esquema ACADEMICO")]
end
subgraph L3["3 · Lakehouse — Prof. Jesús"]
S3[("AWS S3<br/>landing")]
BR[(Bronze)]
SV[(Silver)]
GD[(Gold)]
end
subgraph L4["4 · Servicio — Prof. Condori"]
API["API REST"]
end
subgraph L5["5 · Consumo — Prof. Valery"]
WEB["Aplicación web"]
end
SRC --> J1 -->|MERGE| ORA
ORA -->|lectura| J2 -->|Parquet| S3
S3 --> BR --> SV --> GD
GD -->|SQL Warehouse| API
ORA -.->|consultas operativas| API
API -->|JSON| WEB
| Capa | Nombre estándar | Responsable | Tecnología | Entrada | Salida |
|---|---|---|---|---|---|
| 0 | Sistemas fuente | — | CSV | — | Archivos diarios |
| 1 | Ingesta y calidad de datos | Prof. Isael | Apache Spark | CSV · Oracle | Oracle · S3 |
| 2 | Base de datos operacional (ODS) | Prof. Canales | Oracle | Cargas del Job 1 | Datos íntegros y consultables |
| 3 | Lakehouse (Medallion) | Prof. Jesús | AWS S3 · Databricks · Delta Lake | Parquet en S3 | Tablas Gold |
| 4 | Capa de servicio (API) | Prof. Condori | Spring Boot | Gold · Oracle | Endpoints REST |
| 5 | Capa de consumo | Prof. Valery | React | API REST | Pantallas y dashboards |
Prof. Isael es el punto de entrada: todo dato que entra a la plataforma pasa primero por sus jobs. Lo que no cumple las reglas de calidad no llega a la base de datos.
4. Flujo de una ejecución diaria
sequenceDiagram
autonumber
participant F as Fuentes (CSV)
participant J1 as Job 1 · Ingesta (Prof. Isael)
participant O as Oracle (Prof. Canales)
participant J2 as Job 2 · Exportación (Prof. Isael)
participant L as Lakehouse (Prof. Jesús)
participant A as API (Prof. Condori)
participant W as Web (Prof. Valery)
F->>J1: 01:00 llegan los CSV del día
J1->>J1: valida reglas de calidad
J1->>O: MERGE de filas válidas
J1->>O: INSERT filas rechazadas en CUARENTENA
J1->>O: INSERT registro en CARGAS
J2->>O: 02:00 lee lo modificado desde la última exportación
J2->>L: escribe Parquet + _SUCCESS en S3
L->>L: 03:00 Bronze → Silver → Gold
W->>A: el coordinador abre el dashboard
A->>L: consulta Gold
A-->>W: indicadores + fecha de actualización
5. Componentes
5.1 Ingesta y calidad — Prof. Isael
Responsabilidad: ser la única puerta de entrada de datos a la plataforma y garantizar su calidad.
| Job | Entrada | Salida | Frecuencia |
|---|---|---|---|
Job 1 · ingesta-academica |
CSV del día | Oracle: tablas maestras y transaccionales, CUARENTENA, CARGAS |
Diaria, 01:00 |
Job 2 · exportacion-lakehouse |
Oracle (incremental por FECHA_ACTUALIZACION) |
S3 landing/ en Parquet + _SUCCESS |
Diaria, 02:00 |
Job 1 — etapas:
flowchart LR
A[Lectura CSV<br/>como texto] --> B[Validación<br/>reglas de calidad]
B -->|válidas| C[Tipado y<br/>normalización]
B -->|rechazadas| Q[(CUARENTENA)]
C --> D{Umbral de<br/>rechazo}
D -->|dentro| E[MERGE a Oracle]
D -->|excedido| X[Lote rechazado<br/>código de salida ≠ 0]
E --> R[(CARGAS)]
Reglas de calidad (ISO/IEC 25012):
| Dimensión | Ejemplo |
|---|---|
| Completitud | ESTUDIANTE_ID no vacío |
| Validez | NOTA entre 0 y 20; ESTADO ∈ {P, F, T, J} |
| Unicidad | una nota por estudiante, curso, periodo y evaluación |
| Integridad referencial | el curso de la nota existe |
| Consistencia | los pesos de las evaluaciones de un curso suman 1 |
Garantías:
- Idempotencia: correr dos veces el mismo día no duplica datos (
MERGEpor clave). - Trazabilidad: cada fila en Oracle tiene el
EJECUCION_IDde la carga que la escribió. - Atomicidad del lote: si se excede el umbral, no se escribe nada en las tablas de negocio.
- Spark no crea tablas: solo inserta, actualiza y lee.
5.2 Base operacional — Prof. Canales
Responsabilidad: modelo de datos, integridad, seguridad y rendimiento de la base institucional.
Esquema ACADEMICO
├── Maestras SEMESTRES · CURSOS · ESTUDIANTES
├── Transaccionales NOTAS · ASISTENCIA
└── Control CARGAS · CUARENTENA
Columnas de auditoría en todas las tablas de negocio:
FECHA_CREACION · FECHA_ACTUALIZACION · EJECUCION_ID
| Usuario Oracle | Permisos | Lo usa |
|---|---|---|
ACADEMICO_OWNER |
Dueño del esquema (DDL) | Scripts de despliegue |
ACADEMICO_ETL |
SELECT, INSERT, UPDATE sobre tablas de negocio y control | Jobs 1 y 2 |
ACADEMICO_API |
Solo SELECT | API |
Entregables: scripts DDL versionados, llaves primarias y foráneas, índices para las consultas de la API y para la exportación incremental, y un plan de respaldo.
5.3 Lakehouse — Prof. Jesús
Responsabilidad: convertir los datos operacionales en indicadores analíticos.
s3://academico-<ambiente>/landing/<tabla>/fecha_carga=YYYY-MM-DD/
part-*.parquet
_SUCCESS ← solo se procesa la carpeta que lo tiene
Unity Catalog: academico
├── bronze.<tabla> copia fiel del landing + metadatos de carga
├── silver.<tabla> tipado, deduplicado, historial de cambios
└── gold
├── rendimiento estudiante × curso × periodo
├── cursos_resumen curso × periodo
├── alertas_asistencia estudiante × curso
└── estudiantes_riesgo estudiante × periodo
Orquestación con Databricks Workflows a las 03:00: bronze → silver → gold. Exposición de Gold por Databricks SQL Warehouse.
5.4 Servicio — Prof. Condori
Responsabilidad: exponer los datos a la aplicación de forma segura y estable.
| Módulo | Fuente | Endpoints |
|---|---|---|
| Analítico | Gold (SQL Warehouse) | /api/v1/indicadores/rendimiento · /cursos · /alertas · /riesgo |
| Operativo | Oracle (ACADEMICO_API, solo lectura) |
/api/v1/estudiantes · /cursos · /cargas |
- Solo lectura. La API no escribe datos de negocio: la única entrada de datos es la capa de ingesta.
- No calcula indicadores: si falta uno, se agrega a Gold.
- Autenticación con JWT, roles
COORDINADOR,TUTOR,DOCENTE. - Documentación con OpenAPI; versionado en la ruta (
/api/v1).
5.5 Consumo — Prof. Valery
Responsabilidad: que cada usuario encuentre la información que necesita.
| Rol | Vistas |
|---|---|
| Coordinador | Dashboard general, resumen por curso, estado de las cargas |
| Tutor | Estudiantes en riesgo, alertas de asistencia |
| Docente | Rendimiento de sus cursos |
- Consume solo la API.
- Muestra siempre la fecha de última actualización de los datos.
6. Contratos entre capas
Un contrato es el acuerdo de lo que una capa entrega a la siguiente. Se guarda en contratos/, tiene versión y solo lo cambia quien lo define.
| Contrato | Define | Consume | Contenido |
|---|---|---|---|
fuentes.md |
Prof. Isael | — | Archivos esperados, columnas, formato, hora de llegada |
modelo-oracle.md |
Prof. Canales | Prof. Isael, Prof. Condori | Tablas, columnas, tipos, llaves |
landing-s3.md |
Prof. Isael | Prof. Jesús | Ruta, particiones, formato, marcador _SUCCESS |
gold.md |
Prof. Jesús | Prof. Condori | Tablas, columnas, granularidad, hora de actualización |
openapi.yaml |
Prof. Condori | Prof. Valery | Endpoints, parámetros, respuestas, errores |
Con los contratos, cada capa se desarrolla y prueba sola con datos simulados que los respetan.
7. Aspectos transversales
| Aspecto | Estándar del proyecto |
|---|---|
| Seguridad | Un usuario por componente con mínimo privilegio. Credenciales en variables de entorno, nunca en el repositorio. |
| Trazabilidad | EJECUCION_ID en logs, Oracle, S3 y Gold: un dato se rastrea de punta a punta. |
| Observabilidad | Tabla CARGAS (qué entró, cuánto, cuándo); CUARENTENA (qué se rechazó y por qué); alertas del workflow si falla. |
| Calidad de software | Pruebas unitarias y de integración por componente; CI en cada push; revisión por merge request. |
| Nomenclatura | Oracle en MAYUSCULAS; S3 y lakehouse en snake_case; todo en español. |
| Ambientes | dev en local (Docker: Oracle, API, web; Spark local) y prod en la nube (S3 + Databricks). |
8. Decisiones de arquitectura
| # | Decisión | Motivo |
|---|---|---|
| D1 | La ingesta es la única entrada de datos | Un solo lugar donde se garantiza la calidad. |
| D2 | La calidad se valida antes de Oracle | La base institucional solo contiene datos confiables. |
| D3 | Oracle como base operacional y Databricks como analítica | Las consultas analíticas pesadas no afectan a la base operacional. |
| D4 | S3 como zona de aterrizaje entre Oracle y Databricks | Desacopla ambos sistemas; permite reprocesar sin volver a leer Oracle. |
| D5 | Carga con MERGE por clave |
Las cargas se pueden repetir sin duplicar datos. |
| D6 | Las tablas las crean los scripts del DBA, no Spark | Separación de responsabilidades; control de cambios del esquema. |
| D7 | La API solo lee | Evita una segunda entrada de datos sin validar. |
| D8 | Los indicadores se calculan solo en Gold | Una sola definición de cada métrica. |
9. Estructura del repositorio
plataforma-datos-academicos/
├── contratos/ acuerdos entre capas
├── ingesta/ Prof. Isael — Jobs 1 y 2 (Spark), reglas de calidad, pruebas
├── database/ Prof. Canales — DDL, usuarios, índices, datos semilla
├── lakehouse/ Prof. Jesús — notebooks y workflow de Databricks
├── api/ Prof. Condori — servicio REST
├── web/ Prof. Valery — aplicación web
├── docker-compose.yml Oracle + API + web en local
└── .gitlab-ci.yml un job de CI por carpeta