Diagrama C4 — Vista del Sistema

Esta página muestra la arquitectura del sistema IngelCoding en dos niveles de abstracción: Contexto (quién interactúa con el sistema y desde dónde) y Contenedores (los bloques internos principales).

Para explorar el grafo interactivo completo: Vista del grafo

---

Nivel 1 — Contexto del Sistema

Muestra IngelCoding como una caja negra y sus relaciones con actores externos.

C4Context
    title IngelCoding — Contexto del Sistema

    Person(analista, "Analista / Desarrollador", "Opera los pipelines, revisa logs, mantiene el sistema")
    Person(jefatura, "Jefatura / Gerencia", "Consume dashboards Power BI y reportes consolidados")
    Person(admin, "Administración", "Consulta Google Sheets con facturación y pedidos al día")

    System(ingelcoding, "IngelCoding", "Automatización de gestión de proyectos e ingeniería para Ingelsur. Captura datos desde correo y sistemas externos, los procesa y publica reportes.")

    System_Ext(imap, "Correo Corporativo (Gmail/IMAP)", "Facturas PDF, pedidos HES, avisos SAP — tres cuentas corporativas")
    System_Ext(hes, "Sistema HES", "Pedidos y órdenes de trabajo de Ingelsur")
    System_Ext(sap, "SAP", "Sistema de gestión empresarial — reportes y saldos")
    System_Ext(drive, "Google Drive / Excel", "Archivos de operación: cronogramas, reportes de campo")
    System_Ext(gsheets, "Google Sheets", "Hojas compartidas para el equipo de administración")
    System_Ext(pbi, "Power BI Service", "Dashboards de jefatura — 4 informes por zona y área")

    Rel(imap, ingelcoding, "Entrega facturas y pedidos", "IMAP/TLS")
    Rel(hes, ingelcoding, "Entrega reportes de OTs", "Email/API")
    Rel(sap, ingelcoding, "Entrega reportes de saldos", "Email/API")
    Rel(drive, ingelcoding, "Archivos Excel de operación", "gspread/Drive API")
    Rel(ingelcoding, gsheets, "Publica datos al día", "gspread API")
    Rel(ingelcoding, pbi, "Alimenta el DW vía Gateway", "ODBC/Supabase")
    Rel(analista, ingelcoding, "Opera y mantiene", "CLI/Python")
    Rel(jefatura, pbi, "Consulta dashboards", "Browser")
    Rel(admin, gsheets, "Consulta facturación y pedidos", "Browser")

---

Nivel 2 — Contenedores

Descompone IngelCoding en sus bloques internos principales.

C4Container
    title IngelCoding — Contenedores

    Person(analista, "Analista", "Opera los pipelines")

    System_Ext(imap, "Correo IMAP", "Facturas, pedidos, avisos")
    System_Ext(drive, "Drive / Excel", "Archivos de operación")
    System_Ext(gsheets, "Google Sheets", "Hojas compartidas")
    System_Ext(supabase, "Supabase (PostgreSQL)", "DW en la nube")
    System_Ext(pbi, "Power BI Service", "Dashboards")

    Container_Boundary(ic, "IngelCoding") {
        Container(ingesta, "Capa de Ingesta", "Python — imap_client.py, raw_loaders.py", "Captura correos y archivos. Persiste en RAW Store (Parquet).")
        ContainerDb(raw, "RAW Store", "Parquet/JSONL", "Emails y archivos crudos. Dedup por message_id.")
        Container(pipelines, "Pipelines de Negocio", "Python — 10 pipelines main_*.py", "Transforma datos crudos: facturación, HES, SAP, Gantt, valorizaciones, cierres, pagos, costos, productividad.")
        Container(orquestador, "Orquestador", "Python — run_pipeline.py", "Gestiona ejecución en 2 waves: fetchers primero, pipelines principales después.")
        ContainerDb(sqlite, "Data Warehouse SQLite", "SQLite — 32 tablas", "Archivo histórico local. Fuente para migraciones y Power BI Gateway.")
        Container(migrador, "Migrador Cloud", "Python — migrate_all.py", "Sincroniza SQLite → Supabase PostgreSQL (9 tablas, modo SELECTIVE).")
    }

    Rel(imap, ingesta, "Correos/adjuntos", "IMAP/TLS")
    Rel(drive, ingesta, "Archivos Excel", "Drive API")
    Rel(ingesta, raw, "Persiste crudos", "Parquet")
    Rel(raw, pipelines, "Lee datos crudos")
    Rel(analista, orquestador, "Ejecuta", "CLI: python run_pipeline.py --all")
    Rel(orquestador, pipelines, "Orquesta waves")
    Rel(pipelines, sqlite, "Escribe resultados", "SQLite")
    Rel(pipelines, gsheets, "Publica al día", "gspread API")
    Rel(sqlite, migrador, "Lee tablas")
    Rel(migrador, supabase, "Migra tablas", "Supabase Management API")
    Rel(supabase, pbi, "Alimenta dashboards", "PostgreSQL/SSL")

---

Notas de arquitectura

• Wave 1 (paralelo): fetch_saldos, fetch_cierres — descargan reportes de la nube antes que los pipelines principales los necesiten.
• Wave 2 (secuencia): 8 pipelines de dominio — cada uno idempotente sobre su raw correspondiente.
• Stage PUBLISH integrado: facturacion y pedidos_HES escriben a Google Sheets como etapa final del pipeline, no como paso separado (desde 2026-04-25).
• Trazabilidad: cada ejecución queda registrada en pipeline_runs con hash del input, hash del código y rango de fechas procesado.

Para las decisiones arquitectónicas detrás de este diseño, ver ADRs — Decisiones.

Diagrama generado desde la arquitectura documentada en portal-data.json y Arquitectura-Completa.md.