# karimalisahili/gema_backend architecture

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

- Interactive diagram: https://gitdiagram.com/karimalisahili/gema_backend
- Repository: https://github.com/karimalisahili/gema_backend

## Overview

##### Project type and purpose
- This is a Node.js backend API written in TypeScript, using Express for HTTP routing, Drizzle ORM for database access, and PostgreSQL as the data store.
- The README confirms it exposes REST endpoints for managing users, technical locations, workgroups, technicians, and their relationships.

##### File structure
- Top‐level “src” folder holds all TS source code:
- src/index.ts – application entry point, creates Express app and verifies DB connection
- src/db.ts + drizzle.config.ts – configure and export Drizzle ORM instance pointing to PostgreSQL (DATABASE_URL)
- src/routes/index.ts – central router that mounts sub‐routers
- src/controllers/… – one folder per domain (auth, gruposDeTrabajo, tecnico, trabajaEnGrupo, ubicacionesTecnicas) each with controller, routes, service
- src/middleware/auth.middleware.ts – JWT or session‐based auth guard for protected endpoints
- src/tables/*.ts – Drizzle ORM table definitions (usuarios, grupoDeTrabajo, incluyen, trabajaEnGrupo, ubicacionTecnica)
- src/utils/password.ts – password hashing/verification
- src/scripts/*.ts – stand‐alone scripts (initDB, prepushdb, postpushdb, exportToExcel) that run migrations, seed data or export data
- src/swagger.ts – Swagger/OpenAPI setup for auto‐generated API docs

##### Key architecture points from README
- On server start: check DB connection → if OK, start listening on configured port
- “npm run pushdb” uses Drizzle to synchronize schema
- “npm run initDB” seeds a master user

##### Main components
a. External Client(s) (e.g. Frontend, Postman, other services)
b. Express HTTP Server
c. Middleware layer (auth.middleware)
d. Routing layer (src/routes)
f. Service layer (business logic services called by controllers)
g. ORM layer (Drizzle instance from src/db.ts)
h. Database (PostgreSQL) with tables: usuarios, grupoDeTrabajo, incluyen, trabajaEnGrupo, ubicacionTecnica
i. Utility modules (password utils)
j. Scripts & tools (initDB, pushdb, exportToExcel, Swagger)

##### Relationships and data flow
- HTTP Server → Authentication Middleware → Router
- Router → Domain‐specific Controller (e.g. AuthController, GrupoDeTrabajoController, etc.)
- Controller → Service (e.g. AuthService, GrupoDeTrabajoService)
- Service → Drizzle ORM → PostgreSQL

##### Architectural patterns & principles
- Layered architecture (presentation → controller → service → data)
- Separation of concerns: controllers handle HTTP/response, services handle business logic, ORM handles persistence
- Configuration via environment variables (DATABASE_URL in .env)
- Type safety end‐to‐end: TypeScript + Drizzle types + explicit request/response types in controllers
- DB schema migrations with Drizzle and init scripts

## Diagram (Mermaid)

```mermaid
flowchart TB
    Client["External Client(s)"]:::runtime
    Server["Express HTTP Server\n(src/index.ts)"]:::runtime
    Middleware["Auth Middleware\n(src/middleware/auth.middleware.ts)"]:::runtime
    Router["Root Router\n(src/routes/index.ts)"]:::runtime

    subgraph "Routes"
        direction TB
        AuthR["Auth Routes\n(src/controllers/auth/auth.routes.ts)"]:::runtime
        GDT_R["GrupoDeTrabajo Routes\n(src/controllers/gruposDeTrabajo/gruposDeTrabajo.routes.ts)"]:::runtime
        Tec_R["Tecnico Routes\n(src/controllers/tecnico/tecnico.routes.ts)"]:::runtime
        TEG_R["TrabajaEnGrupo Routes\n(src/controllers/trabajaEnGrupo/trabajaEnGrupo.routes.ts)"]:::runtime
        UT_R["UbicacionesTecnicas Routes\n(src/controllers/ubicacionesTecnicas/ubicacionesTecnicas.routes.ts)"]:::runtime
    end

    subgraph "Controllers"
        direction TB
        AuthCtrl["Auth Controller\n(src/controllers/auth/auth.controller.ts)"]:::runtime
        GDT_Ctrl["GrupoDeTrabajo Controller\n(src/controllers/gruposDeTrabajo/gruposDeTrabajo.controller.ts)"]:::runtime
        Tec_Ctrl["Tecnico Controller\n(src/controllers/tecnico/tecnico.controller.ts)"]:::runtime
        TEG_Ctrl["TrabajaEnGrupo Controller\n(src/controllers/trabajaEnGrupo/trabajaEnGrupo.controller.ts)"]:::runtime
        UT_Ctrl["UbicacionesTecnicas Controller\n(src/controllers/ubicacionesTecnicas/ubicacionesTecnicas.controller.ts)"]:::runtime
    end

    subgraph "Services"
        direction TB
        AuthSvc["Auth Service\n(src/controllers/auth/auth.service.ts)"]:::runtime
        GDT_Svc["GrupoDeTrabajo Service\n(src/controllers/gruposDeTrabajo/gruposDeTrabajo.service.ts)"]:::runtime
        Tec_Svc["Tecnico Service\n(src/controllers/tecnico/tecnico.service.ts)"]:::runtime
        TEG_Svc["TrabajaEnGrupo Service\n(src/controllers/trabajaEnGrupo/trabajaEnGrupo.service.ts)"]:::runtime
        UT_Svc["UbicacionesTecnicas Service\n(src/controllers/ubicacionesTecnicas/ubicacionesTecnicas.service.ts)"]:::runtime
    end

    ORM_Config["Drizzle Config\n(drizzle.config.ts)"]:::runtime
    ORM["Drizzle ORM Instance\n(src/db.ts)"]:::runtime
    DB[(PostgreSQL)]:::datastore

    Utils["Password Utils\n(src/utils/password.ts)"]:::runtime
    Swagger["Swagger/OpenAPI\n(src/swagger.ts)"]:::tool

    subgraph "Scripts & Tooling"
        direction TB
        initDB["initDB Script\n(src/scripts/initDB.ts)"]:::tool
        prepush["prepushdb Script\n(src/scripts/prepushdb.ts)"]:::tool
        postpush["postpushdb Script\n(src/scripts/postpushdb.ts)"]:::tool
        exportExcel["exportToExcel Script\n(src/scripts/exportToExcel.ts)"]:::tool
    end

    Client -->|"HTTP Request"| Server
    Server -->|"uses"| Middleware
    Middleware -->|"forwards"| Router

    Router -->|"mounts"| AuthR
    Router -->|"mounts"| GDT_R
    Router -->|"mounts"| Tec_R
    Router -->|"mounts"| TEG_R
    Router -->|"mounts"| UT_R

    AuthR -->|"routes to"| AuthCtrl
    GDT_R -->|"routes to"| GDT_Ctrl
    Tec_R -->|"routes to"| Tec_Ctrl
    TEG_R -->|"routes to"| TEG_Ctrl
    UT_R -->|"routes to"| UT_Ctrl

    AuthCtrl -->|"calls"| AuthSvc
    GDT_Ctrl -->|"calls"| GDT_Svc
    Tec_Ctrl -->|"calls"| Tec_Svc
    TEG_Ctrl -->|"calls"| TEG_Svc
    UT_Ctrl -->|"calls"| UT_Svc

    AuthSvc -->|"executes queries via"| ORM
    GDT_Svc -->|"executes queries via"| ORM
    Tec_Svc -->|"executes queries via"| ORM
    TEG_Svc -->|"executes queries via"| ORM
    UT_Svc -->|"executes queries via"| ORM

    ORM_Config -->|"used by"| ORM
    ORM -->|"connects to"| DB

    Utils -->|"utilized by"| AuthSvc

    Server -->|"serves docs via"| Swagger

    initDB --> ORM
    prepush --> ORM
    postpush --> ORM
    exportExcel --> ORM

    initDB --> DB
    prepush --> DB
    postpush --> DB
    exportExcel --> DB

    classDef runtime fill:#a0c4ff,stroke:#0366d6,color:#000
    classDef datastore fill:#b7e4c7,stroke:#40916c,color:#000
    classDef tool fill:#ffd6a5,stroke:#e85d04,color:#000

    click Server "https://github.com/karimalisahili/gema_backend/blob/main/src/index.ts"
    click ORM_Config "https://github.com/karimalisahili/gema_backend/blob/main/drizzle.config.ts"
    click ORM "https://github.com/karimalisahili/gema_backend/blob/main/src/db.ts"
    click Router "https://github.com/karimalisahili/gema_backend/blob/main/src/routes/index.ts"
    click Middleware "https://github.com/karimalisahili/gema_backend/blob/main/src/middleware/auth.middleware.ts"
    click AuthCtrl "https://github.com/karimalisahili/gema_backend/blob/main/src/controllers/auth/auth.controller.ts"
    click AuthR "https://github.com/karimalisahili/gema_backend/blob/main/src/controllers/auth/auth.routes.ts"
    click AuthSvc "https://github.com/karimalisahili/gema_backend/blob/main/src/controllers/auth/auth.service.ts"
    click GDT_Ctrl "https://github.com/karimalisahili/gema_backend/blob/main/src/controllers/gruposDeTrabajo/gruposDeTrabajo.controller.ts"
    click GDT_R "https://github.com/karimalisahili/gema_backend/blob/main/src/controllers/gruposDeTrabajo/gruposDeTrabajo.routes.ts"
    click GDT_Svc "https://github.com/karimalisahili/gema_backend/blob/main/src/controllers/gruposDeTrabajo/gruposDeTrabajo.service.ts"
    click Tec_Ctrl "https://github.com/karimalisahili/gema_backend/blob/main/src/controllers/tecnico/tecnico.controller.ts"
    click Tec_R "https://github.com/karimalisahili/gema_backend/blob/main/src/controllers/tecnico/tecnico.routes.ts"
    click Tec_Svc "https://github.com/karimalisahili/gema_backend/blob/main/src/controllers/tecnico/tecnico.service.ts"
    click TEG_Ctrl "https://github.com/karimalisahili/gema_backend/blob/main/src/controllers/trabajaEnGrupo/trabajaEnGrupo.controller.ts"
    click TEG_R "https://github.com/karimalisahili/gema_backend/blob/main/src/controllers/trabajaEnGrupo/trabajaEnGrupo.routes.ts"
    click TEG_Svc "https://github.com/karimalisahili/gema_backend/blob/main/src/controllers/trabajaEnGrupo/trabajaEnGrupo.service.ts"
    click UT_Ctrl "https://github.com/karimalisahili/gema_backend/blob/main/src/controllers/ubicacionesTecnicas/ubicacionesTecnicas.controller.ts"
    click UT_R "https://github.com/karimalisahili/gema_backend/blob/main/src/controllers/ubicacionesTecnicas/ubicacionesTecnicas.routes.ts"
    click UT_Svc "https://github.com/karimalisahili/gema_backend/blob/main/src/controllers/ubicacionesTecnicas/ubicacionesTecnicas.service.ts"
    click Utils "https://github.com/karimalisahili/gema_backend/blob/main/src/utils/password.ts"
    click Swagger "https://github.com/karimalisahili/gema_backend/blob/main/src/swagger.ts"
    click initDB "https://github.com/karimalisahili/gema_backend/blob/main/src/scripts/initDB.ts"
    click prepush "https://github.com/karimalisahili/gema_backend/blob/main/src/scripts/prepushdb.ts"
    click postpush "https://github.com/karimalisahili/gema_backend/blob/main/src/scripts/postpushdb.ts"
    click exportExcel "https://github.com/karimalisahili/gema_backend/blob/main/src/scripts/exportToExcel.ts"
```
