# xiscocambil/generator-core architecture

> Architecture diagram of the GitHub repository xiscocambil/generator-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xiscocambil/generator-core
- Repository: https://github.com/xiscocambil/generator-core

## Overview

##### Identificar el tipo de proyecto y su propósito
- A partir de la estructura y el README vemos que este repositorio actúa como “contenedor” de varios submódulos:
- authorization-server
- core
- front
- generator
- No hay un único ejecutable, sino que son varios servicios/componentes orquestados juntos. Por tanto se trata de un sistema modular de tipo full-stack/microservicios:
- Un front-end (interfaz de usuario)
- Un servidor de autorización (auth-service)
- Un módulo “core” con la lógica de negocio y orquestación
- Un motor “generator” que produce salidas (archivos, reportes, código, etc.)

##### Analizar la estructura de archivos
- .gitmodules confirma que cada carpeta (authorization-server, core, front, generator) es un submódulo Git independiente.
- No aparecen carpetas adicionales de infraestructura (por ejemplo “infra”, “deploy”), pero podemos inferir la necesidad de bases de datos o colas de mensajes en función de cada módulo.
- La carpeta front será típicamente una SPA (React/Angular/Vue).
- El authorization-server gestiona autenticación y tokens (OAuth2/OpenID).
- El core expone APIs REST/GraphQL para la aplicación.
- El generator es un componente de procesamiento por lotes o microservicio asíncrono.

##### Extraer insights clave del README
- El README explica cómo actualizar submódulos, pero no detalla la arquitectura.
- Dado el propósito de “generator-core”, el foco está en mantener versiones alineadas de cada submódulo.
- La ausencia de diagramas obliga a inferir el flujo de datos entre componentes.

##### Creación del diagrama de arquitectura
a. Componentes principales:
1. Front-end (navegador del usuario): carpeta front
2. API Gateway / Core Service: carpeta core
3. Authorization Server (OAuth2/OpenID): carpeta authorization-server
4. Generator Service (batch/cola): carpeta generator
5. Base de datos(s): p. ej. user-db (para auth), domain-db (para core), task-queue (para generator)
6. Clientes externos / CLI (opcional)

b. Relaciones e interacciones:
- El usuario interactúa con el Front.
- El Front envía peticiones API (HTTP/GraphQL) al Core Service.
- El Core Service valida el token contra el Authorization Server (JWT/OAuth introspection).
- Una vez autorizado, el Core escribe o lee datos de Domain-DB y/o encola tareas en Task-Queue.
- El Generator Service consume Task-Queue, procesa y almacena resultados en Storage o los regresa al Core.
- El Core puede exponer endpoints para consultar el estado/resultados generados.

c. Patrones y principios arquitectónicos:
- Microservicios desacoplados (cada submódulo es un servicio independiente).
- Separación de responsabilidades (UI vs. autenticación vs. lógica vs. generación).
- Comunicación síncrona (HTTP entre Front↔Core↔Auth) y asíncrona (colas entre Core↔Generator).
- Infraestructura de persistencia distribuida (bases de datos y colas).

d. Tecnologías y frameworks (hipotéticas, confirmar en cada submódulo):
- Front: React / Vue / Angular
- Core: Node.js (Express/Koa) o Spring Boot
- Auth: Keycloak / OAuth2 Server
- Generator: Python / Java batch / Node worker
- Mensajería: RabbitMQ / Kafka
- Persistencia: PostgreSQL / MongoDB

##### Elementos gráficos recomendados
- Componentes: cajas/rectángulos etiquetados con nombre y tecnología.
- Flechas direccionales:
- Lineal para REST/GraphQL (Front → Core → Auth)
- De ida/vuelta para validación de token (Core ↔ Auth)
- Unidireccional para colas (Core → Task-Queue → Generator).
- Código de colores o formas:
- UI (azul), Servicios (verde), Infra (gris), Mensajería (naranja).
- Íconos de base de datos, colas, navegador.

##### Consejos finales
- Sé exhaustivo: incluye cada submódulo, base de datos y cola.
- Etiqueta claramente puertos, protocolos y formatos de mensaje (JSON, JWT).
- Añade notas o leyenda para aclarar patrones (p. ej. “autorización OAuth2”).
- Revisa cada submódulo y agrega sus dependencias externas (storage S3, SMTP, Redis).

Con esta guía podrás elaborar un diagrama que refleje fielmente la arquitectura multipartes de “generator-core” y sirva de referencia para desarrolladores y ops.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        User["User<br>(Browser)"]:::ui
        Front["Front-end<br>(React/Vue)"]:::ui
    end

    %% Services Layer
    subgraph "Services"
        direction TB
        Auth["Authorization Server<br>(OAuth2/OpenID)"]:::service
        Core["Core Service<br>(API Gateway<br>Node.js/Spring)"]:::service
        Generator["Generator Service<br>(Batch Processor)"]:::service
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        direction TB
        UserDB["User DB<br>(PostgreSQL)"]:::db
        DomainDB["Domain DB<br>(PostgreSQL)"]:::db
        TaskQueue["Task Queue<br>(RabbitMQ/Kafka)"]:::queue
        Storage["Storage<br>(S3/Filesystem)"]:::db
    end

    %% Configuration Files
    subgraph "Configuration"
        direction TB
        GitModules[".gitmodules"]:::config
        Readme["README.md"]:::config
    end

    %% Connections
    User -->|"interacts with"| Front
    Front -->|"HTTP/GraphQL (3000→8080)"| Core
    Core -->|"token validation (JWT)"| Auth
    Auth -->|"token introspection"| Core
    Core -->|"read/write"| DomainDB
    Core -->|"enqueue task"| TaskQueue
    TaskQueue -->|"consume tasks"| Generator
    Generator -->|"store results"| Storage
    Core -->|"fetch results"| Storage

    %% Click Events
    click Front "https://github.com/xiscocambil/generator-core/tree/main/front/"
    click Core "https://github.com/xiscocambil/generator-core/tree/main/core/"
    click Auth "https://github.com/xiscocambil/generator-core/tree/main/authorization-server/"
    click Generator "https://github.com/xiscocambil/generator-core/tree/main/generator/"
    click GitModules "https://github.com/xiscocambil/generator-core/blob/main/.gitmodules"
    click Readme "https://github.com/xiscocambil/generator-core/blob/main/README.md"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef service fill:#DFFFE0,stroke:#22863a,color:#22863a;
    classDef db fill:#F0F0F0,stroke:#6a737d,color:#6a737d,shape:cylinder;
    classDef queue fill:#FFEDD5,stroke:#d15704,color:#d15704,shape:cylinder;
    classDef config fill:#FFF5B1,stroke:#735C0F,color:#735C0F;
```
