Skip to content
PageWell
Arquitectura de referencia — Plataforma de Datos Académicos ISAEL JAVIER FATAMA GODOYUpdated 2026-11-21

Copy


Arquitectura de referencia — Plataforma de Datos Académicos

8 min read Updated 2026-11-21

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 (MERGE por clave).
  • Trazabilidad: cada fila en Oracle tiene el EJECUCION_ID de 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