# josephmn/msv-maven-student architecture

> Architecture diagram of the GitHub repository josephmn/msv-maven-student, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/josephmn/msv-maven-student
- Repository: https://github.com/josephmn/msv-maven-student

## Overview

##### Project type and purpose
- This is a standalone backend REST API built with Java 17, Spring Boot WebFlux, R2DBC (reactive MySQL), and Vault.
- It exposes endpoints to manage Student and Teacher records (CRUD-lite for registration and retrieval).

##### High-level architecture pattern
- The codebase follows a layered (“hexagonal/onion”) architecture:
- presentation (controllers)
- application (use-case interfaces)
- domain (entities + business-logic implementations)
- infrastructure/adapters (DB adapters, mappers, configuration)

##### Key components (to include
A. External Actors & Services
- Client (e.g., Postman, Browser)
- Vault (secret management)
- MySQL database (R2DBC driver)

B. API Gateway layer (optional, for future)

C. Presentation Layer
- StudentController
- TeacherController

D. Application Layer (Ports)
- StudentUseCase (interface)
- TeacherUseCase (interface)

E. Domain Layer (Core business logic)
- StudentUseCaseImpl
- TeacherUseCaseImpl
- Entities: StudentEntity, TeacherEntity

F. Domain Ports (Repository Interfaces)
- StudentRepositoryReactive
- TeacherRepositoryReactive

G. Infrastructure Layer (Adapters)
- R2DBC MySQL Adapter (provided by Spring Data R2DBC)
- MapStruct mappers: StudentMapper, TeacherMapper
- Configuration: JacksonConfig, ConstantsConfig
- Exception handling: GlobalExceptionHandler + ErrorResponse

##### Interactions & data flow
1. Client → HTTP(S) request → Controller
2. Controller → invoke UseCase interface
3. UseCaseImpl (business logic) → validate/transform data → call Repository interface
4. Repository interface → Spring Data R2DBC → MySQL
5. Response bubbles back up: DB → Repository → UseCaseImpl → Controller → Client
6. At startup, application → Vault client reads DB credentials → JacksonConfig/Properties

##### Architectural patterns & design principles
- Hexagonal (Ports & Adapters): use‐case interfaces decouple business logic from frameworks.
- Reactive programming (Spring WebFlux + R2DBC).
- Separation of concerns: Controllers vs. UseCases vs. Domain vs. Infrastructure.
- Exception translation layer for consistent error responses.
- Externalized configuration & secret management via Vault.

##### Technologies & frameworks callouts
- Java 17
- Spring Boot 3.x (WebFlux, Data R2DBC)
- MySQL (R2DBC driver)
- Vault (HashiCorp Vault client)
- MapStruct (DTO↔Entity mapping)
- Lombok (boilerplate reduction)
- OpenAPI spec (openapi.yaml)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    subgraph "External Services"  
        direction TB
        Client["Client (Postman/Browser)"]:::external
        Vault["Vault"]:::external
        MySQL["MySQL (R2DBC)"]:::external
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"  
        direction TB
        JacksonConfig["JacksonConfig"]:::infrastructure
        ConstantsConfig["ConstantsConfig"]:::infrastructure
        GlobalExceptionHandler["GlobalExceptionHandler"]:::infrastructure
        ErrorResponse["ErrorResponse"]:::infrastructure
        subgraph "Exception Types"
            direction TB
            NotFoundException["NotFoundException"]:::infrastructure
            StudentAlreadyExistsException["StudentAlreadyExistsException"]:::infrastructure
            ValidationException["ValidationException"]:::infrastructure
        end
        StudentMapper["StudentMapper"]:::infrastructure
        TeacherMapper["TeacherMapper"]:::infrastructure
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        StudentEntity["StudentEntity"]:::domain
        TeacherEntity["TeacherEntity"]:::domain
        StudentUseCaseImpl["StudentUseCaseImpl"]:::domain
        TeacherUseCaseImpl["TeacherUseCaseImpl"]:::domain
        StudentRepositoryReactive["StudentRepositoryReactive"]:::domain
        TeacherRepositoryReactive["TeacherRepositoryReactive"]:::domain
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        StudentUseCase["StudentUseCase (interface)"]:::application
        TeacherUseCase["TeacherUseCase (interface)"]:::application
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        StudentController["StudentController"]:::presentation
        TeacherController["TeacherController"]:::presentation
    end

    %% Startup & Config
    Application["Application (entry point)"]:::infrastructure
    OpenAPI["openapi.yaml"]:::infrastructure
    Bootstrap["bootstrap.yml"]:::infrastructure

    %% Flows
    Client -->|"HTTP GET/POST /api/v1/students"| StudentController
    Client -->|"HTTP GET/POST /api/v1/teachers"| TeacherController
    StudentController -->|"calls"| StudentUseCase
    TeacherController -->|"calls"| TeacherUseCase
    StudentUseCase -->|"delegates to"| StudentUseCaseImpl
    TeacherUseCase -->|"delegates to"| TeacherUseCaseImpl
    StudentUseCaseImpl -->|"uses"| StudentRepositoryReactive
    TeacherUseCaseImpl -->|"uses"| TeacherRepositoryReactive
    StudentRepositoryReactive -->|"R2DBC"| MySQL
    TeacherRepositoryReactive -->|"R2DBC"| MySQL

    Application -.->|"reads secrets"| Vault
    Application -.->|"loads config"| Bootstrap
    Application -.->|"loads API spec"| OpenAPI
    Vault -.->|"provides secrets to"| JacksonConfig
    Vault -.->|"provides secrets to"| ConstantsConfig

    %% Click Events
    click StudentController "https://github.com/josephmn/msv-maven-student/blob/main/src/main/java/com/maven/student/presentation/StudentController.java"
    click TeacherController "https://github.com/josephmn/msv-maven-student/blob/main/src/main/java/com/maven/student/presentation/TeacherController.java"
    click StudentUseCase "https://github.com/josephmn/msv-maven-student/blob/main/src/main/java/com/maven/student/application/usecases/StudentUseCase.java"
    click TeacherUseCase "https://github.com/josephmn/msv-maven-student/blob/main/src/main/java/com/maven/student/application/usecases/TeacherUseCase.java"
    click StudentUseCaseImpl "https://github.com/josephmn/msv-maven-student/blob/main/src/main/java/com/maven/student/domain/services/StudentUseCaseImpl.java"
    click TeacherUseCaseImpl "https://github.com/josephmn/msv-maven-student/blob/main/src/main/java/com/maven/student/domain/services/TeacherUseCaseImpl.java"
    click StudentEntity "https://github.com/josephmn/msv-maven-student/blob/main/src/main/java/com/maven/student/domain/model/StudentEntity.java"
    click TeacherEntity "https://github.com/josephmn/msv-maven-student/blob/main/src/main/java/com/maven/student/domain/model/TeacherEntity.java"
    click StudentRepositoryReactive "https://github.com/josephmn/msv-maven-student/blob/main/src/main/java/com/maven/student/domain/repository/StudentRepositoryReactive.java"
    click TeacherRepositoryReactive "https://github.com/josephmn/msv-maven-student/blob/main/src/main/java/com/maven/student/domain/repository/TeacherRepositoryReactive.java"
    click StudentMapper "https://github.com/josephmn/msv-maven-student/blob/main/src/main/java/com/maven/student/infrastructure/util/StudentMapper.java"
    click TeacherMapper "https://github.com/josephmn/msv-maven-student/blob/main/src/main/java/com/maven/student/infrastructure/util/TeacherMapper.java"
    click JacksonConfig "https://github.com/josephmn/msv-maven-student/blob/main/src/main/java/com/maven/student/infrastructure/config/JacksonConfig.java"
    click ConstantsConfig "https://github.com/josephmn/msv-maven-student/blob/main/src/main/java/com/maven/student/infrastructure/util/ConstantsConfig.java"
    click GlobalExceptionHandler "https://github.com/josephmn/msv-maven-student/blob/main/src/main/java/com/maven/student/infrastructure/exception/GlobalExceptionHandler.java"
    click ErrorResponse "https://github.com/josephmn/msv-maven-student/blob/main/src/main/java/com/maven/student/infrastructure/exception/ErrorResponse.java"
    click Application "https://github.com/josephmn/msv-maven-student/blob/main/src/main/java/com/maven/student/Application.java"
    click OpenAPI "https://github.com/josephmn/msv-maven-student/blob/main/src/main/resources/openapi.yaml"
    click Bootstrap "https://github.com/josephmn/msv-maven-student/blob/main/src/main/resources/bootstrap.yml"

    %% Styles
    classDef presentation fill:#AEDFF7,stroke:#036B99,color:#000
    classDef application fill:#FFD59E,stroke:#B36B00,color:#000
    classDef domain fill:#C3E6CB,stroke:#2E7D32,color:#000
    classDef infrastructure fill:#E0E0E0,stroke:#616161,color:#000
    classDef external fill:#D1C4E9,stroke:#4527A0,color:#000
```
