# dromara/ujcms architecture

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

- Interactive diagram: https://gitdiagram.com/dromara/ujcms
- Repository: https://github.com/dromara/ujcms

## Overview

##### Project Type and Purpose
- UJCMS is a Java-based, full-stack, enterprise CMS that supports both traditional server-rendered sites (Freemarker templates) and a headless CMS mode (REST API + SPA).
- Backend: a monolithic Spring Boot application (Spring Security, MyBatis, Liquibase, Quartz/Flowable, Lucene).
- Frontend:
- Public site: Freemarker templates under `src/main/webapp/templates`
- Admin site (“cp”): Vue3/ElementPlus SPA with assets in `src/main/webapp/cp`, built by Vite/Gulp.

##### High-Level Components
- Clients
- Public Browser → Freemarker-rendered pages
- Admin Browser → Vue3 SPA (calls backend REST)
- Spring Boot Application (single deployable jar/war)
- Web Layer
– Public MVC Controllers (Freemarker)
– REST Controllers (API under `/api`, backend API under `/cp/api`)
- Service Layer (business logic)
- Data Access Layer (MyBatis mappers + domain objects)
- Core Modules
– SecurityConfig, JwtAuthService
– CacheConfig (Spring Cache)
– LuceneConfig (embedded full-text search)
– ScheduleConfig (Quartz or Spring Scheduler)
– MyBatisConfig, SwaggerConfig
– AOP (OperationLogAspect)
- Extension Module (`com.ujcms.cms.ext`): plugin-style subsystems (collector, survey, message board, import, visit stat, vote, etc.)
- Common Libraries (`com.ujcms.commons`): shared utilities (captcha, db helpers, file handlers, freemarker tags, security, SMS, web helper classes)
- Persistence
- MySQL 8.0 (with Liquibase changelogs under `src/main/resources/db/changelog`)
- Freemarker template files and static uploads on filesystem (`/uploads`)
- Lucene index files (`WEB-INF/lucene`)
- External Services
- OAuth providers (Weixin, QQ, Weibo)
- SMTP/SMS gateways (Aliyun/Tencent utilities)
- Optional Redis or other cache backends if configured

##### Relationships & Data Flows
- Browser → HTTP(S) → Spring Boot Web Layer
- Web Layer → Service Layer → Data Access Layer → MySQL
- Service Layer ↔ Spring Cache (in-memory or Redis)
- Service Layer ↔ Lucene Engine (index + search)
- Startup → Liquibase applies DB migrations automatically
- Admin SPA → REST API Controllers → Service → DB/Cache

##### Architectural Patterns & Principles
- Layered MVC (Controller → Service → Mapper/DAO)
- Plugin/Extension architecture (`core` vs `ext` packages)
- Headless CMS support: decoupled API layer for modern SPAs
- Template-plus-tags for server-rendered mode vs API-first for SPAs
- Use of AOP for cross-cutting concerns (logging, security)
- Embedded full-text search with Lucene

##### Essential Elements
- Clients: Public Browser, Admin Browser (SPA)
- HTTP Layer: MVC Controllers, API Controllers
- Business Layer: Services, AOP aspects
- Data Layer: MyBatis mappers → MySQL (with Liquibase)
- Embedded Search: Lucene index store
- File Storage: templates & uploads directories
- Extensions: plugin modules under `com.ujcms.cms.ext`
- Commons: shared utilities
- External: OAuth, SMS/Email services

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients" 
        PublicBrowser["Public Site<br/>(Freemarker)"]:::ui
        AdminBrowser["Admin SPA<br/>(Vue3/ElementPlus)"]:::ui
    end

    %% Spring Boot Application
    subgraph "Spring Boot Application" 
        Entry["Application Entry Point"]:::app
        click Entry "https://github.com/dromara/ujcms/blob/master/src/main/java/com/ujcms/cms/Application.java"

        subgraph "Web Layer"
            MVC["Public MVC Controllers"]:::web
            click MVC "https://github.com/dromara/ujcms/tree/master/src/main/java/com/ujcms/cms/core/web/frontend"
            API["REST API Controllers<br/>(Public)"]:::web
            click API "https://github.com/dromara/ujcms/tree/master/src/main/java/com/ujcms/cms/core/web/api"
            BAPI["REST API Controllers<br/>(Admin)"]:::web
            click BAPI "https://github.com/dromara/ujcms/tree/master/src/main/java/com/ujcms/cms/core/web/backendapi"
        end

        subgraph "Core Config Modules"
            Sec["SecurityConfig"]:::config
            click Sec "https://github.com/dromara/ujcms/blob/master/src/main/java/com/ujcms/cms/core/SecurityConfig.java"
            Jwt["JwtAuthService"]:::config
            click Jwt "https://github.com/dromara/ujcms/blob/master/src/main/java/com/ujcms/cms/core/component/JwtAuthService.java"
            CacheC["CacheConfig"]:::config
            click CacheC "https://github.com/dromara/ujcms/blob/master/src/main/java/com/ujcms/cms/core/CacheConfig.java"
            LucC["LuceneConfig"]:::config
            click LucC "https://github.com/dromara/ujcms/blob/master/src/main/java/com/ujcms/cms/core/LuceneConfig.java"
            Sched["ScheduleConfig"]:::config
            click Sched "https://github.com/dromara/ujcms/blob/master/src/main/java/com/ujcms/cms/core/ScheduleConfig.java"
            MybC["MyBatisConfig"]:::config
            click MybC "https://github.com/dromara/ujcms/blob/master/src/main/java/com/ujcms/cms/core/MyBatisConfig.java"
            Swag["SwaggerConfig"]:::config
            click Swag "https://github.com/dromara/ujcms/blob/master/src/main/java/com/ujcms/cms/core/SwaggerConfig.java"
            TaskE["TaskExecutorConfig"]:::config
            click TaskE "https://github.com/dromara/ujcms/blob/master/src/main/java/com/ujcms/cms/core/TaskExecutorConfig.java"
            AOP["OperationLogAspect"]:::config
            click AOP "https://github.com/dromara/ujcms/blob/master/src/main/java/com/ujcms/cms/core/aop/OperationLogAspect.java"
        end

        subgraph "Service & Domain"
            Service["Service Layer"]:::service
            click Service "https://github.com/dromara/ujcms/tree/master/src/main/java/com/ujcms/cms/core/service"
            Domain["Domain Objects"]:::service
        end

        subgraph "Data Access Layer"
            Mappers["MyBatis Mappers"]:::data
            click Mappers "https://github.com/dromara/ujcms/tree/master/src/main/java/com/ujcms/cms/core/mapper"
            XML["XML Mappings"]:::data
            click XML "https://github.com/dromara/ujcms/tree/master/src/main/resources/com/ujcms/cms/core/mapper"
        end

        Plugin["Extension Module"]:::service
        click Plugin "https://github.com/dromara/ujcms/tree/master/src/main/java/com/ujcms/cms/ext"
        Commons["Common Libraries"]:::service
        click Commons "https://github.com/dromara/ujcms/tree/master/src/main/java/com/ujcms/commons"
    end

    %% Persistence
    subgraph "Persistence"
        DB["MySQL 8.0"]:::db
        Liquibase["Liquibase Changelogs"]:::persistence
        click Liquibase "https://github.com/dromara/ujcms/tree/master/src/main/resources/db/changelog"
        FS["File Store<br/>templates & uploads & lucene"]:::persistence
        click FS "https://github.com/dromara/ujcms/tree/master/src/main/webapp/templates"
        click FS "https://github.com/dromara/ujcms/tree/master/src/main/webapp/uploads"
    end

    %% External Services
    subgraph "External Services"
        OAuth["OAuth Providers"]:::external
        click OAuth "https://github.com/dromara/ujcms/tree/master/src/main/java/com/ujcms/commons/security/oauth"
        Sms["SMTP/SMS Gateways"]:::external
        click Sms "https://github.com/dromara/ujcms/tree/master/src/main/java/com/ujcms/commons/sms"
    end

    %% Clients to App
    PublicBrowser -->|"HTTP/HTTPS"| MVC
    AdminBrowser -->|"HTTP/HTTPS"| BAPI

    %% Web to Service
    MVC -->|"calls"| Service
    API -->|"calls"| Service
    BAPI -->|"calls"| Service

    %% Service to Data
    Service -->|"uses"| Mappers
    Mappers -->|"queries"| DB
    Service -->|"caches"| CacheC
    Service -->|"indexes/searches"| LucC
    LucC -->|"stores index in"| FS

    %% Service to File Store
    Service -->|"reads/writes"| FS
    MVC -->|"renders templates from"| FS

    %% Startup Migration
    Entry -->|"on startup"| Liquibase
    Liquibase -->|"migrates DB"| DB

    %% External integrations
    Service -->|"auth via"| OAuth
    Commons -->|"sends via"| Sms

    %% Extension & Commons dependencies
    Service --> Plugin
    Service --> Commons

    classDef ui fill:#cdeaff,stroke:#027bc3,color:#000;
    classDef app fill:#e0ffe0,stroke:#007f00,color:#000;
    classDef web fill:#d0eaff,stroke:#0077b6,color:#000;
    classDef config fill:#e8fdd8,stroke:#379237,color:#000;
    classDef service fill:#e0ffe0,stroke:#007f00,color:#000;
    classDef data fill:#fff3cd,stroke:#ffb700,color:#000;
    classDef db fill:#ffe5e5,stroke:#d90429,color:#000;
    classDef persistence fill:#ffe5e5,stroke:#d90429,color:#000;
    classDef external fill:#ffd7e0,stroke:#d00000,color:#000;
```
