# martinsjavacode/springboot-kotlin-clean-arch architecture

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

- Interactive diagram: https://gitdiagram.com/martinsjavacode/springboot-kotlin-clean-arch
- Repository: https://github.com/martinsjavacode/springboot-kotlin-clean-arch

## Overview

##### Project Type and Purpose
- The README clearly states that this project (“user-api”) is a CRUD system for users. It is built using Kotlin on the JVM (Java 11) and employs the Clean Architecture pattern.
- The project also includes integration components with GitHub (as seen in both the “amartins/kotlin” and “user/api” packages), indicating that it not only handles user CRUD operations but also integrates or fetches data from an external GitHub service.

##### File Structure
- Two main application entry points can be identified:
- br/com/amartins/kotlin/KotlinApplication.kt
- br/com/user/api/UserApiApplication.kt
- The “br/com/user/api” package is clearly dedicated to the user API, containing configuration, controllers, converters, domain models, exceptions, integrations, repositories, and use cases. This neatly reflects Clean Architecture’s emphasis on separation of concerns.
- The core directories represent the following layers in Clean Architecture:
- Controllers (under “controller” and “controller/resource”) manage incoming HTTP requests (e.g., UserController, GithubController).
- Use Cases (under “usecase” and “usecase/impl”) encapsulate business logic like Save, Update, Delete operations and GitHub integration use cases.
- Domain models (under “domain”) define the key business entities such as User and Github.
- Integration layers (under “integration” and “integration/impl”) handle communication with external APIs (GitHub).
- Repository layers (under “repository” and its converters/impl) manage persistence and conversions.
- Configuration packages (with ModelMapperConfig, SwaggerConfig, SpringFoxConfig, FeignClientConfig) are there for cross-cutting concerns and external configuration.

##### Components and Their Relationships
- Main Components:
- API Layer/Controllers: Expose endpoints for user operations (CRUD) and potentially GitHub lookups.
- Use Case Layer: Contains business logic that takes input from controllers and processes it using domain rules.
- Domain Layer: Contains the core business entities such as User and Github.
- Repository/Adapter Layer: Abstracts data persistence and provides implementations (and conversions) for storing/fetching Users.
- Integration Layer: Provides services to integrate with GitHub such as fetching user details externally.
- Configuration: Manages application settings, Swagger documentation, mapping strategies, and HTTP client configurations.
- Relationships:
- Controllers call Use Cases.
- Use Cases interact with Domain models.
- Use Cases communicate with both the Repository Layer (for persistence) and the Integration Layer (to fetch GitHub data).
- Converters are applied between API resources and domain entities in the API, integration, and repository layers.
- External Requests/Responses from GitHub are funneled through dedicated gateways and converter components before affecting the domain.

##### Architectural Patterns and Key Principles
- Each major functionality (Users, GitHub) is divided into its own bounded contexts, meaning you have distinct components for handling user data and external GitHub interactions.
- Use of Dependency Inversion is implied by how controllers and use cases depend on abstractions (interfaces) rather than on concrete classes (as seen with the gateways and converters).

## Diagram (Mermaid)

```mermaid
graph TD

    %% API / Controller Layer
    subgraph "API / Controller Layer"
        UC1["UserController"]:::controller
        GC1["GithubController"]:::controller
    end

    %% Use Case Layer
    subgraph "Use Case Layer"
        UUC["User Use Cases"]:::usecase
        FGHU["FindGitHubUseCase"]:::usecase
        FGHUI["FindGitHubUseCaseImpl"]:::usecase
    end

    %% Domain Layer
    subgraph "Domain Layer"
        UD["User"]:::domain
        GH["Github"]:::domain
    end

    %% Repository / Adapter Layer
    subgraph "Repository / Adapter Layer"
        UR["UserRepository"]:::repository
        URC["UserRepository Converter"]:::repository
        URI["UserRepository Impl"]:::repository
    end

    %% Integration Layer
    subgraph "Integration Layer"
        FGHI["FindUserGithub"]:::integration
        GHI["GithubGatewayImpl"]:::integration
        IC["Integration Converters"]:::integration
        GR["GithubResponse"]:::integration
    end

    %% Configuration Components
    subgraph "Configuration"
        UAC["UserAPI Config"]:::config
        KC["Kotlin Config"]:::config
    end

    %% External System
    ES["GitHub External Service"]:::external

    %% Connections between Layers
    %% API Controllers to Use Cases
    UC1 -->|"calls"| UUC
    GC1 -->|"calls"| FGHU

    %% Use Cases interacting with Domain
    UUC -->|"manages"| UD
    FGHU -->|"processes"| GH

    %% Use Cases calling Repository / Adapter layer
    UUC -->|"persists"| UR

    %% Use Cases calling Integration Layer
    FGHU -->|"fetches"| FGHI

    %% Internal Integration flow
    FGHI -->|"delegates"| GHI
    GHI -->|"parses"| IC
    IC -->|"returns"| GR
    GHI -->|"calls"| ES

    %% Configuration effects
    UAC ---|"configures"| UC1
    UAC ---|"configures"| UR
    KC ---|"configures"| GC1

    %% Use Case Implementation relation
    FGHU -->|"implementedBy"| FGHUI

    %% Repository internal relationship
    UR -->|"uses"| URC
    UR -->|"uses"| URI

    %% Use Cases and Domain link (bidirectional indication of business logic)
    UUC ---|"validates"| UD
    FGHU ---|"validates"| GH

    %% Click Events
    click UC1 "https://github.com/martinsjavacode/springboot-kotlin-clean-arch/blob/master/src/main/kotlin/br/com/user/api/controller/UserController.kt"
    click GC1 "https://github.com/martinsjavacode/springboot-kotlin-clean-arch/blob/master/src/main/kotlin/br/com/amartins/kotlin/controller/GithubController.kt"
    click UUC "https://github.com/martinsjavacode/springboot-kotlin-clean-arch/tree/master/src/main/kotlin/br/com/user/api/usecase"
    click FGHU "https://github.com/martinsjavacode/springboot-kotlin-clean-arch/blob/master/src/main/kotlin/br/com/user/api/usecase/FindGitHubUseCase.kt"
    click FGHUI "https://github.com/martinsjavacode/springboot-kotlin-clean-arch/blob/master/src/main/kotlin/br/com/user/api/usecase/impl/FindGitHubUseCaseImpl.kt"
    click UD "https://github.com/martinsjavacode/springboot-kotlin-clean-arch/blob/master/src/main/kotlin/br/com/user/api/domain/User.kt"
    click GH "https://github.com/martinsjavacode/springboot-kotlin-clean-arch/blob/master/src/main/kotlin/br/com/user/api/domain/Github.kt"
    click UR "https://github.com/martinsjavacode/springboot-kotlin-clean-arch/blob/master/src/main/kotlin/br/com/user/api/repository/UserRepository.kt"
    click URC "https://github.com/martinsjavacode/springboot-kotlin-clean-arch/tree/master/src/main/kotlin/br/com/user/api/repository/converter"
    click URI "https://github.com/martinsjavacode/springboot-kotlin-clean-arch/tree/master/src/main/kotlin/br/com/user/api/repository/impl"
    click FGHI "https://github.com/martinsjavacode/springboot-kotlin-clean-arch/blob/master/src/main/kotlin/br/com/user/api/integration/FindUserGithub.kt"
    click GHI "https://github.com/martinsjavacode/springboot-kotlin-clean-arch/blob/master/src/main/kotlin/br/com/user/api/integration/impl/GithubGatewayImpl.kt"
    click IC "https://github.com/martinsjavacode/springboot-kotlin-clean-arch/tree/master/src/main/kotlin/br/com/user/api/integration/converter"
    click GR "https://github.com/martinsjavacode/springboot-kotlin-clean-arch/blob/master/src/main/kotlin/br/com/user/api/integration/response/GithubResponse.kt"
    click UAC "https://github.com/martinsjavacode/springboot-kotlin-clean-arch/tree/master/src/main/kotlin/br/com/user/api/config"
    click KC "https://github.com/martinsjavacode/springboot-kotlin-clean-arch/tree/master/src/main/kotlin/br/com/amartins/kotlin/config"

    %% Styles
    classDef controller fill:#F7C6C7,stroke:#B0413E,stroke-width:2px;
    classDef usecase fill:#C3D7FF,stroke:#23529F,stroke-width:2px;
    classDef domain fill:#C8FACC,stroke:#2F7A2E,stroke-width:2px;
    classDef repository fill:#FFE8A6,stroke:#B37800,stroke-width:2px;
    classDef integration fill:#CAEDFF,stroke:#2E8BC0,stroke-width:2px;
    classDef config fill:#FFF3C4,stroke:#B38A00,stroke-width:2px;
    classDef external fill:#E0E0E0,stroke:#777777,stroke-width:2px,stroke-dasharray: 5 5;
```
