# vuongnhattin/kotkit-spring-boot architecture

> Architecture diagram of the GitHub repository vuongnhattin/kotkit-spring-boot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vuongnhattin/kotkit-spring-boot
- Repository: https://github.com/vuongnhattin/kotkit-spring-boot

## Overview

##### Project type and purpose
- This is a monolithic Spring Boot REST API (“Kotkit”) providing user authentication, video management, comments, friendships, likes, notifications, and file storage.
- It’s intended to serve a web/mobile frontend via JSON over HTTP, with Swagger UI for API testing.

##### File structure
- src/main/java/com/example/kotkit:
- config: Spring Security (JWT), OpenAPI/Swagger, MinIO, ModelMapper, application properties
- controller: REST controllers (AuthController, VideoController, etc.)
- service: business-logic layer (AuthService, VideoService, MinioService, PermissionService, etc.)
- repository: Spring Data JPA interfaces for persistence
- entity: JPA entities and enums
- dto: input/output payload models
- exception: custom exceptions and global handler
- src/main/resources:
- application.yaml: runtime configuration
- db/migration: Flyway SQL migrations for schema initialization and seed data
- docker-compose.yml + init.sql: spins up the database and MinIO storage.

##### README insights
- Run “docker compose up -d” to start dependent services (PostgreSQL/MySQL + MinIO).
- Swagger UI available at http://localhost:8080/swagger-ui/index.html for testing endpoints.

##### Main components
a. Client layer
- Web or mobile clients + Swagger UI
b. API layer
- Spring Security filter chain (JwtAuthFilter)
- REST controllers (AuthController, UserController, VideoController, etc.)
c. Service layer
- Business services: AuthService, VideoService, CommentService, FriendshipService, NotificationService, PermissionService, MinioService, JwtService
d. Persistence layer
- Spring Data JPA repositories (UserRepository, VideoRepository, etc.)
- Relational database (PostgreSQL/MySQL) with Flyway-managed schema
e. External storage
- MinIO object storage for video/avatar files
f. Infrastructure/orchestration
- Docker Compose orchestrator starting DB + MinIO
- Application running on embedded Tomcat via Spring Boot

##### Relationships and interactions
- Client → HTTP Request → SecurityConfig → JwtAuthFilter → Controller
- Controller → delegates to Service → Service performs business logic → Repository → Database
- VideoService & MinioService → upload/download files → MinIO
- Flyway migrations run at startup to prepare the database schema
- ModelMapperConfig used within services to map between entities and DTOs
- GlobalExceptionHandler intercepts errors and returns ApiResponse wrappers

##### Architectural patterns and design principles
- Layered (Controller → Service → Repository)
- Dependency injection via Spring
- Separation of concerns: security, config, controllers, services, persistence
- Transactional boundaries at service methods
- JWT-based stateless authentication
- Externalized configuration (application.yaml, .env)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        WebClient["Web/Mobile Clients"]:::external
        SwaggerUI["Swagger UI"]:::external
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        SecurityConfig["SecurityConfig"]:::app
        JwtAuthFilter["JwtAuthFilter"]:::app
        subgraph "Controllers"
            direction TB
            AuthController["AuthController"]:::app
            UserController["UserController"]:::app
            VideoController["VideoController"]:::app
            CommentController["CommentController"]:::app
            FriendController["FriendController"]:::app
            NotificationController["NotificationController"]:::app
        end
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        AuthService["AuthService"]:::app
        UserService["UserService"]:::app
        VideoService["VideoService"]:::app
        CommentService["CommentService"]:::app
        FriendshipService["FriendshipService"]:::app
        PermissionService["PermissionService"]:::app
        JwtService["JwtService"]:::app
        MinioService["MinioService"]:::app
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        subgraph "Repositories"
            direction TB
            UserRepo["UserRepository"]:::app
            VideoRepo["VideoRepository"]:::app
            CommentRepo["CommentRepository"]:::app
            FriendshipRepo["FriendshipRepository"]:::app
            LikeRepo["LikeRepository"]:::app
            SavedVideoRepo["SavedVideoRepository"]:::app
        end
        Database["Relational Database\n(PostgreSQL/MySQL)"]:::datastore
        Flyway["Flyway Migrations"]:::app
    end

    %% Object Storage
    subgraph "Object Storage"
        direction TB
        MinIO["MinIO Object Storage"]:::datastore
    end

    %% Infrastructure
    subgraph "Infrastructure & Orchestration"
        direction TB
        DockerCompose["Docker Compose"]:::infra
        KotkitApp["KotkitApplication\n(Spring Boot)"]:::app
        ApplicationConfig["ApplicationConfig"]:::app
        ModelMapperConfig["ModelMapperConfig"]:::app
    end

    %% Connections
    WebClient -->|"HTTP/JSON"| JwtAuthFilter
    SwaggerUI -->|"HTTP/JSON"| JwtAuthFilter
    SecurityConfig --> JwtAuthFilter
    JwtAuthFilter --> Controllers

    AuthController --> AuthService
    UserController --> UserService
    VideoController --> VideoService
    CommentController --> CommentService
    FriendController --> FriendshipService
    NotificationController --> PermissionService

    AuthService --> UserRepo
    UserService --> UserRepo
    VideoService --> VideoRepo
    CommentService --> CommentRepo
    FriendshipService --> FriendshipRepo
    PermissionService --> LikeRepo
    PermissionService --> SavedVideoRepo
    JwtService --> AuthService

    VideoService --> MinioService
    MinioService --> MinIO

    UserRepo --> Database
    VideoRepo --> Database
    CommentRepo --> Database
    FriendshipRepo --> Database
    LikeRepo --> Database
    SavedVideoRepo --> Database
    Flyway --> Database

    DockerCompose --> Database
    DockerCompose --> MinIO
    DockerCompose --> KotkitApp

    KotkitApp --> ApplicationConfig
    KotkitApp --> ModelMapperConfig
    KotkitApp --> Flyway

    %% Click Events
    click SwaggerUI "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/config/OpenApiConfig.java"
    click JwtAuthFilter "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/config/JwtAuthFilter.java"
    click SecurityConfig "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/config/SecurityConfig.java"
    click ApplicationConfig "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/config/ApplicationConfig.java"
    click ModelMapperConfig "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/config/ModelMapperConfig.java"
    click MinioService "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/service/MinioService.java"
    click AuthController "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/controller/AuthController.java"
    click UserController "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/controller/UserController.java"
    click VideoController "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/controller/VideoController.java"
    click CommentController "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/controller/CommentController.java"
    click FriendController "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/controller/FriendController.java"
    click NotificationController "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/controller/NotificationController.java"
    click AuthService "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/service/AuthService.java"
    click UserService "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/service/UserService.java"
    click VideoService "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/service/VideoService.java"
    click CommentService "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/service/CommentService.java"
    click FriendshipService "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/service/FriendshipService.java"
    click PermissionService "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/service/PermissionService.java"
    click JwtService "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/service/JwtService.java"
    click UserRepo "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/repository/UserRepository.java"
    click VideoRepo "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/repository/VideoRepository.java"
    click CommentRepo "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/repository/CommentRepository.java"
    click FriendshipRepo "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/repository/FriendshipRepository.java"
    click LikeRepo "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/repository/LikeRepository.java"
    click SavedVideoRepo "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/java/com/example/kotkit/repository/SavedVideoRepository.java"
    click DockerCompose "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/docker-compose.yml"
    click Flyway "https://github.com/vuongnhattin/kotkit-spring-boot/blob/main/src/main/resources/db/migration/V1__init.sql"

    %% Styles
    classDef external fill:#D0E6FF,stroke:#3399FF,color:#003366
    classDef app fill:#E6FFE6,stroke:#33CC33,color:#006600
    classDef datastore fill:#FFE6CC,stroke:#FF9933,color:#663300
    classDef infra fill:#F2F2F2,stroke:#999999,color:#333333
```
