# arunadhithyagowthaman/springboot-rest-crud-learning architecture

> Architecture diagram of the GitHub repository arunadhithyagowthaman/springboot-rest-crud-learning, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arunadhithyagowthaman/springboot-rest-crud-learning
- Repository: https://github.com/arunadhithyagowthaman/springboot-rest-crud-learning

## Overview

##### Project type and purpose (from README + minimal tree)
This is a **Spring Boot REST API** learning project focused on:
- **RESTful CRUD endpoints**
- **Layered architecture**: Controller → Service → Repository
- **Spring Data JPA** persistence
- **Database**: H2 (dev) and/or MySQL
- **Global exception handling** via `@ControllerAdvice`
- **Custom runtime exceptions**
- **Validation logic** explicitly in the **service layer**
- Manual testing via **Postman** (i.e., an API client)

##### Spring Boot Application (single deployable)
- **Controllers** (REST layer)
- **Services** (business logic + validation)
- **Repositories** (data access abstraction via Spring Data JPA)
- **Global Exception Handler** (`@ControllerAdvice`)
- (Optional but typical) **DTO mapping / response models**
##### Database
- H2 (in-memory or file) for local/dev
- MySQL for external persistence

##### Key cross-cutting concerns to make explicit
- **Dependency Injection** (constructor injection)
- **Exception flow** (custom runtime exceptions → controller advice → error response)
- **Validation in Service layer** (call out that validation is not only annotations at controller boundary)

Purpose: show external actors and the deployed application + DB.

**Nodes**
- Postman / API Consumer
- Spring Boot REST API (single container)
- H2 or MySQL DB

- Client → API: HTTP requests (GET/POST/PUT/DELETE)
- API → DB: JDBC/JPA persistence operations

Purpose: show internal layering and dependencies.

- `Controller` layer (REST endpoints)
- `Service` layer (business rules + validation)
- `Repository` layer (Spring Data JPA interfaces)
- `Entity` model (JPA entities)
- `GlobalExceptionHandler` (`@ControllerAdvice`)
- `CustomExceptions` (domain-specific runtime exceptions)

**Dependency direction (important)**
- Controllers depend on Services
- Services depend on Repositories
- Repositories depend on JPA/EntityManager (implicit) and map Entities
- ExceptionHandler depends on Exceptions (and is invoked by Spring MVC on throw)

- Controller → Service: “DTO → domain call” / “invoke use-case”
- Service → Repository: “CRUD + queries”
- Service → (throws) CustomException → ControllerAdvice: “mapped to error response”
- Repository → DB: “JPA/Hibernate SQL”

Purpose: make exception handling and validation concrete.

**Happy path sequence**
##### Controller returns HTTP response (JSON)

**Failure path sequence**
##### Error response returned (status code + error body)

- **Client → Controller**: HTTP (JSON)
- **Controller → Service**: method calls (use-case invocation)
- **Service → Repository**: data access calls
- **Repository → DB**: persistence
- **Service → Custom Exceptions**: throws
- **Spring MVC runtime → ControllerAdvice**: exception interception
- **ControllerAdvice → Client**: consistent error payload + HTTP status

That **constructor injection** implies:
- Controller has Service as a constructor dependency
- Service has Repository as a constructor dependency

##### What “very detailed” means for this project (without overthinking)
- REST Controllers
- Service layer (validation lives here)
- Repository layer (Spring Data JPA)
- JPA Entities
- Exception handling:
- Custom exceptions
- Global handler (`@ControllerAdvice`)
- Configuration (optional but common): “DB config: H2/MySQL” (even if not shown in tree)

- Left: Postman
- Center: Spring Boot app split into Controller/Service/Repository + ControllerAdvice
- Right: DB (H2/MySQL)
- Two flows: “Happy path” and “Error path”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% System Context / Container
    %% =========================
    Client["API Client (Postman / HTTP Consumer)"]:::external

    subgraph "Spring Boot REST API (single deployable)"
        direction TB

        subgraph "REST Layer"
            direction TB
            C1["XController\n(REST endpoints: GET/POST/PUT/DELETE)\nJSON in/out"]:::controller
        end

        subgraph "Service Layer"
            direction TB
            S1["XService / XServiceImpl\n(Business logic + Validation)\nConstructor injection"]:::service
            V1["Validation Logic\n(explicit in service layer)"]:::serviceAux
        end

        subgraph "Data Access Layer"
            direction TB
            R1["XRepository\n(Spring Data JPA interfaces)\nCRUD + queries"]:::repository
            E1["XEntity\n(JPA Entities / Domain Model)"]:::entity
            JPA["JPA / Hibernate\n(EntityManager, ORM)"]:::platform
        end

        subgraph "Exception Handling (Cross-cutting)"
            direction TB
            EX1["Custom Runtime Exceptions\n(XNotFoundException, XValidationException, ...)"]:::exception
            EH1["GlobalExceptionHandler\n(@ControllerAdvice)\nMaps exceptions -> HTTP error response"]:::handler
        end

        CFG1["Configuration\n(DB config: H2/MySQL)"]:::config
    end

    DB1[("Database\nH2 (dev) / MySQL (external)")]:::database

    %% =========================
    %% Happy-path Request Flow
    %% =========================
    Client -->|"HTTP_JSON_request"| C1
    C1 -->|"invoke_use-case (DTO->domain)"| S1
    S1 -->|"validate_input/business_rules"| V1
    V1 -->|"continue"| S1
    S1 -->|"CRUD+queries"| R1
    R1 -->|"maps"| E1
    R1 -->|"uses"| JPA
    JPA -->|"SQL_over_JDBC"| DB1
    S1 -->|"return_result"| C1
    C1 -->|"HTTP_JSON_response"| Client

    %% =========================
    %% Error/Exception Flow
    %% =========================
    S1 -.->|"throws_CustomRuntimeException"| EX1
    EX1 -.->|"handled_by"| EH1
    C1 -.->|"exception_intercepted_by_Spring_MVC"| EH1
    EH1 -.->|"error_payload + HTTP_status"| Client

    %% =========================
    %% Dependency Injection (explicit)
    %% =========================
    C1 -.->|"constructor_injection"| S1
    S1 -.->|"constructor_injection"| R1

    %% =========================
    %% Click Events (from component_mapping)
    %% =========================
    click CFG1 "https://github.com/arunadhithyagowthaman/springboot-rest-crud-learning/blob/main/README.md"
    click C1 "https://github.com/arunadhithyagowthaman/springboot-rest-crud-learning/blob/main/README.md"
    click S1 "https://github.com/arunadhithyagowthaman/springboot-rest-crud-learning/blob/main/README.md"
    click R1 "https://github.com/arunadhithyagowthaman/springboot-rest-crud-learning/blob/main/README.md"
    click EH1 "https://github.com/arunadhithyagowthaman/springboot-rest-crud-learning/blob/main/README.md"
    click EX1 "https://github.com/arunadhithyagowthaman/springboot-rest-crud-learning/blob/main/README.md"
    click DB1 "https://github.com/arunadhithyagowthaman/springboot-rest-crud-learning/blob/main/README.md"

    %% =========================
    %% Styles
    %% =========================
    classDef external fill:#0b3556,stroke:#06243a,color:#ffffff,stroke-width:1.5px
    classDef controller fill:#1f77b4,stroke:#0f4f7a,color:#ffffff,stroke-width:1.5px
    classDef service fill:#2ca02c,stroke:#1d6f1d,color:#ffffff,stroke-width:1.5px
    classDef serviceAux fill:#34b233,stroke:#1d6f1d,color:#ffffff,stroke-width:1.2px
    classDef repository fill:#9467bd,stroke:#5b3a7a,color:#ffffff,stroke-width:1.5px
    classDef entity fill:#bcbd22,stroke:#7a7b15,color:#1a1a1a,stroke-width:1.5px
    classDef platform fill:#7f7f7f,stroke:#4f4f4f,color:#ffffff,stroke-width:1.2px
    classDef database fill:#ff7f0e,stroke:#a65208,color:#ffffff,stroke-width:1.8px
    classDef handler fill:#d62728,stroke:#8a1616,color:#ffffff,stroke-width:1.5px
    classDef exception fill:#ff4d4d,stroke:#8a1616,color:#ffffff,stroke-width:1.2px
    classDef config fill:#17becf,stroke:#0a6a73,color:#ffffff,stroke-width:1.2px
```
