# xsergiodm/metaudla architecture

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

- Interactive diagram: https://gitdiagram.com/xsergiodm/metaudla
- Repository: https://github.com/xsergiodm/metaudla

## Overview

##### Project Type and Purpose
- Metaudla is a Spring Boot–based backend service (REST API) for an educational metaverse.
- It exposes HTTP endpoints for user and “isla” (virtual world) management, social interactions (comments, likes, favorites, ratings), and statistics.

##### High-Level Architecture
- Layered MVC style:
- Presentation/API Layer (Controllers)
- Business Logic Layer (Services + Mappers)
- Data Access Layer (Repositories + Entities)
- Infrastructure (Database, Security, Configuration)

##### Main Components
a. Clients
- Web front-end or mobile app
- API consumers (e.g., analytics tools, admin dashboards)
b. API Gateway / Load Balancer (optional)
c. Controllers (/api/usuarios, /api/islas)
d. DTOs & Mappers
- DTO packages under `src/main/java/.../DTOs`
- Mapstruct or manual mappers convert between DTOs and Entities
e. Services
- `IGestionUsuario` / `GestionUsuarioImpl`
- `IGestionIsla` / `GestionIslaImpl`
f. Repositories (Spring Data JPA interfaces)
- `UsuarioRepository`, `IslaRepository`, etc.
g. Entities (Domain Models)
- `Usuario`, `Isla`, `Comentario`, `Favorito`, `MeGusta`, `Puntuacion`, etc.
h. Database
- MySQL instance
i. Security Layer
- Spring Security config (`SecurityConfig`)
- Authentication (Session or JWT)
j. Configuration
- `application.properties`
- ServiceConfig, banner

##### Relationships & Data Flows
- Client → HTTP Request → Controller
- Controller invokes Service method
- Service applies business rules, uses Mappers to translate DTO↔Entity
- Service calls Repository methods
- Repository executes SQL on MySQL DB
- Data flows back through layers: Entity → Mapper → DTO → Controller → Client
- SecurityConfig intercepts incoming requests (authentication/authorization)
- Optional external services (e.g., email, file storage) can be shown as side-services

##### Architectural Patterns & Principles
- Layered pattern (separation of concerns)
- Dependency Injection (Spring context)
- Repository pattern (Spring Data JPA)
- DTO pattern (to decouple internal models from API)
- Configuration as code (Java & properties files)
- Liskov substitution for service interfaces (IGestionUsuario/IgestionIsla)

##### Technologies & Frameworks
- Java 21, Spring Boot 3.5.6
- Spring Web MVC (REST controllers)
- Spring Data JPA (repositories)
- Spring Security (authentication & authorization)
- Spring Validation
- MySQL (RDBMS)
- Lombok (boilerplate reduction)
- Maven (build tool)

##### Essential Details to Capture
- All REST endpoints grouped under their Controller.
- Service interfaces vs. implementations.
- DTOs and mappers as the translation boundary.
- Repository interfaces mapping to tables in MySQL.
- SecurityConfig intercepting requests before Controllers.
- application.properties settings (DB URL, credentials, JPA dialect).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Layer
    subgraph "External Clients"
        direction TB
        WebClient["Web Front-end / Mobile App"]:::external
        APIConsumer["API Consumers (Analytics, Admin)"]:::external
    end

    %% Optional Gateway
    APIGateway["API Gateway / Load Balancer"]:::external

    WebClient -->|HTTP Request| APIGateway
    APIConsumer -->|HTTP Request| APIGateway

    %% Infrastructure - Security
    subgraph "Cross-cutting Infrastructure"
        direction TB
        Security["SecurityConfig"]:::infra
        ConfigProps["application.properties"]:::infra
        Banner["banner.txt"]:::infra
    end

    APIGateway -->|filters| Security
    Security --> Controllers

    click Security "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/config/SecurityConfig.java"
    click ConfigProps "https://github.com/xsergiodm/metaudla/blob/main/src/main/resources/application.properties.example"
    click Banner "https://github.com/xsergiodm/metaudla/blob/main/src/main/resources/banner.txt"

    %% Presentation Layer
    subgraph "Presentation / API Layer" 
        direction TB
        Controllers["PruebaController"]:::api
        DTOs["DTOs"]:::api
    end

    Security --> Controllers
    Controllers -->|uses| DTOs

    click Controllers "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/controllers/PruebaController.java"

    %% DTOs & Mappers
    subgraph "DTOs & Mappers"
        direction TB
        subgraph "DTOs"
            direction TB
            IslaDtoC["IslaDtoCreate"]:::api
            IslaDtoR["IslaDtoResponse"]:::api
            UsuarioDtoC["UsuarioDtoCreate"]:::api
            UsuarioDtoR["UsuarioResponseDto"]:::api
        end
        subgraph "Mappers"
            direction TB
            IslaMapper["IslaMapper"]:::api
            UsuarioMapper["UsuarioMapper"]:::api
        end
    end

    DTOs --> IslaDtoC
    DTOs --> IslaDtoR
    DTOs --> UsuarioDtoC
    DTOs --> UsuarioDtoR
    DTOs --> IslaMapper
    DTOs --> UsuarioMapper

    click IslaDtoC "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/DTOs/isla/IslaDtoCreate.java"
    click IslaDtoR "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/DTOs/isla/IslaDtoResponse.java"
    click UsuarioDtoC "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/DTOs/usuario/UsuarioDtoCreate.java"
    click UsuarioDtoR "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/DTOs/usuario/UsuarioResponseDto.java"
    click IslaMapper "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/mappers/IslaMapper.java"
    click UsuarioMapper "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/mappers/UsuarioMapper.java"

    Controllers -->|"calls"| IslaDtoC
    Controllers -->|"calls"| UsuarioDtoC

    %% Business Logic Layer
    subgraph "Business Layer"
        direction TB
        subgraph "Service Interfaces"
            direction TB
            IGestionIsla["IGestionIsla"]:::business
            IGestionUsuario["IGestionUsuario"]:::business
        end
        subgraph "Service Implementations"
            direction TB
            GestionIsla["GestionIslaImpl"]:::business
            GestionUsuario["GestionUsuarioImpl"]:::business
        end
    end

    IslaMapper --> IGestionIsla
    UsuarioMapper --> IGestionUsuario
    IGestionIsla --> GestionIsla
    IGestionUsuario --> GestionUsuario

    click IGestionIsla "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/servicies/gestion_islas/IGestionIsla.java"
    click GestionIsla "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/servicies/gestion_islas/GestionIslaImpl.java"
    click IGestionUsuario "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/servicies/gestion_usuarios/IGestionUsuario.java"
    click GestionUsuario "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/servicies/gestion_usuarios/GestionUsuarioImpl.java"

    Controllers -->|"invokes"| GestionIsla
    Controllers -->|"invokes"| GestionUsuario
    GestionIsla -->|"uses"| IslaMapper
    GestionUsuario -->|"uses"| UsuarioMapper

    %% Data Access Layer
    subgraph "Data Access Layer"
        direction TB
        subgraph "Repositories"
            direction TB
            UsuarioRepo["UsuarioRepository"]:::data
            IslaRepo["IslaRepository"]:::data
            ComentarioRepo["ComentarioRepository"]:::data
            FavoritoRepo["FavoritoRepository"]:::data
            MeGustaRepo["MeGustaRepository"]:::data
            LikeComentarioRepo["LikeComentarioRepository"]:::data
            PuntuacionRepo["PuntuacionRepository"]:::data
            CategoriaRepo["CategoriaRepository"]:::data
        end
        subgraph "Entities"
            direction TB
            UsuarioEnt["Usuario"]:::data
            IslaEnt["Isla"]:::data
            ComentarioEnt["Comentario"]:::data
            FavoritoEnt["Favorito"]:::data
            MeGustaEnt["MeGusta"]:::data
            LikeComentarioEnt["LikeComentario"]:::data
            PuntuacionEnt["Puntuacion"]:::data
            CategoriaEnt["Categoria"]:::data
        end
    end

    GestionIsla -->|"calls"| IslaRepo
    GestionUsuario -->|"calls"| UsuarioRepo
    IslaRepo -->|"manages"| IslaEnt
    UsuarioRepo -->|"manages"| UsuarioEnt
    ComentarioRepo -->|"manages"| ComentarioEnt
    FavoritoRepo -->|"manages"| FavoritoEnt
    MeGustaRepo -->|"manages"| MeGustaEnt
    LikeComentarioRepo -->|"manages"| LikeComentarioEnt
    PuntuacionRepo -->|"manages"| PuntuacionEnt
    CategoriaRepo -->|"manages"| CategoriaEnt

    click UsuarioRepo "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/repositories/UsuarioRepository.java"
    click IslaRepo "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/repositories/IslaRepository.java"
    click ComentarioRepo "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/repositories/ComentarioRepository.java"
    click FavoritoRepo "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/repositories/FavoritoRepository.java"
    click MeGustaRepo "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/repositories/MeGustaRepository.java"
    click LikeComentarioRepo "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/repositories/LikeComentarioRepository.java"
    click PuntuacionRepo "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/repositories/PuntuacionRepository.java"
    click CategoriaRepo "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/repositories/CategoriaRepository.java"

    click UsuarioEnt "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/entities/Usuario.java"
    click IslaEnt "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/entities/Isla.java"
    click ComentarioEnt "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/entities/Comentario.java"
    click FavoritoEnt "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/entities/Favorito.java"
    click MeGustaEnt "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/entities/MeGusta.java"
    click LikeComentarioEnt "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/entities/LikeComentario.java"
    click PuntuacionEnt "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/entities/Puntuacion.java"
    click CategoriaEnt "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/entities/Categoria.java"

    %% Persistence
    MySQL["MySQL Database"]:::db
    UsuarioRepo -->|JPA SQL| MySQL
    IslaRepo -->|JPA SQL| MySQL
    ComentarioRepo -->|JPA SQL| MySQL
    FavoritoRepo -->|JPA SQL| MySQL
    MeGustaRepo -->|JPA SQL| MySQL
    LikeComentarioRepo -->|JPA SQL| MySQL
    PuntuacionRepo -->|JPA SQL| MySQL
    CategoriaRepo -->|JPA SQL| MySQL

    %% Application Entry
    MetaudlaApp["MetaudlaApplication"]:::infra
    MetaudlaApp --> Controllers

    click MetaudlaApp "https://github.com/xsergiodm/metaudla/blob/main/src/main/java/com/udlaverso/metaudla/MetaudlaApplication.java"

    %% Enums
    Enums["Enums (Rol, EstadoBasico, EstadoModeracion, TipoLike)"]:::infra
    click Enums "https://github.com/xsergiodm/metaudla/tree/main/src/main/java/com/udlaverso/metaudla/enums/"

    %% Build & Docs
    Pom["pom.xml"]:::infra
    README["README.md"]:::infra
    RunConfig[".run/UdlaVerso.run.xml"]:::infra
    click Pom "https://github.com/xsergiodm/metaudla/blob/main/pom.xml"
    click README "https://github.com/xsergiodm/metaudla/blob/main/README.md"
    click RunConfig "https://github.com/xsergiodm/metaudla/blob/main/.run/UdlaVerso.run.xml"

    %% Styles
    classDef external fill:#AEDFF7,stroke:#036; 
    classDef api fill:#B3D7FF,stroke:#036;
    classDef business fill:#C6F6C6,stroke:#070;
    classDef data fill:#FFD8A8,stroke:#E65;
    classDef infra fill:#E2E2E2,stroke:#888;
    classDef db fill:#BBBBBB,stroke:#666;
```
