# kualk4410/dormitorymanagesystem architecture

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

- Interactive diagram: https://gitdiagram.com/kualk4410/dormitorymanagesystem
- Repository: https://github.com/kualk4410/dormitorymanagesystem

## Overview

##### Project Type and Purpose
- This is a full-stack web application named “DMS” (Dormitory Management System).
- Front-end: Vue3 single-page application (SPA) built with Vite, Element-Plus, and static asset handling.
- Back-end: Spring Boot monolith exposing RESTful APIs, layered as Controller → Service → MyBatis Mapper → MySQL.
- Database: MySQL 8.0, with ORM via MyBatis.
- External integrations: weather API, dorm water/electricity data API.
- File storage: image upload for cleaning records (likely on local disk or object storage).

##### High-Level Components
a. Client Layer
- Browser / Mobile Web.
- Vue3 SPA (components, router, utils/java_request.js).
- UI modules: Login, Index, Member, Record (E‐water, Labor, Photo, Rule), etc.
b. API Layer
- Spring Boot REST controllers (EwaterController, LaborController, RuleController, StudentController, TitleController).
- JWT‐based auth handled by JwtUtil and LoginInterceptor.
c. Business Layer
- Service interfaces (EwaterService, LaborService, …) and implementations.
- Utility classes (Md5Util, ThreadLocalUtil).
d. Data Access Layer
- MyBatis mappers (EwaterMapper, LaborMapper, …).
- POJOs representing tables (Ewater, Labor, Rule, Student, Title).
e. Persistence
- MySQL database.
- Schema: student, dorm, rule, clean_task, expense, event, repair_order, log tables.
f. External Services
- Weather forecasting API.
- University water/electricity usage API.
g. File Storage
- Uploaded images for cleaning records (could be local or cloud).
h. Logging
- Application logs stored under .DMS/log (daily log files).
i. DevOps (optional to show)
- Git branches (main/dev).
- Build tools: Maven (pom.xml), npm (package.json).
- Deployment artifacts: application.yml, Vite config.

##### Relationships and Interactions
- User’s browser sends HTTP(S) requests to the Vue SPA.
- SPA makes AJAX calls (java_request.js) carrying JWT tokens to Spring Boot REST endpoints.
- LoginInterceptor validates JWT; JwtUtil issues tokens on login.
- Controllers orchestrate requests to Service layer.
- Services enforce business rules (cleaning management, duty rotation, proposals, logs).
- Services call MyBatis Mappers to execute SQL against MySQL.
- For image uploads, backend stores files and returns URLs to front-end.
- Scheduled or on-demand tasks fetch data from external weather and utility APIs.
- Logs are appended to .DMS/log files.

##### Architectural Patterns and Principles
- Layered architecture: Presentation (Vue) → API (Controller) → Business (Service) → Data (Mapper) → Persistence.
- MVC on back-end: Controllers + Views (JSON) + Models (POJOs).
- Token-based stateless authentication (JWT).
- Configuration via application.yml.
- RESTful design: Resource controllers per entity.
- Modular front-end: Separation of Base components vs. feature-specific components.
- Low coupling: Front-end ↔ back-end via defined interfaces; back-end ↔ DB via MyBatis.
- High cohesion: Each service & mapper handles a single domain.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client"
        Browser["User Browser"]:::external
    end

    %% Front-end Layer
    subgraph "Front-end SPA (Vue3 + Vite)" 
        direction TB
        FE_main["main.js"]:::frontend
        FE_html["index.html"]:::frontend
        FE_vite["vite.config.js"]:::frontend
        FE_pkg["package.json"]:::frontend
        FE_router["router/index.js"]:::frontend
        FE_utils["java_request.js"]:::frontend
        FE_base["Base Components"]:::frontend
        FE_indexComps["IndexPage Components"]:::frontend
        FE_memberComps["MemberPage Components"]:::frontend
        FE_recordComps["RecordPage Components"]:::frontend
        FE_views["Views (Login, Index, Member, Records, Rule)"]:::frontend
    end

    Browser -->|"loads SPA (HTTP)"| FE_main
    FE_main --> FE_html
    FE_main --> FE_vite
    FE_main --> FE_pkg
    FE_main --> FE_router
    FE_router --> FE_utils
    FE_router --> FE_base
    FE_router --> FE_indexComps
    FE_router --> FE_memberComps
    FE_router --> FE_recordComps
    FE_router --> FE_views

    %% Back-end Layer
    subgraph "Back-end Server (Spring Boot)" 
        direction TB
        BE_app["DMSApplication.java"]:::backend
        BE_config["WebConfig & WebConfigurer"]:::backend
        BE_jwt["JwtUtil.java"]:::backend
        BE_interceptor["LoginInterceptor.java"]:::backend
        BE_controllers["Controllers (Ewater, Labor, Rule, Student, Title)"]:::backend
        BE_services_iface["Service Interfaces"]:::backend
        BE_services_impl["Service Implementations"]:::backend
        BE_mappers["MyBatis Mappers"]:::backend
        BE_pojos["Domain POJOs"]:::backend
        BE_utils["Md5Util & ThreadLocalUtil"]:::backend
        BE_appcfg["application.yml"]:::backend
        BE_pom["pom.xml"]:::backend
    end

    FE_utils -->|"AJAX calls (HTTP+JWT)"| BE_controllers
    BE_app --> BE_config
    BE_controllers -->|"calls"| BE_services_iface
    BE_services_iface --> BE_services_impl
    BE_services_impl --> BE_mappers
    BE_mappers -->|"executes SQL"| DB
    BE_services_impl -->|"calls External APIs"| WeatherAPI
    BE_services_impl -->|"calls External APIs"| UtilityAPI
    BE_services_impl -->|"stores files"| FileStorage
    BE_app -->|"logs events"| Logs

    %% Persistence and External
    DB["MySQL Database"]:::db
    WeatherAPI["Weather Forecast API"]:::external
    UtilityAPI["Utility Usage API"]:::external
    FileStorage["Image File Storage"]:::storage
    Logs["Application Logs (.DMS/log)"]:::logs

    %% Click Events
    click FE_main "https://github.com/kualk4410/dormitorymanagesystem/blob/main/v2/front/src/main.js"
    click FE_html "https://github.com/kualk4410/dormitorymanagesystem/blob/main/v2/front/index.html"
    click FE_vite "https://github.com/kualk4410/dormitorymanagesystem/blob/main/v2/front/vite.config.js"
    click FE_pkg "https://github.com/kualk4410/dormitorymanagesystem/blob/main/v2/front/package.json"
    click FE_router "https://github.com/kualk4410/dormitorymanagesystem/blob/main/v2/front/src/router/index.js"
    click FE_utils "https://github.com/kualk4410/dormitorymanagesystem/blob/main/v2/front/src/utils/java_request.js"
    click FE_base "https://github.com/kualk4410/dormitorymanagesystem/tree/main/v2/front/src/components/Base/"
    click FE_indexComps "https://github.com/kualk4410/dormitorymanagesystem/tree/main/v2/front/src/components/IndexPage/"
    click FE_memberComps "https://github.com/kualk4410/dormitorymanagesystem/tree/main/v2/front/src/components/MemberPage/"
    click FE_recordComps "https://github.com/kualk4410/dormitorymanagesystem/tree/main/v2/front/src/components/RecordPage/"
    click FE_views "https://github.com/kualk4410/dormitorymanagesystem/tree/main/v2/front/src/views/"
    click BE_app "https://github.com/kualk4410/dormitorymanagesystem/blob/main/v2/back/DMS/src/main/java/senior/DMSApplication.java"
    click BE_config "https://github.com/kualk4410/dormitorymanagesystem/blob/main/v2/back/DMS/src/main/java/senior/config/WebConfig.java"
    click BE_interceptor "https://github.com/kualk4410/dormitorymanagesystem/blob/main/v2/back/DMS/src/main/java/senior/interceptors/LoginInterceptor.java"
    click BE_jwt "https://github.com/kualk4410/dormitorymanagesystem/blob/main/v2/back/DMS/src/main/java/senior/utils/JwtUtil.java"
    click BE_controllers "https://github.com/kualk4410/dormitorymanagesystem/tree/main/v2/back/DMS/src/main/java/senior/controller/"
    click BE_services_iface "https://github.com/kualk4410/dormitorymanagesystem/tree/main/v2/back/DMS/src/main/java/senior/service/"
    click BE_services_impl "https://github.com/kualk4410/dormitorymanagesystem/tree/main/v2/back/DMS/src/main/java/senior/service/impl/"
    click BE_mappers "https://github.com/kualk4410/dormitorymanagesystem/tree/main/v2/back/DMS/src/main/java/senior/mapper/"
    click BE_pojos "https://github.com/kualk4410/dormitorymanagesystem/tree/main/v2/back/DMS/src/main/java/senior/pojo/"
    click BE_utils "https://github.com/kualk4410/dormitorymanagesystem/tree/main/v2/back/DMS/src/main/java/senior/utils/"
    click BE_appcfg "https://github.com/kualk4410/dormitorymanagesystem/blob/main/v2/back/DMS/src/main/resources/application.yml"
    click BE_pom "https://github.com/kualk4410/dormitorymanagesystem/blob/main/v2/back/DMS/pom.xml"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366D6,color:#0366D6;
    classDef backend fill:#DFFFE0,stroke:#228B22,color:#228B22;
    classDef db fill:#FFE0B2,stroke:#EF6C00,color:#EF6C00;
    classDef external fill:#E0E0E0,stroke:#666666,color:#333333;
    classDef storage fill:#F0F0F0,stroke:#999999,color:#666666;
    classDef logs fill:#F5F5F5,stroke:#AAAAAA,color:#555555;
```
