# eduvirttul/eduvirt-backend architecture

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

- Interactive diagram: https://gitdiagram.com/eduvirttul/eduvirt-backend
- Repository: https://github.com/eduvirttul/eduvirt-backend

## Overview

Based on our analysis of the project’s complete file tree and the configuration details in the README, the project is a full-fledged Java Spring Boot backend application that primarily acts as a management and orchestration service for an oVirt-based virtualization environment. It is concerned with managing courses, reservations, clusters, teams, and a variety of resource groups. The project is also containerized (using Docker with docker-compose and Dockerfile) and integrates with several external systems, including a PostgreSQL database, oVirt Engine API, Keycloak for authentication, and an SMTP mail server.

##### Main Components
- Web/API Layer: Represent the REST controllers (e.g., AccessKeyController, ClusterController, CourseController, ReservationController, etc.) that expose endpoints for client interactions. Mark notes for authentication filters (like RefreshTokenFilter) and aspects that handle logging and exception resolution.
- Service Layer: Include the various service packages such as CourseService, ReservationService, VirtualMachineService, and also the oVirt integration services (OVirtClusterService, OVirtHostService, etc.). This layer encapsulates business logic and domain-specific operations.
- Persistence Layer: Highlight repositories (e.g., CourseRepository, ReservationRepository, UserRepository, etc.) combined with JPA entities and Liquibase-managed database schema (configuration/liquibase folder). Indicate the PostgreSQL database connection (via JDBC URL and credentials in environment variables).
- External Integrations:
- Mail Server: Illustrate connection details for sending emails using SMTP. Include configuration aspects (MAIL_HOST, MAIL_PORT, etc.).
- oVirt Engine API: Represent the integration with the oVirt Engine (ENGINE_URL, ENGINE_USERNAME, ENGINE_PASSWORD) where many service calls are routed.
- Keycloak: Show integration for SSO via Keycloak (KEYCLOAK_URL, KEYCLOAK_REALM, etc.).
- Cross-Cutting Concerns: Outline the aspects that intercept exceptions and log information (logging, exception aspects) and the use of JWT for security.
- Docker & Deployment: Add a containerization layer that includes Docker configuration (Dockerfile, docker/compose.yaml, db initialization scripts) to reflect the deployment environment.
- Configuration & Environment: Include the configuration settings read from environment variables (e.g., mail server, database credentials, and various external service endpoints).

##### Relationships and Data Flow
- That controllers delegate processing to the service layer, which in turn interacts with the persistence layer (repositories) to read/write data.
- References from the service layer to the cross-cutting concerns (aspects for logging/exception handling) to illustrate how these features are “woven” into the flow.
- The persistence layer should clearly connect to an external PostgreSQL database, as initialized with Liquibase scripts.

##### Architectural Patterns and Design Principles
- The project follows a layered (or n-tier) architecture with distinct responsibilities split between controllers, services, and repositories.
- Use of AOP (Aspect-Oriented Programming) is apparent (for logging and exception handling), which should be represented as an overlay or cross-cutting element applied across several layers.
- Integration patterns for external services, such as REST-based calls to oVirt and Keycloak, are key to the design.
- Containerization and CI/CD integration are emphasized via Docker and GitHub Actions (workflows under .github/workflows).

##### Relevant Technologies and Frameworks
- Java with Spring Boot is the core framework – show Spring’s role in REST API and dependency injection.
- Maven as the build tool (pom.xml, mvnw scripts).
- PostgreSQL as the database, with Liquibase for schema evolution.
- Docker for containerization.
- Integration with external services using SMTP (for emails), oVirt Engine API (for virtualization), and Keycloak (for authentication/SAML/OAuth flows).
- JWS & JWT mechanism for secure token management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["External Client"]:::external

    %% Web/API Layer
    subgraph "Web/API Layer"
        Controllers["REST Controllers"]:::api
        Filter["Refresh Token Filter"]:::filter
        Client -->|"HTTPRequest"| Controllers
        Controllers -->|"Uses"| Filter
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        Controllers -->|"Delegates"| Service["Service Layer"]:::service
        Service -->|"Calls"| OVirt["oVirt Integration Services"]:::service
        Service -->|"Triggers"| Executor["Executor & Scheduler"]:::executor
        Service -->|"Invokes"| MailConfig["Mail Configuration"]:::service
        Service -->|"Notifies"| MailNotification["Mail Notification Service"]:::service
        Service -->|"Authenticates"| KeycloakConfig["Keycloak Config"]:::service
        Service -->|"Weaves"| CrossCut["Cross Cutting Concerns"]:::service
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        Service -->|"Persists"| Repository["Repositories"]:::repository
        Repository -->|"Accesses"| DB["PostgreSQL Database"]:::database
        Repository -->|"Defines"| Liquibase["Liquibase Schema"]:::repository
    end

    %% External Systems
    subgraph "External Systems"
        OVirtEngine["oVirt Engine API"]:::external
        SMTP["SMTP Mail Server"]:::external
        KeycloakServer["Keycloak Server"]:::external
        Service ---|"Calls"| OVirtEngine
        Service ---|"Sends"| SMTP
        Service ---|"Verifies"| KeycloakServer
    end

    %% Configuration & Deployment
    subgraph "Configuration & Deployment"
        AppConfig["Application Configurations"]:::config
        Additional["Additional Configurations"]:::config
        DockerConfig["Docker & Deployment"]:::docker
        DBInit["DB Initialization Scripts"]:::docker
    end

    %% Cross Cutting Concerns Details
    subgraph "Cross Cutting Concerns"
        Logging["Logging Aspects"]:::service
        Exception["Exception Handling"]:::service
        JWT["JWT Utilities"]:::service
        CrossCut --> Logging
        CrossCut --> Exception
        CrossCut --> JWT
    end

    %% Click Events
    click Controllers "https://github.com/eduvirttul/eduvirt-backend/tree/develop/src/main/java/pl/lodz/p/it/eduvirt/controller"
    click Filter "https://github.com/eduvirttul/eduvirt-backend/blob/develop/src/main/java/pl/lodz/p/it/eduvirt/filter/RefreshTokenFilter.java"
    click Service "https://github.com/eduvirttul/eduvirt-backend/tree/develop/src/main/java/pl/lodz/p/it/eduvirt/service"
    click OVirt "https://github.com/eduvirttul/eduvirt-backend/tree/develop/src/main/java/pl/lodz/p/it/eduvirt/service/ovirt"
    click Repository "https://github.com/eduvirttul/eduvirt-backend/tree/develop/src/main/java/pl/lodz/p/it/eduvirt/repository"
    click Liquibase "https://github.com/eduvirttul/eduvirt-backend/tree/develop/src/main/resources/config/liquibase"
    click Executor "https://github.com/eduvirttul/eduvirt-backend/tree/develop/src/main/java/pl/lodz/p/it/eduvirt/executor/service"
    click MailConfig "https://github.com/eduvirttul/eduvirt-backend/blob/develop/src/main/java/pl/lodz/p/it/eduvirt/configuration/MailConfig.java"
    click MailNotification "https://github.com/eduvirttul/eduvirt-backend/blob/develop/src/main/java/pl/lodz/p/it/eduvirt/executor/service/MailNotificationService.java"
    click KeycloakConfig "https://github.com/eduvirttul/eduvirt-backend/blob/develop/src/main/java/pl/lodz/p/it/eduvirt/configuration/KeycloackConfig.java"
    click Logging "https://github.com/eduvirttul/eduvirt-backend/tree/develop/src/main/java/pl/lodz/p/it/eduvirt/aspect/logging"
    click Exception "https://github.com/eduvirttul/eduvirt-backend/tree/develop/src/main/java/pl/lodz/p/it/eduvirt/aspect/exception"
    click JWT "https://github.com/eduvirttul/eduvirt-backend/tree/develop/src/main/java/pl/lodz/p/it/eduvirt/util/jwt"
    click DockerConfig "https://github.com/eduvirttul/eduvirt-backend/tree/develop/Dockerfile"
    click DBInit "https://github.com/eduvirttul/eduvirt-backend/tree/develop/docker/db_init"
    click AppConfig "https://github.com/eduvirttul/eduvirt-backend/blob/develop/src/main/resources/application.yaml"
    click Additional "https://github.com/eduvirttul/eduvirt-backend/tree/develop/src/main/java/pl/lodz/p/it/eduvirt/configuration"

    %% Styling
    classDef external fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef api fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef filter fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef service fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef repository fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef executor fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef config fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef docker fill:#FFE4B5,stroke:#333,stroke-width:2px;
    classDef database fill:#AFEEEE,stroke:#333,stroke-width:2px;

    class Client external;
    class Controllers api;
    class Filter filter;
    class Service service;
    class OVirt service;
    class Repository repository;
    class Liquibase repository;
    class Executor executor;
    class MailConfig service;
    class MailNotification service;
    class KeycloakConfig service;
    class Logging service;
    class Exception service;
    class JWT service;
    class DB database;
    class AppConfig config;
    class Additional config;
    class DockerConfig docker;
    class DBInit docker;
    class OVirtEngine external;
    class SMTP external;
    class KeycloakServer external;
```
