# geocoderdev/siasis-api01-dev architecture

> Architecture diagram of the GitHub repository geocoderdev/siasis-api01-dev, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/geocoderdev/siasis-api01-dev
- Repository: https://github.com/geocoderdev/siasis-api01-dev

## Overview

##### Project type and purpose
- This is a backend REST-style API (“API01-SIASIS”) written in Node.js/TypeScript.
- It serves attendance, user management and related endpoints for multiple SIASIS roles (auxiliar, directivo, profesor, responsable, etc.).
- It runs on Vercel/Serverless or a Node.js host, uses Prisma + raw SQL for PostgreSQL, Redis for caching or session/OTP data, and integrates with GitHub EMCS01 and Google Drive for file backups.

##### File structure
Top-level directories:
- prisma – database schema + migrations (PostgreSQL via Prisma).
- core – “domain” folder containing:
– databases/config (Prisma, Redis clients)
– connectors/postgres.ts (DB connection)
– queries/RDP02 (raw SQL queries organized by domain)
– external (adapters for GitHub EMCS01, Google Drive).
- src – application code:
– app.ts (Express or similar HTTP server setup)
– routes/api (route modules per resource)
– middlewares (auth by role, SQL-injection prevention, param checks)
– lib/helpers (business logic: JWT, encryption, validation, OTP email, file uploads, error handlers)
– constants & interfaces (shared types, enums, environment configs).
- .github/workflows – CI/CD pipelines for development, certification, production.

##### Architecture insights from README & structure
- Layered/hexagonal architecture separating HTTP layer (routes + middlewares), business logic (lib/helpers), data access (core/databases), and external integrations (core/external).
- Uses Prisma ORM alongside raw SQL for complex queries.
- JWT-based authentication per role with cookies.
- Redis for caching or short-lived data (OTP codes).
- External adapters follow an adapter pattern under core/external.

a. Main components:
- Clients (Web/Mobile)
- API Gateway / Load Balancer (Vercel or Nginx)
- API Server (Node.js/Express)
– HTTP Layer: Routes & Middlewares
– Service Layer: lib/helpers (JWT, encryption, email, validators)
– Domain/Data Layer: core/databases (Prisma client, Redis client, raw SQL queries)
- Data Stores: PostgreSQL, Redis
- External Services:
– GitHub EMCS01 API
– Google Drive API
- CI/CD: GitHub Actions
- Deployment: Vercel (or container host)
b. Relationships & interactions:
1. Client → Load Balancer → API Server
2. API Server: request passes through Middlewares → Route Handler → Business Logic → Data Connectors → PostgreSQL/Redis or External Adapters → back up the chain to client.
3. Background jobs or hooks may call Google Drive adapter for file backup and GitHub EMCS01 adapter for external data.
c. Architectural patterns/design principles:
– Layered architecture with clear separation of concerns
– Repository/Connector pattern for data access
– Adapter pattern for external services
– DRY and modular helpers for cross-cutting concerns (auth, validation, error handling)
d. Key technologies/frameworks:
– Node.js + Express (or similar) for HTTP server
– TypeScript for strong typing
– Prisma ORM + raw SQL for PostgreSQL
– Redis client for caching/OTP
– JWT for authentication
– GitHub Actions for CI/CD
– Vercel (serverless) or container for deployment

- HTTP/API Layer (blue)
- Business Logic (green)
- Data Access (orange)
- External Services (gray)
- Infrastructure/CI-CD (purple)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients and Gateway
    subgraph "Clients & Gateway"
        Client["Web/Mobile Clients"]:::external
        Gateway["Load Balancer / API Gateway"]:::external
    end

    Client -->|Requests| Gateway

    %% API Server Layer
    subgraph "API Server (Node.js/Express)"    
        direction TB

        %% HTTP/API Layer
        subgraph "HTTP Layer"
            direction TB
            App["HTTP Server Entry Point\n(src/app.ts)"]:::http
            Routes["Express Routes\n(src/routes/router.ts\nand src/routes/api/*)"]:::http
            Middlewares["Middlewares\n(src/middlewares/*)"]:::http
        end

        %% Business Logic Layer
        subgraph "Business Logic / Services"
            direction TB
            Helpers["Helpers & Services\n(src/lib/helpers/**)"]:::biz
        end

        %% Data Access Layer
        subgraph "Data Access & Persistence"
            direction TB
            Connectors["DB Connectors\n(core/databases/connectors/postgres.ts\n& RedisClient)"]:::data
            Queries["Raw SQL Queries\n(core/databases/queries/RDP02/**)"]:::data
            Prisma["Prisma ORM\n(prisma/schema.prisma\n& migrations)"]:::data
        end

        %% External Adapters
        subgraph "External Adapters"
            direction TB
            GitHubAdapter["GitHub EMCS01 Adapter\n(core/external/github/EMCS01/consultarConEMCS01.ts)"]:::external
            GoogleDrive["Google Drive Adapter\n(core/external/google/drive/**)"]:::external
        end

        %% Constants & Interfaces
        Constants["Constants & Config\n(src/constants/**)"]:::data
        Interfaces["TypeScript Interfaces\n(src/interfaces/shared/**)"]:::data
    end

    Gateway -->|Proxies to| App
    App -->|mounts| Routes
    Routes -->|uses| Middlewares
    Middlewares -->|calls| Helpers
    Helpers -->|executes| Connectors
    Helpers -->|executes| Queries
    Helpers -->|executes| Prisma
    Helpers -->|uses| Constants
    Helpers -->|uses| Interfaces
    Helpers -->|invokes| GitHubAdapter
    Helpers -->|invokes| GoogleDrive

    %% Datastores
    subgraph "Data Stores"
        Postgres["PostgreSQL"]:::data
        Redis["Redis Cache"]:::data
    end

    Connectors -->|SQL/ORM| Postgres
    Queries -->|raw SQL| Postgres
    Prisma -->|ORM| Postgres
    Connectors -->|cache/OTP| Redis
    Helpers -->|cache/OTP| Redis

    %% CI/CD & Deployment
    subgraph "CI/CD & Deployment"
        direction TB
        Actions["GitHub Actions\n(.github/workflows/*.yml)"]:::infra
        Vercel["Vercel / Node Host"]:::infra
    end

    Actions -->|deploy| Vercel
    Vercel -->|hosts| Gateway

    %% Click Events
    click App "https://github.com/geocoderdev/siasis-api01-dev/blob/master/src/app.ts"
    click Routes "https://github.com/geocoderdev/siasis-api01-dev/blob/master/src/routes/router.ts"
    click Middlewares "https://github.com/geocoderdev/siasis-api01-dev/blob/master/src/middlewares/checkAuthentication.ts"
    click Middlewares "https://github.com/geocoderdev/siasis-api01-dev/blob/master/src/middlewares/sqlInjectionPrevention.ts"
    click Middlewares "https://github.com/geocoderdev/siasis-api01-dev/blob/master/src/middlewares/verifyGenericUserForAPI01.ts"
    click Middlewares "https://github.com/geocoderdev/siasis-api01-dev/blob/master/src/middlewares/wereObligatoryQueryParamsReceived.ts"
    click Helpers "https://github.com/geocoderdev/siasis-api01-dev/tree/master/src/lib/helpers/comprobations"
    click Helpers "https://github.com/geocoderdev/siasis-api01-dev/blob/master/src/lib/helpers/email/enviarCorreoOTP.ts"
    click Helpers "https://github.com/geocoderdev/siasis-api01-dev/tree/master/src/lib/helpers/encriptations"
    click Helpers "https://github.com/geocoderdev/siasis-api01-dev/tree/master/src/lib/helpers/functions/jwt"
    click Helpers "https://github.com/geocoderdev/siasis-api01-dev/blob/master/src/lib/helpers/functions/subirFotoPerfil.ts"
    click Helpers "https://github.com/geocoderdev/siasis-api01-dev/tree/master/src/lib/helpers/handlers"
    click Helpers "https://github.com/geocoderdev/siasis-api01-dev/tree/master/src/lib/helpers/instances"
    click Helpers "https://github.com/geocoderdev/siasis-api01-dev/blob/master/src/lib/helpers/security/generarCodigoOTP.ts"
    click Helpers "https://github.com/geocoderdev/siasis-api01-dev/blob/master/src/lib/helpers/serializeCookie.ts"
    click Helpers "https://github.com/geocoderdev/siasis-api01-dev/tree/master/src/lib/helpers/validators"
    click Helpers "https://github.com/geocoderdev/siasis-api01-dev/blob/master/src/lib/helpers/verificators/verificarBloqueoRol.ts"
    click Connectors "https://github.com/geocoderdev/siasis-api01-dev/blob/master/core/databases/connectors/postgres.ts"
    click Connectors "https://github.com/geocoderdev/siasis-api01-dev/blob/master/core/databases/config/Redis/RedisClient.ts"
    click Queries "https://github.com/geocoderdev/siasis-api01-dev/tree/master/core/databases/queries/RDP02"
    click Prisma "https://github.com/geocoderdev/siasis-api01-dev/blob/master/prisma/schema.prisma"
    click Prisma "https://github.com/geocoderdev/siasis-api01-dev/tree/master/prisma/migrations"
    click GitHubAdapter "https://github.com/geocoderdev/siasis-api01-dev/blob/master/core/external/github/EMCS01/consultarConEMCS01.ts"
    click GoogleDrive "https://github.com/geocoderdev/siasis-api01-dev/blob/master/core/external/google/drive/getDriveClient.ts"
    click GoogleDrive "https://github.com/geocoderdev/siasis-api01-dev/blob/master/core/external/google/drive/uploadFileToDrive.ts"
    click GoogleDrive "https://github.com/geocoderdev/siasis-api01-dev/blob/master/core/external/google/drive/deleteFileFromDrive.ts"
    click GoogleDrive "https://github.com/geocoderdev/siasis-api01-dev/blob/master/core/external/google/drive/findOrCreateFolder.ts"
    click Constants "https://github.com/geocoderdev/siasis-api01-dev/tree/master/src/constants"
    click Interfaces "https://github.com/geocoderdev/siasis-api01-dev/tree/master/src/interfaces/shared"
    click Actions "https://github.com/geocoderdev/siasis-api01-dev/blob/master/.github/workflows/haciaDesarrollo.yml"
    click Actions "https://github.com/geocoderdev/siasis-api01-dev/blob/master/.github/workflows/haciaCertificacion.yml"
    click Actions "https://github.com/geocoderdev/siasis-api01-dev/blob/master/.github/workflows/haciaProduccionIE20935.yml"
    click Vercel "https://github.com/geocoderdev/siasis-api01-dev/blob/master/vercel.json"

    %% Styles
    classDef http fill:#D0E7FF,stroke:#333,stroke-width:1px
    classDef biz fill:#DFFFD0,stroke:#333,stroke-width:1px
    classDef data fill:#FFE7C0,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef infra fill:#E7D0FF,stroke:#333,stroke-width:1px
```
