# dnguyenminh/chunk-upload architecture

> Architecture diagram of the GitHub repository dnguyenminh/chunk-upload, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dnguyenminh/chunk-upload
- Repository: https://github.com/dnguyenminh/chunk-upload

## Overview

##### Project type and purpose
- This is a Java-based, multi-module Gradle project implementing a resumable “chunked” file upload service.
- It consists of three modules:
- server: a Spring Boot REST API for initializing uploads, accepting chunks, tracking progress, and assembling files on disk.
- client: a standalone Java client library (and CLI wrappers) that invokes the server’s REST endpoints.
- model: a shared DTO module (InitRequest, InitResponse) used by both client and server.

##### File structure
- Root: settings.gradle, build.gradle (common Gradle configuration & dependency management via Spring Boot BOM).
- server/: Spring Boot application code (controllers, services, managers, configuration), resources (application.properties, logback.xml), an embedded H2 file (used for tests), scripts for running & user setup.
- client/: Java client code invoking upload/init, upload/chunk, status, delete operations; build scripts; a local H2 file for testing.
- model/: simple DTOs with no external dependencies.
- Shared scripts/workflows: GitHub Actions for build/release, Qodana for code quality.

##### README for additional insights
- Clarifies REST API endpoints (/api/upload/init, /chunk, /status, DELETE).
- Storage is filesystem-based (“in-progress” & “complete” directories), no external database in production.
- Logging with SLF4J + Logback.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Module" 
        direction TB
        CUC["ChunkedUploadClient"]:::client
        CLIUnix["Unix CLI Wrapper"]:::client
        CLIWin["Windows CLI Wrapper"]:::client
    end

    %% Model Layer
    subgraph "Model Module"
        direction TB
        InitReq["InitRequest"]:::model
        InitRes["InitResponse"]:::model
    end

    %% Server Layer
    subgraph "Server Module"
        direction TB
        App["UploadApplication"]:::server
        SecurityConfig["SecurityConfig"]:::server
        subgraph "API Layer"
            direction TB
            CUController["ChunkedUploadController"]:::server
            UserController["UserController"]:::server
        end
        subgraph "Business Layer"
            direction TB
            Service["ChunkedUploadService"]:::server
        end
        subgraph "Manager Layer"
            direction TB
            SessionManager["SessionManager"]:::server
            BitsetManager["BitsetManager"]:::server
        end
        subgraph "Configuration"
            direction TB
            Props["application.properties"]:::server
            Logback["logback.xml"]:::server
        end
    end

    %% Storage
    subgraph "Filesystem Storage"
        direction TB
        InProgress["In-Progress Directory"]:::storage
        Complete["Complete Directory"]:::storage
    end

    %% Test Harness
    subgraph "Test Harness"
        direction TB
        ServerRealIT["Real Integration Test"]:::test
        ServerUnitTest["Controller Unit Test"]:::test
        ClientIT["Client Integration Test"]:::test
    end

    %% Gradle & CI
    subgraph "Build & CI"
        direction TB
        RootBuild["build.gradle"]:::infra
        Settings["settings.gradle"]:::infra
        ClientBuild["client/build.gradle"]:::infra
        ModelBuild["model/build.gradle"]:::infra
        ServerBuild["server/build.gradle"]:::infra
        GHBuild[".github/workflows/build-and-release.yml"]:::infra
        Qodana[".github/workflows/qodana_code_quality.yml"]:::infra
    end

    %% Connections
    CLIUnix -->|wraps| CUC
    CLIWin -->|wraps| CUC
    CUC -->|uses| InitReq
    CUC -->|uses| InitRes
    CUC -->|"POST /api/upload/init"| CUController
    CUC -->|"POST /api/upload/chunk"| CUController
    CUC -->|"GET /api/upload/status"| CUController
    CUC -->|"DELETE /api/upload"| CUController

    CUController -->|"invokes"| Service
    Service -->|"startSession"| SessionManager
    Service -->|"writeChunk"| BitsetManager
    Service -->|"assembleFile"| Complete
    SessionManager -->|reads/writes header| InProgress
    BitsetManager -->|updates bitset| InProgress

    CUController -->|uses| InitReq
    CUController -->|returns| InitRes

    App -->|boots| CUController
    App -->|boots| UserController
    App -->|loads| SecurityConfig
    Props -->|configures| InProgress
    Props -->|configures| Complete
    Logback -->|logs to| storage

    ServerRealIT -->|tests| CUController
    ServerRealIT -->|uses FS| InProgress
    ServerUnitTest -->|tests| CUController
    ClientIT -->|tests| CUC

    RootBuild -->|includes modules| ClientBuild
    RootBuild -->|includes modules| ModelBuild
    RootBuild -->|includes modules| ServerBuild
    Settings -->|references| ClientBuild
    Settings -->|references| ModelBuild
    Settings -->|references| ServerBuild
    GHBuild -->|runs| RootBuild
    Qodana -->|analyzes| RootBuild

    %% Click Events
    click CUC "https://github.com/dnguyenminh/chunk-upload/blob/master/client/src/main/java/vn/com/fecredit/chunkedupload/client/ChunkedUploadClient.java"
    click CLIUnix "https://github.com/dnguyenminh/chunk-upload/blob/master/client/run-client.sh"
    click CLIWin "https://github.com/dnguyenminh/chunk-upload/blob/master/client/run-client.bat"
    click InitReq "https://github.com/dnguyenminh/chunk-upload/blob/master/model/src/main/java/vn/com/fecredit/chunkedupload/model/InitRequest.java"
    click InitRes "https://github.com/dnguyenminh/chunk-upload/blob/master/model/src/main/java/vn/com/fecredit/chunkedupload/model/InitResponse.java"
    click App "https://github.com/dnguyenminh/chunk-upload/blob/master/server/src/main/java/vn/com/fecredit/chunkedupload/UploadApplication.java"
    click CUController "https://github.com/dnguyenminh/chunk-upload/blob/master/server/src/main/java/vn/com/fecredit/chunkedupload/controller/ChunkedUploadController.java"
    click UserController "https://github.com/dnguyenminh/chunk-upload/blob/master/server/src/main/java/vn/com/fecredit/chunkedupload/controller/UserController.java"
    click Service "https://github.com/dnguyenminh/chunk-upload/blob/master/server/src/main/java/vn/com/fecredit/chunkedupload/service/ChunkedUploadService.java"
    click SessionManager "https://github.com/dnguyenminh/chunk-upload/blob/master/server/src/main/java/vn/com/fecredit/chunkedupload/manager/SessionManager.java"
    click BitsetManager "https://github.com/dnguyenminh/chunk-upload/blob/master/server/src/main/java/vn/com/fecredit/chunkedupload/manager/BitsetManager.java"
    click SecurityConfig "https://github.com/dnguyenminh/chunk-upload/blob/master/server/src/main/java/vn/com/fecredit/chunkedupload/config/SecurityConfig.java"
    click Props "https://github.com/dnguyenminh/chunk-upload/blob/master/server/src/main/resources/application.properties"
    click Logback "https://github.com/dnguyenminh/chunk-upload/blob/master/server/src/main/resources/logback.xml"
    click ServerRealIT "https://github.com/dnguyenminh/chunk-upload/blob/master/server/src/test/java/vn/com/fecredit/chunkedupload/integration/ChunkedUploadControllerRealIntegrationTest.java"
    click ServerUnitTest "https://github.com/dnguyenminh/chunk-upload/blob/master/server/src/test/java/vn/com/fecredit/chunkedupload/controller/ChunkedUploadControllerTest.java"
    click ClientIT "https://github.com/dnguyenminh/chunk-upload/blob/master/client/src/test/java/vn/com/fecredit/chunkedupload/client/ChunkedUploadClientIntegrationTest.java"
    click RootBuild "https://github.com/dnguyenminh/chunk-upload/blob/master/build.gradle"
    click Settings "https://github.com/dnguyenminh/chunk-upload/blob/master/settings.gradle"
    click ClientBuild "https://github.com/dnguyenminh/chunk-upload/blob/master/client/build.gradle"
    click ModelBuild "https://github.com/dnguyenminh/chunk-upload/blob/master/model/build.gradle"
    click ServerBuild "https://github.com/dnguyenminh/chunk-upload/blob/master/server/build.gradle"
    click GHBuild "https://github.com/dnguyenminh/chunk-upload/blob/master/.github/workflows/build-and-release.yml"
    click Qodana "https://github.com/dnguyenminh/chunk-upload/blob/master/.github/workflows/qodana_code_quality.yml"

    %% Styles
    classDef client fill:#D7E8FF,stroke:#1E70BF,stroke-width:1px;
    classDef server fill:#DFF2D8,stroke:#319F2F,stroke-width:1px;
    classDef model fill:#FFF5CC,stroke:#DFAF1B,stroke-width:1px;
    classDef storage fill:#FFE6CC,stroke:#E36D00,stroke-width:1px,stroke-dasharray: 5 5;
    classDef test fill:#F2E6FF,stroke:#7F3FBF,stroke-width:1px;
    classDef infra fill:#E8E8E8,stroke:#4A4A4A,stroke-width:1px;
```
