# ecg301997/emailsender architecture

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

- Interactive diagram: https://gitdiagram.com/ecg301997/emailsender
- Repository: https://github.com/ecg301997/emailsender

## Overview

##### Tipo y propósito del proyecto (según file tree + README)
**Tipo:** Aplicación Node.js “batch/CLI” (se ejecuta con `node index.js`) para **envío masivo de correos** a partir de una **base Excel** y **archivos adjuntos** en disco.
**Propósito:** Leer un Excel (“BD PARA COBRO.xlsx”), tomar por fila el **CORREO** y la **MARCACION** (nombre del archivo a adjuntar), enviar el correo con anexos y generar un **Excel de reporte** (“reporte correos”) con éxitos/errores.

Indicios en el repo:
- `index.js`: entrypoint principal (README lo indica).
- `Excel.js`: módulo dedicado a manipulación de Excel (lectura y/o escritura del reporte).
- `config.json` + `.env`: configuración/secretos (SMTP, rutas, etc.).
- `server.js` + `public/index.html`: sugiere **una UI web mínima** (probablemente Express + estáticos) para servir un formulario/landing; aunque el README menciona un **link a formulario externo**, el repo contiene una opción local.
- `package.json`: dependencias y scripts (no visibles aquí, pero importantes para etiquetar tecnologías en el diagrama).

##### Cómo analizar la estructura y convertirla en arquitectura “dibujable”
Piensa en 3 niveles (estilo C4, aunque no necesitas llamarlo así):
##### Contexto: quién usa el sistema y con qué servicios externos interactúa.
2. **Contenedores**: procesos ejecutables (CLI script, servidor web), almacenes (filesystem), servicios externos (SMTP).
##### Componentes: módulos internos (Excel.js, mailer, logger/reporting, config loader).

Este proyecto se beneficia mucho de un diagrama que muestre **flujo de datos** (Excel → envío → reporte) y **dependencias externas** (SMTP, filesystem, formulario).

##### Actores / Operación
- **Operador (usuario)**: ejecuta `node index.js`, revisa consola y abre el Excel “reporte correos”.
- **Destinatarios**: reciben correos.

##### Artefactos / Datos (muy relevantes en este proyecto)
- **Archivo fuente Excel**: `BD PARA COBRO.xlsx` (ruta configurada en `index.js`).
- Campos clave: `CORREO`, `MARCACION`.
- Hoja usada: `sheetName` (configurable).
- **Carpeta de adjuntos**: (README menciona `archives/`) + otros anexos requeridos.
- **Archivo resultado Excel**: “reporte correos.xlsx” (o nombre similar) con estado por destinatario.

##### Procesos / Ejecutables
- **CLI Batch Runner (`index.js`)**:
- Orquesta todo el flujo.
- Contiene variables configurables: `link`, `mes`, `limitDate`, `path`, `sheetName`.
- **Servidor Web (`server.js`)** (si realmente se usa):
- Sirve `public/index.html`.
- Puede representar una UI local alternativa (aunque el README hable de un link externo).

##### Módulos internos (componentes lógicos)
- **Excel Service (`Excel.js`)**
- Leer la hoja `sheetName`.
- Extraer `CORREO` y `MARCACION`.
- Escribir “reporte correos” con resultados.
- **Mail Sender / SMTP Client** (probable Nodemailer u otro)
- Construir asunto/cuerpo usando `mes`, `limitDate`, `link`.
- Adjuntar archivos según `MARCACION` (filesystem).
- Enviar a cada `CORREO`.
- **Attachment Resolver**
- Dado `MARCACION`, localizar archivo en `archives/` (y validar existencia).
- **Config Loader**
- Carga `.env` / `config.json` (credenciales SMTP, host/puerto, etc.).
- **Logger / Result Collector**
- Acumula éxitos/errores por fila.
- Pasa esos resultados a Excel Service para persistir el reporte.

##### Dependencias externas
- **Proveedor de correo / Servidor SMTP** (Gmail, Office365, SMTP corporativo, etc.).
- **Formulario externo** (por `link`) si aplica: NO es parte del repo, pero impacta el contenido del correo (ponlo como “External Form URL”).

##### Relaciones e interacciones (qué flechas dibujar)
Dibuja el flujo como una “pipeline” con flechas direccionales claras:

##### Excel Service → (retorna) → lista de registros `{CORREO, MARCACION, ...}`
5) **index.js** → (por cada registro) → **Attachment Resolver** → (lee) → **Filesystem (archives/ + anexos)**
6) **index.js** → **Mail Sender** → (SMTP) → **Servidor/Proveedor de Email** → **Destinatarios**
##### (Opcional) Operador → (abre) → reporte correos.xlsx

Si incluyes `server.js`:
- **Operador** → **Browser** → **Web Server (server.js)** → (sirve) → `public/index.html`
y marca si ese servidor es **opcional** o “modo alternativo” (porque el README prioriza `node index.js`).

##### Patrones / principios arquitectónicos a resaltar en el diagrama
- **Batch processing / ETL-like**: Excel (entrada) → procesamiento → SMTP (salida) → Excel (reporte).
- **Separation of concerns por módulos**: orquestación (index.js) vs utilidades (Excel.js) vs infraestructura (SMTP/filesystem/config).
- **Externalized configuration**: `.env` y/o `config.json` (separar secretos y parámetros del código).

##### Tecnologías a etiquetar explícitamente (en cajas o notas)
Aunque no vemos `package.json`, por el tipo de proyecto normalmente aparecerán:
- **Node.js runtime**
- Librería Excel: `xlsx` o `exceljs` (valídalo en `package.json`)
- Cliente SMTP: `nodemailer` (valídalo en `package.json`)
- (Si aplica) **Express** en `server.js`

En el diagrama, pon “Node.js” en el contenedor principal y agrega “exceljs/xlsx”, “nodemailer”, “express” como *technology tags* en los componentes relevantes.

##### Diagrama 1 (recomendado): “Container + Data Flow” (el más útil aquí)
Incluye:
- Actor: Operador
- Contenedores: CLI (index.js), opcional Web Server (server.js)
- Almacenes: BD PARA COBRO.xlsx, archives/, reporte correos.xlsx
- Servicio externo: SMTP Provider, External Form URL
- Flechas numeradas (1..9) como el flujo anterior

Caja grande: **CLI Batch Runner (index.js)** y dentro:
- Config Loader
- Excel Service (Excel.js)
- Attachment Resolver
- Mail Sender (SMTP Client)
- Result Collector / Reporter

Esto ayuda a discutir mantenimiento, testeo, y puntos de fallo.

##### Reglas visuales (para que el diagrama sea inequívoco y “audit-able”)
- **Etiquetas claras**:
- Usa nombres reales del repo: `index.js`, `Excel.js`, `server.js`, `public/index.html`, `.env`, `config.json`.
- Usa nombres reales de artefactos: “BD PARA COBRO.xlsx”, “reporte correos.xlsx”, “archives/”.
- **Flechas con verbo** (no solo líneas): “read”, “write”, “send SMTP”, “resolve attachment”, “serve static”.
- Rectángulos azules: procesos/servicios (Node CLI, Web Server)
- Cilindros: datos/archivos (Excel input/output)
- Carpeta: filesystem/attachments
- Nube: servicios externos (SMTP, Form URL)
- **Diferencia “runtime vs build-time”**:
- Este proyecto es principalmente runtime; no mezcles `package-lock.json` como componente en ejecución (solo como nota de build/deps).
- **Marca lo opcional**:
- Si `server.js` no es esencial para el flujo descrito en README, dibújalo con línea punteada o etiqueta “Optional”.

##### Checklist final (para validar que el diagrama quedó “completo”)
- ¿Se ve claramente que el trigger es `node index.js`?
- ¿Se ve el Excel de entrada, las columnas CORREO/MARCACION y la hoja `sheetName` (al menos como nota)?
- ¿Se ve de dónde salen los adjuntos (archives/ + nombre por MARCACION)?
- ¿Se ve el servicio SMTP como dependencia externa?
- ¿Se ve el Excel de reporte como salida?
- ¿Queda claro qué configuración viene de `.env` / `config.json` vs variables en `index.js`?

Con esto, el diagrama no solo “representa” el repo: también explica el flujo operativo real (que es lo más importante en una app de envío masivo por Excel).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% ================
    %% Actors & External
    %% ================
    Operator["Operador (Usuario)"]:::actor
    Recipients["Destinatarios"]:::actor

    SMTP["Proveedor Email / Servidor SMTP"]:::external
    FormURL["External Form URL (link en correo)"]:::external

    %% ================
    %% Runtime (Node.js)
    %% ================
    subgraph "Runtime Node.js"
        direction TB

        subgraph "Batch/CLI Mode (Principal)"
            direction TB
            CLI["CLI Batch Runner (index.js)\nTech: Node.js"]:::process

            subgraph "Componentes internos (lógicos)"
                direction TB
                Config["Config Loader\n(.env + config.json)"]:::component
                ExcelSvc["Excel Service (Excel.js)\nTech: exceljs/xlsx"]:::component
                Attach["Attachment Resolver\n(resuelve MARCACION)"]:::component
                Mailer["Mail Sender / SMTP Client\nTech: nodemailer"]:::component
                Results["Logger / Result Collector\n(OK/ERROR por fila)"]:::component
            end
        end

        subgraph "Web UI Mode (Opcional)"
            direction TB
            WebServer["Servidor Web (server.js)\nTech: express"]:::process
            StaticUI["UI Estática (public/index.html)"]:::frontend
            PublicDir["Directorio estáticos (public/)"]:::frontend
        end
    end

    %% ================
    %% Data Stores (FS)
    %% ================
    subgraph "Filesystem / Artefactos"
        direction TB
        InputXlsx[("BD PARA COBRO.xlsx\nCampos: CORREO, MARCACION\nHoja: sheetName")]:::datastore
        Archives[["Carpeta adjuntos (archives/)"]]:::folder
        ReportXlsx[("reporte correos.xlsx\n(éxitos/errores)")]:::datastore
    end

    %% ======================
    %% Build/Dependencies Note
    %% ======================
    subgraph "Build / Dependencias (No runtime)"
        direction TB
        Pkg["package.json\n(deps/scripts)"]:::meta
        Lock["package-lock.json\n(lockfile)"]:::meta
    end

    %% ================
    %% Main Pipeline (1..9)
    %% ================
    Operator -->|"1) ejecuta node index.js"| CLI
    CLI -->|"2) read config"| Config
    CLI -->|"3) read sheetName"| ExcelSvc
    ExcelSvc -->|"3) open/read"| InputXlsx
    ExcelSvc -->|"4) retorna registros {CORREO,MARCACION}"| CLI
    CLI -->|"5) resolve attachment (MARCACION)"| Attach
    Attach -->|"5) read"| Archives
    CLI -->|"6) send email (subject/body uses mes,limitDate,link)"| Mailer
    Mailer -->|"6) SMTP"| SMTP
    SMTP -->|"deliver"| Recipients
    Mailer -->|"7) result OK/ERROR"| Results
    Results -->|"8) write report rows"| ExcelSvc
    ExcelSvc -->|"8) generate"| ReportXlsx
    Operator -->|"9) abre reporte"| ReportXlsx

    %% External link used in email content
    CLI -.->|"uses link in email body"| FormURL

    %% Optional Web UI (dotted)
    Operator -.->|"opcional: abre en browser"| WebServer
    WebServer -.->|"serve static"| PublicDir
    PublicDir -.->|"contains"| StaticUI

    %% Dependencies association (non-runtime, dotted)
    CLI -.->|"deps/scripts"| Pkg
    WebServer -.->|"deps"| Pkg
    Pkg -.->|"locked by"| Lock

    %% =================
    %% Click Events
    %% =================
    click CLI "https://github.com/ecg301997/emailsender/blob/main/index.js"
    click ExcelSvc "https://github.com/ecg301997/emailsender/blob/main/Excel.js"
    click Config "https://github.com/ecg301997/emailsender/blob/main/.env"
    click Config "https://github.com/ecg301997/emailsender/blob/main/config.json"
    click WebServer "https://github.com/ecg301997/emailsender/blob/main/server.js"
    click StaticUI "https://github.com/ecg301997/emailsender/blob/main/public/index.html"
    click PublicDir "https://github.com/ecg301997/emailsender/tree/main/public/"
    click Pkg "https://github.com/ecg301997/emailsender/blob/main/package.json"
    click Lock "https://github.com/ecg301997/emailsender/blob/main/package-lock.json"

    %% =================
    %% Styles (Color)
    %% =================
    classDef actor fill:#FFE7C2,stroke:#B8741A,stroke-width:1px,color:#2B1A00
    classDef process fill:#D6ECFF,stroke:#1E64A0,stroke-width:1.2px,color:#06233D
    classDef component fill:#E8F4FF,stroke:#2A78C5,stroke-width:1px,color:#06233D
    classDef frontend fill:#E6FFFA,stroke:#1F8A7A,stroke-width:1px,color:#063B35
    classDef datastore fill:#EFEFEF,stroke:#6B6B6B,stroke-width:1px,color:#1C1C1C
    classDef folder fill:#FFF4CC,stroke:#A8871F,stroke-width:1px,color:#2B2305
    classDef external fill:#F3E8FF,stroke:#6D28D9,stroke-width:1px,color:#1F1147
    classDef meta fill:#F8FAFC,stroke:#94A3B8,stroke-dasharray: 4 3,color:#0F172A
```
