# luisegui/dunktomic architecture

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

- Interactive diagram: https://gitdiagram.com/luisegui/dunktomic
- Repository: https://github.com/luisegui/dunktomic

## Overview

##### Project Type and Purpose
- Dunktomic is a full-stack sports reservation platform.
- Frontend: Vue 3 + Vite single-page app for user interaction.
- Backend: Spring Boot multi-module Java application implementing REST API, layered with Domain-Driven Design (DDD) / hexagonal principles.
- Infrastructure services: MySQL database, Keycloak for authentication, Docker Compose to orchestrate backend + DB + Keycloak.

##### File Structure
- Top‐level directories:
- frontend – Vue code, assets, components, pages, services (HTTP, API, local storage) and its Dockerfile.
- backend – Multi-module Maven project under backend/code:
– boot: Spring Boot launcher + configuration (CORS, security, logging, Keycloak client).
– api/rest: Controllers and DTOs exposing HTTP endpoints (AuthController, ClubsController, PlayersController).
– application: Use case implementations and application-level DTOs.
– domain: Core entities, value objects, repository interfaces, domain exceptions.
– infrastructure:
- database: JPA/Hibernate adapters & entities mapping to MySQL.
- repository: adapters mapping domain repositories to external data stores.
- keycloak-client: REST client against Keycloak’s OpenAPI.
- db/mysql/dev: Dockerfile, init scripts for MySQL.
- keycloak: Dockerfile, realm configuration, setup script.
- scripts: Python script + JSON data for populating clubs via API.
- docker-compose.yml: orchestrates backend (built via backend/deployment), db, Keycloak.

##### README
- Describes functional requirements (search/book courts, manage matches, chat, community).
- Non-functional stack: Spring, Vue, Docker, GitHub Actions.
- Deployment via Docker Compose (backend, DB, Keycloak) + separate npm dev server for frontend.

##### Detail
- Maven module as a sub-component in the backend block
- How DTOs flow from Controllers down to Use Cases and back
- Where exceptions are handled (RestExceptionHandler in API layer)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Side"
        direction TB
        Frontend["Frontend SPA (Vue 3 + Vite)"]:::frontend
    end

    %% Server Side
    subgraph "Server Side"
        direction TB

        subgraph "API Layer"
            direction TB
            Controllers["REST Controllers"]:::backend
            DTOs["DTOs"]:::backend
            ExceptionHandler["RestExceptionHandler"]:::backend
        end

        subgraph "Application Layer"
            direction TB
            UseCases["Use Case Implementations"]:::backend
            AppDTOs["Application DTOs"]:::backend
        end

        subgraph "Domain Layer"
            direction TB
            Entities["Entities"]:::backend
            ValueObjects["Value Objects"]:::backend
            RepoInterfaces["Repository Interfaces"]:::backend
        end

        subgraph "Infrastructure Layer"
            direction TB
            subgraph "Database Adapters"
                direction TB
                JPAAdapters["JPA Adapters"]:::backend
                JPAModels["JPA Entity Models"]:::backend
            end
            RepoAdapters["Repository Adapters"]:::backend
            KeycloakClient["Keycloak Client"]:::auth
        end

        subgraph "Boot Module"
            direction TB
            Boot["Spring Boot Launcher & Config"]:::backend
        end
    end

    %% External Services & Scripts
    MySQLDB["MySQL Database"]:::database
    KeycloakServ["Keycloak Auth Server"]:::auth
    DockerCompose["Docker Compose"]:::infra
    DataLoader["Data-Loader Script"]:::scripts
    CICD["GitHub Actions CI/CD"]:::ci

    %% Relationships
    Frontend -->|"HTTP/REST"| Controllers
    Controllers -->|"use cases"| UseCases
    UseCases -->|"domain logic"| Entities
    UseCases --> ValueObjects
    UseCases --> RepoInterfaces
    RepoInterfaces --> RepoAdapters
    RepoAdapters --> JPAAdapters
    JPAAdapters --> JPAModels
    JPAModels --> MySQLDB

    Controllers -->|"auth calls"| KeycloakServ
    KeycloakClient -->|"token validation"| KeycloakServ

    Boot --> Controllers
    Boot --> UseCases
    Boot --> KeycloakClient

    DockerCompose -.-> Boot
    DockerCompose -.-> MySQLDB
    DockerCompose -.-> KeycloakServ

    DataLoader -->|"preload via API"| Controllers
    CICD -->|"build & deploy"| DockerCompose

    %% Click Events
    click Frontend "https://github.com/luisegui/dunktomic/tree/main/frontend/code"
    click Controllers "https://github.com/luisegui/dunktomic/tree/main/backend/code/api/rest/src/main/java/es/ucm/luisegui/dunktomic/controllers"
    click DTOs "https://github.com/luisegui/dunktomic/tree/main/backend/code/api/rest/src/main/java/es/ucm/luisegui/dunktomic/dtos"
    click ExceptionHandler "https://github.com/luisegui/dunktomic/blob/main/backend/code/api/rest/src/main/java/es/ucm/luisegui/dunktomic/errors/RestExceptionHandler.java"
    click UseCases "https://github.com/luisegui/dunktomic/tree/main/backend/code/application/src/main/java/es/ucm/luisegui/dunktomic/application/usecases"
    click AppDTOs "https://github.com/luisegui/dunktomic/tree/main/backend/code/application/src/main/java/es/ucm/luisegui/dunktomic/application/dtos"
    click Entities "https://github.com/luisegui/dunktomic/tree/main/backend/code/domain/src/main/java/es/ucm/luisegui/dunktomic/domain/entities"
    click ValueObjects "https://github.com/luisegui/dunktomic/tree/main/backend/code/domain/src/main/java/es/ucm/luisegui/dunktomic/domain/valueobjects"
    click RepoInterfaces "https://github.com/luisegui/dunktomic/tree/main/backend/code/domain/src/main/java/es/ucm/luisegui/dunktomic/domain/repositories"
    click JPAAdapters "https://github.com/luisegui/dunktomic/tree/main/backend/code/infraestructure/database/src/main/java/es/ucm/luisegui/dunktomic/infrastructure/database/adapters"
    click JPAModels "https://github.com/luisegui/dunktomic/tree/main/backend/code/infraestructure/database/src/main/java/es/ucm/luisegui/dunktomic/infrastructure/database/models"
    click RepoAdapters "https://github.com/luisegui/dunktomic/tree/main/backend/code/infraestructure/repository/src/main/java/es/ucm/luisegui/dunktomic/infrastructure/repository"
    click KeycloakClient "https://github.com/luisegui/dunktomic/tree/main/backend/code/infraestructure/keycloak-client"
    click Boot "https://github.com/luisegui/dunktomic/tree/main/backend/code/boot/src/main/java/es/ucm/luisegui/dunktomic"
    click MySQLDB "https://github.com/luisegui/dunktomic/tree/main/db/mysql/dev"
    click KeycloakServ "https://github.com/luisegui/dunktomic/tree/main/keycloak"
    click DockerCompose "https://github.com/luisegui/dunktomic/blob/main/docker-compose.yml"
    click DataLoader "https://github.com/luisegui/dunktomic/blob/main/scripts/sports_center/python/load_clubs.py"
    click CICD "https://github.com/luisegui/dunktomic/blob/main/.github/workflows/bump.yml"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#339fff
    classDef backend fill:#ccffcc,stroke:#339f33
    classDef database fill:#ffd699,stroke:#ff9f00
    classDef auth fill:#e0ccff,stroke:#9f33ff
    classDef infra fill:#eeeeee,stroke:#666666
    classDef scripts fill:#dddddd,stroke:#666666
    classDef ci fill:#f0f0f0,stroke:#333333
```
