# josue-leon/davivienda architecture

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

- Interactive diagram: https://gitdiagram.com/josue-leon/davivienda
- Repository: https://github.com/josue-leon/davivienda

## Overview

##### Project Type and Purpose
- This is a full-stack, multi-container application for a “Billetera Virtual” (Digital Wallet).
- It consists of three cooperating services:
- cliente-app: a React/Vite web client
- servidor-client: a NestJS API Gateway/business-logic service
- servidor-database: a NestJS data/persistence service backed by MySQL via Prisma

##### File Structure
- Top-level:
- cliente-app/… — front-end React SPA
- servidor-client/… — NestJS service exposing business-logic endpoints
- servidor-database/… — NestJS service exposing raw data/persistence endpoints
- docker-compose.yml — orchestrates all three containers plus MySQL & phpMyAdmin
- Each NestJS service uses controllers, DTOs, entities, global error handling, guards, and services.
- The database layer adds modules, repositories, Prisma context/unit-of-work, and migrations/seed.

##### README Insights
- Ports:
- 3000: Servidor-database’s Swagger/OpenAPI UI
- 3001: Servidor-client’s Swagger/OpenAPI UI
- 5173: cliente-app web UI
- 33060: MySQL
- 8081: phpMyAdmin
- Stack: React 19, NestJS + Fastify, Prisma + MySQL, Docker Compose, OpenAPI Generator, Postman

##### Main Components and Interactions
a. Frontend (cliente-app)
- Serves UI pages (Home, ConsultarSaldo, Pagar, etc.)
- Calls servidor-client via VITE_API_BASE_URL + API key
b. API Gateway / Business Service (servidor-client)
- Exposes high-level endpoints (e.g., /clientes, /billetera, /pagar)
- Implements authentication guard (API-Key)
- Delegates persistence calls to servidor-database via HTTP (using generated OpenAPI client)
c. Data / Persistence Service (servidor-database)
- Exposes low-level CRUD endpoints directly interacting with MySQL via Prisma
- Implements repositories, unit-of-work, custom validators, global error filters
d. Database (MySQL)
- Stores cliente, transacción, sesiónCompra, saldo tables
- Accessed by Prisma through servidor-database
e. Supporting Tools
- phpMyAdmin for DB inspection
- Swagger/OpenAPI for API docs on both NestJS services
- Postman collections for manual testing

##### Architectural Patterns & Design Principles
- Layered Microservice Architecture: three independently deployable containers
- API-First Design: both NestJS services have OpenAPI/Swagger and generated API clients
- Dependency Injection & Inversion (NestJS modules, services, controllers)
- Repository + Unit-of-Work Pattern in the database layer
- Separation of Concerns: UI vs business logic vs data access

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Docker Compose" 
        direction TB
        clienteApp["cliente-app<br/>(React/Vite, port 5173)"]:::ui
        servidorClient["servidor-client<br/>(NestJS Fastify, port 3001)"]:::biz
        servidorDatabase["servidor-database<br/>(NestJS Fastify, port 3000)"]:::data
        mysql["MySQL<br/>(port 33060)"]:::ext
        phpMyAdmin["phpMyAdmin<br/>(port 8081)"]:::ext
    end

    clienteApp -->|"HTTP/REST<br/>to API Gateway<br/>port 3001<br/>API Key"| servidorClient
    servidorClient -->|"HTTP/REST<br/>to Data Service<br/>port 3000<br/>API Key"| servidorDatabase
    servidorDatabase -->|"Prisma ORM<br/>MySQL port 33060"| mysql
    mysql -->|"DB UI"| phpMyAdmin

    subgraph "cliente-app Directory Structure" 
        direction TB
        pages["src/pages"]:::ui
        apiWrappers["src/api"]:::ui
        openApiClientFE["api-client"]:::ui
        componentsFE["src/components"]:::ui
        contexts["src/contexts/NotificationContext.tsx"]:::ui
    end

    clienteApp --> pages
    clienteApp --> apiWrappers
    clienteApp --> openApiClientFE
    clienteApp --> componentsFE
    clienteApp --> contexts

    subgraph "servidor-client Directory Structure"
        direction TB
        controllersSC["src/controllers"]:::biz
        servicesSC["src/services"]:::biz
        guardSC["src/guards/api-key.guard.ts"]:::biz
        globalsSC["src/globals"]:::biz
        apiClientSC["api-db"]:::biz
        codegenSC["generate-api.sh<br/>openapitools.json"]:::biz
    end

    servidorClient --> controllersSC
    servidorClient --> servicesSC
    servidorClient --> guardSC
    servidorClient --> globalsSC
    servidorClient --> apiClientSC
    servidorClient --> codegenSC

    subgraph "servidor-database Directory Structure"
        direction TB
        controllersSD["src/controllers"]:::data
        servicesSD["src/services"]:::data
        reposSD["src/repositories"]:::data
        prismaContext["src/prisma"]:::data
        schemaSD["prisma/schema"]:::data
        seedSD["prisma/seed.ts"]:::data
    end

    servidorDatabase --> controllersSD
    servidorDatabase --> servicesSD
    servidorDatabase --> reposSD
    servidorDatabase --> prismaContext
    servidorDatabase --> schemaSD
    servidorDatabase --> seedSD

    %% Click Events
    click clienteApp "https://github.com/josue-leon/davivienda/tree/main/cliente-app/"
    click pages "https://github.com/josue-leon/davivienda/tree/main/cliente-app/src/pages/"
    click apiWrappers "https://github.com/josue-leon/davivienda/tree/main/cliente-app/src/api/"
    click openApiClientFE "https://github.com/josue-leon/davivienda/tree/main/cliente-app/api-client/"
    click componentsFE "https://github.com/josue-leon/davivienda/tree/main/cliente-app/src/components/"
    click contexts "https://github.com/josue-leon/davivienda/blob/main/cliente-app/src/contexts/NotificationContext.tsx"
    click servidorClient "https://github.com/josue-leon/davivienda/tree/main/servidor-client/"
    click controllersSC "https://github.com/josue-leon/davivienda/tree/main/servidor-client/src/controllers/"
    click servicesSC "https://github.com/josue-leon/davivienda/tree/main/servidor-client/src/services/"
    click guardSC "https://github.com/josue-leon/davivienda/blob/main/servidor-client/src/guards/api-key.guard.ts"
    click globalsSC "https://github.com/josue-leon/davivienda/tree/main/servidor-client/src/globals/"
    click apiClientSC "https://github.com/josue-leon/davivienda/tree/main/servidor-client/api-db/"
    click codegenSC "https://github.com/josue-leon/davivienda/blob/main/servidor-client/generate-api.sh"
    click servidorDatabase "https://github.com/josue-leon/davivienda/tree/main/servidor-database/"
    click controllersSD "https://github.com/josue-leon/davivienda/tree/main/servidor-database/src/controllers/"
    click servicesSD "https://github.com/josue-leon/davivienda/tree/main/servidor-database/src/services/"
    click reposSD "https://github.com/josue-leon/davivienda/tree/main/servidor-database/src/repositories/"
    click prismaContext "https://github.com/josue-leon/davivienda/tree/main/servidor-database/src/prisma/"
    click schemaSD "https://github.com/josue-leon/davivienda/tree/main/servidor-database/prisma/schema/"
    click seedSD "https://github.com/josue-leon/davivienda/blob/main/servidor-database/prisma/seed.ts"

    classDef ui fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef biz fill:#E0FFD0,stroke:#28A745,color:#28A745
    classDef data fill:#FFE6C7,stroke:#E36209,color:#E36209
    classDef ext fill:#F2F2F2,stroke:#6C757D,color:#6C757D
```
