# yzcheng90/x-springboot architecture

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

- Interactive diagram: https://gitdiagram.com/yzcheng90/x-springboot
- Repository: https://github.com/yzcheng90/x-springboot

## Overview

##### Project type and purpose
- X-SpringBoot is a monolithic, full-stack RESTful API platform (backend in Spring Boot 3.x, frontend in Vue2.x).
- It provides a rapid-development scaffold for mid-size Java services with built-in authentication, code‐generation, RBAC, file storage, logging, and common utilities.

##### File structure
- Top-level directories:
· authentication – Spring Security customization (filters, providers, handlers)
· common – utilities, annotations, AOP for logging, XSS filters
· config – global Spring configuration (MyBatisPlus, Swagger, Kaptcha, XSS)
· interceptor – JWT token and validation filters
· modules – business domains (sys for user/role/menu, oss for file storage, gen for code generation, apk versioning)
· resources – YAML profiles, SQL mappers, code‐gen templates
- Standard layered MVC: Controller → Service → Mapper (MyBatis-Plus) → Database
- Deployment artifacts: pom.xml (Maven), application‐*.yml, nginx.conf in doc.

##### Key components
a. Clients & Edge
- Web client (Vue2 SPA)
- Nginx (reverse proxy, load balancing)
b. Backend Application
- Spring Boot Application
· Authentication Layer (SecurityConfigurer, JWT filters, CustomUserDetailsService)
· Common Layer (AOP SysLogAspect, XSS filters, global exception handler)
· Config Layer (Swagger UI, MyBatisPlus, Kaptcha)
· Interceptor Layer (AuthenticationTokenFilter, ValidateCodeFilter)
· Business Modules:
- sys (user, role, menu management)
- oss (file upload/download, cloud adapters for Qiniu/MinIO)
- gen (dynamic code generation via templates)
- apk (version management)
c. Data Stores & External Services
- MySQL (persistent storage)
- Redis (cache, session or token store)
- MinIO or Qiniu Cloud (object storage)
d. Supporting Infrastructure
- Swagger API docs
- Logging (SLF4J/Log4j via SysLogAspect)

##### Relationships and data flows
- Client → (HTTPS) → Nginx → Spring Boot REST endpoints
- Security filter chain intercepts requests → JWT validation → Controller
- Controllers delegate to Service layer → MyBatisPlus Mappers → MySQL
- File APIs call OSS service → Qiniu/MinIO SDK → object storage
- Events (e.g. LoginLogEvent) published → listeners write to DB
- Redis used for caching lookup tables or session data

##### Important architectural patterns & design principles
- Layered MVC (Controller → Service → DAO)
- AOP for cross-cutting concerns (logging, exception handling, XSS)
- Custom JWT filter chain (stateless token auth)
- Template-based code generation (Velocity templates under resources/template)
- Modular package structure to isolate domains

##### Detail
- Sequence of filters in the security chain (ValidateCodeFilter → AuthenticationTokenFilter)
- AOP aspects intercepting controller methods for logging
- Code-generation flow: SysGenController → Velocity templates → Generated code in target project
- RBAC flow: SysUserService → permission checks (AuthIgnore annotation, SysLogAspect)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients & Edge
    subgraph "Client Side"
        WebClient["Vue2 SPA"]:::frontend
    end

    Nginx["Nginx\n(Reverse Proxy / Load Balancer)"]:::proxy

    WebClient -->|"HTTPS requests"| Nginx

    %% Backend Application
    subgraph "Spring Boot Application" 
        direction TB

        App["Application.java\n(Spring Boot Entry)"]:::backend
        SecurityLayer["Authentication Layer"]:::auth
        CommonLayer["Common Layer\n(Cross-Cutting Concerns)"]:::common
        ConfigLayer["Config Layer"]:::config
        InterceptorLayer["Interceptor Layer"]:::interceptor
        Modules["Business Modules"]:::backend

        App -->|starts| SecurityLayer
        App -->|starts| CommonLayer
        App -->|starts| ConfigLayer
        App -->|starts| InterceptorLayer
        App -->|loads| Modules

        %% Authentication Layer
        subgraph "Authentication Layer"
            direction TB
            SecCfg["SecurityConfigurer"]:::auth
            AuthTokenFilter["AuthenticationTokenFilter"]:::interceptor
            ValidateFilter["ValidateCodeFilter"]:::interceptor
            UserDetail["CustomUserDetailsService"]:::auth
            AuthProvider["CustomDaoAuthenticationProvider"]:::auth
            SecCfg -->|configures| AuthTokenFilter
            SecCfg -->|configures| ValidateFilter
            SecCfg -->|uses| UserDetail
            SecCfg -->|uses| AuthProvider
        end

        %% Common Layer
        subgraph "Common Layer"
            direction TB
            SysLog["SysLogAspect"]:::common
            ExceptionHandler["RRExceptionHandler"]:::common
            XSSFilters["XSS Filters"]:::common
            Utilities["Utilities"]:::common
            Events["LoginLogEvent & Listener"]:::common
            SysLog -->|intercepts| App
            ExceptionHandler -->|handles| App
        end

        %% Config Layer
        subgraph "Config Layer"
            direction TB
            MyBatisCfg["MyBatisPlusConfig"]:::config
            SwaggerCfg["SwaggerConfig"]:::config
            KaptchaCfg["KaptchaConfig"]:::config
            WebCfg["WebConfigurer & FilterConfig"]:::config
            IgnoreCfg["XssIgnoreConfig & AuthIgnoreConfig"]:::config
        end

        %% Interceptor Layer
        subgraph "Interceptor Layer"
            direction TB
            AuthTokenFilter
            ValidateFilter
        end

        %% Business Modules
        subgraph "Modules"
            direction TB
            subgraph "sys (User/Role/Menu)"
                SysController["Sys Controllers"]:::moduleSys
                SysService["Sys Services"]:::moduleSys
                SysMapper["Sys Mappers"]:::moduleSys
            end
            subgraph "oss (File Storage)"
                OssController["SysOssController"]:::moduleOss
                OssService["Oss Services"]:::moduleOss
                OssMapper["SysOssMapper"]:::moduleOss
            end
            subgraph "gen (Code Generation)"
                GenController["SysGenController"]:::moduleGen
                GenService["Gen Services"]:::moduleGen
                GenMapper["SysGenMapper"]:::moduleGen
            end
            subgraph "apk (APK Versioning)"
                ApkController["TbApkVersionController"]:::moduleApk
                ApkService["Apk Services"]:::moduleApk
                ApkMapper["TbApkVersionMapper"]:::moduleApk
            end
        end

    end

    %% Data Stores & External Services
    MySQL[(MySQL Database)]:::db
    Redis[(Redis Cache)]:::db
    MinIO["MinIO / Qiniu Cloud"]:::cloud
    SwaggerUI["Swagger UI"]:::docs
    Logging["SLF4J / Log4j\n(SysLogAspect)"]:::docs

    Nginx -->|forwards| App
    App -->|REST API calls| SwaggerUI
    App -->|logs| Logging
    App -->|SELECT/INSERT| MySQL
    App -->|cache| Redis
    OssService -->|SDK calls| MinIO

    %% Click Events
    click App "https://github.com/yzcheng90/x-springboot/blob/master/src/main/java/com/suke/czx/Application.java"
    click SecCfg "https://github.com/yzcheng90/x-springboot/blob/master/src/main/java/com/suke/czx/authentication/SecurityConfigurer.java"
    click AuthTokenFilter "https://github.com/yzcheng90/x-springboot/blob/master/src/main/java/com/suke/czx/interceptor/AuthenticationTokenFilter.java"
    click ValidateFilter "https://github.com/yzcheng90/x-springboot/blob/master/src/main/java/com/suke/czx/interceptor/ValidateCodeFilter.java"
    click UserDetail "https://github.com/yzcheng90/x-springboot/blob/master/src/main/java/com/suke/czx/authentication/detail/CustomUserDetailsService.java"
    click SysLog "https://github.com/yzcheng90/x-springboot/blob/master/src/main/java/com/suke/czx/common/aspect/SysLogAspect.java"
    click ExceptionHandler "https://github.com/yzcheng90/x-springboot/blob/master/src/main/java/com/suke/czx/common/exception/RRExceptionHandler.java"
    click MyBatisCfg "https://github.com/yzcheng90/x-springboot/blob/master/src/main/java/com/suke/czx/config/MyBatisPlusConfig.java"
    click SwaggerCfg "https://github.com/yzcheng90/x-springboot/blob/master/src/main/java/com/suke/czx/config/SwaggerConfig.java"
    click KaptchaCfg "https://github.com/yzcheng90/x-springboot/blob/master/src/main/java/com/suke/czx/config/KaptchaConfig.java"
    click SysController "https://github.com/yzcheng90/x-springboot/tree/master/src/main/java/com/suke/czx/modules/sys/controller"
    click SysService "https://github.com/yzcheng90/x-springboot/tree/master/src/main/java/com/suke/czx/modules/sys/service"
    click SysMapper "https://github.com/yzcheng90/x-springboot/tree/master/src/main/java/com/suke/czx/modules/sys/mapper"
    click OssController "https://github.com/yzcheng90/x-springboot/blob/master/src/main/java/com/suke/czx/modules/oss/controller/SysOssController.java"
    click OssService "https://github.com/yzcheng90/x-springboot/tree/master/src/main/java/com/suke/czx/modules/oss/service"
    click OssMapper "https://github.com/yzcheng90/x-springboot/blob/master/src/main/java/com/suke/czx/modules/oss/mapper/SysOssMapper.java"
    click GenController "https://github.com/yzcheng90/x-springboot/blob/master/src/main/java/com/suke/czx/modules/gen/controller/SysGenController.java"
    click GenService "https://github.com/yzcheng90/x-springboot/tree/master/src/main/java/com/suke/czx/modules/gen/service"
    click GenMapper "https://github.com/yzcheng90/x-springboot/blob/master/src/main/resources/mapper/gen/SysGenMapper.xml"
    click ApkController "https://github.com/yzcheng90/x-springboot/blob/master/src/main/java/com/suke/czx/modules/apk/controller/TbApkVersionController.java"
    click ApkService "https://github.com/yzcheng90/x-springboot/tree/master/src/main/java/com/suke/czx/modules/apk/service"
    click ApkMapper "https://github.com/yzcheng90/x-springboot/blob/master/src/main/java/com/suke/czx/modules/apk/mapper/TbApkVersionMapper.java"
    click WebClient "https://github.com/yzcheng90/x-springboot/tree/master/src/main/resources"
    click SwaggerUI "https://github.com/yzcheng90/x-springboot/tree/master/src/main/resources"
    click Logging "https://github.com/yzcheng90/x-springboot/blob/master/src/main/resources/logback-spring.xml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6
    classDef proxy fill:#EDEDED,stroke:#999999
    classDef backend fill:#FFF4D6,stroke:#D6A700
    classDef auth fill:#D0F0C0,stroke:#4CAF50
    classDef common fill:#E0F7FA,stroke:#00ACC1
    classDef config fill:#F3E5F5,stroke:#8E24AA
    classDef interceptor fill:#FFF3E0,stroke:#FB8C00
    classDef moduleSys fill:#FFE0B2,stroke:#FF9800
    classDef moduleOss fill:#FFECB3,stroke:#FFC107
    classDef moduleGen fill:#E8F5E9,stroke:#43A047
    classDef moduleApk fill:#FCE4EC,stroke:#EC407A
    classDef db fill:#FFFFFF,stroke:#000000,stroke-dasharray: 2 2
    classDef cloud fill:#E3F2FD,stroke:#1976D2,stroke-dasharray: 5 5
    classDef docs fill:#F5F5F5,stroke:#9E9E9E,stroke-dasharray: 2 2
```
