# lyqgit/salvo-admin architecture

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

- Interactive diagram: https://gitdiagram.com/lyqgit/salvo-admin
- Repository: https://github.com/lyqgit/salvo-admin

## Overview

##### Project Type and Purpose
- This is a full-stack "admin" dashboard framework that combines:
- A Rust-based back end using the Salvo web framework (controllers, services, mappers, entities)
- A Vue 3 + Element Plus + Vite front end (based on Ruoyi-Vue3)
- Provides CRUD management of users, roles, departments, menus, dictionaries, notices, posts, plus a collaborative Excel editor (e-sheet via WebSocket).

##### High-Level Architecture
[Browser/Client]
↕ HTTP(S) & WebSocket
[Vue 3 + Element Plus SPA]
- Views & Components
- API layer (login, system, monitor, tool, etc.)
- WebSocket client for excel collaboration
- Vite dev server or static host
→
[Salvo Web Server (Rust)]
- Router layer (defines HTTP routes)
- Controller layer (chat, user, dept, dict, excel, monitor, swagger, etc.)
- Service layer (business logic)
- Mapper/DAO layer (MySQL queries via xml or code)
- Entity definitions (Rust structs for each table)
- Utils (JWT auth, Redis cache, MySQL pool, MD5, system config, response formatting)
- WebSocket handler for real-time Excel
- Swagger UI endpoint for docs
↕
[Storage & Cache]
- MySQL (persistent storage for all system data)
- Redis (caching, session management, pub/sub for WebSocket)

##### Component Relationships and Data Flow
a) User opens the Vue SPA → loads static assets (HTML/CSS/JS) via Vite or static server
b) SPA calls Salvo back end over REST:
- Authentication (login → JWT token or session cookie)
- CRUD operations → Controllers → Services → Mappers → MySQL
- Cache lookups/invalidations via Redis in Services or Utils
c) SPA opens a WebSocket connection to Salvo for collaborative Excel editing
- Messages routed to excel_websocket.rs → broadcast via Redis pub/sub if needed
d) API docs served at /swagger-ui, secured by basic auth

##### Architectural Patterns & Principles
- Layered/MVC-style: Router → Controller → Service → DAO (Mapper) → Database
- Separation of concerns:
- Controllers only handle HTTP concerns & request validation
- Services encapsulate business logic & coordinate transactions
- Mappers/DAOs handle raw SQL & mapping to Rust entities
- Utilities decouple cross-cutting concerns (auth, caching, hashing, response formatting)
- Real-time collaboration via WebSocket with Redis backing

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Layer
    subgraph "Client Layer" 
        direction TB
        ViteDev["Vite Dev/Static Server"]:::frontend
        Env["Env Configs"]:::frontend
        ViteConfig["vite.config.js"]:::frontend
        VitePlugins["Vite Plugins"]:::frontend
        VueApp["Vue3 App"]:::frontend
        Views["Views"]:::frontend
        Components["Components"]:::frontend
        APILayer["API Layer"]:::frontend
        WSClient["WebSocket Client"]:::frontend
        StaticAssets["Static Assets"]:::frontend
    end

    %% Server Layer
    subgraph "Salvo Server" 
        direction TB
        Router["Router"]:::backend
        Controllers["Controllers"]:::backend
        Services["Services"]:::backend
        Mappers["Mapper/DAO"]:::backend
        Entities["Entities"]:::backend
        WSHandler["WebSocket Handler"]:::backend
        Swagger["Swagger UI Endpoint"]:::backend
        subgraph "Utils" 
            direction TB
            UtilsJWT["JWT Auth"]:::utils
            UtilsRedis["Redis Cache"]:::utils
            UtilsMySQL["MySQL Pool"]:::utils
            UtilsMD5["MD5 Hashing"]:::utils
            UtilsSystem["System Config & Response Formatting"]:::utils
            UtilsCaptcha["Captcha"]:::utils
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        MySQL["MySQL"]:::database
        Redis["Redis"]:::database
        SQLScripts["SQL Scripts"]:::database
    end

    %% Connections
    ViteDev --> VueApp
    VueApp --> Views
    VueApp --> Components
    VueApp --> APILayer
    VueApp --> WSClient
    VueApp -->|"HTTP"| Router
    VueApp -->|WS| WSHandler

    Router --> Controllers
    Controllers --> Services
    Services --> Mappers
    Mappers --> MySQL
    Mappers --> SQLScripts
    Services --> UtilsRedis
    UtilsRedis --> Redis
    WSHandler --> UtilsRedis
    Controllers --> Swagger

    %% Click Events
    click ViteDev "https://github.com/lyqgit/salvo-admin/tree/main/ui/src"
    click Env "https://github.com/lyqgit/salvo-admin/blob/main/ui/.env.development"
    click ViteConfig "https://github.com/lyqgit/salvo-admin/blob/main/ui/vite.config.js"
    click VitePlugins "https://github.com/lyqgit/salvo-admin/tree/main/ui/vite/plugins"
    click StaticAssets "https://github.com/lyqgit/salvo-admin/tree/main/static/"
    click Views "https://github.com/lyqgit/salvo-admin/tree/main/ui/src/views"
    click Components "https://github.com/lyqgit/salvo-admin/tree/main/ui/src/components"
    click APILayer "https://github.com/lyqgit/salvo-admin/tree/main/ui/src/api"
    click WSClient "https://github.com/lyqgit/salvo-admin/blob/main/ui/src/api/tool/excel.js"
    click Router "https://github.com/lyqgit/salvo-admin/tree/main/src/router"
    click Controllers "https://github.com/lyqgit/salvo-admin/tree/main/src/controller"
    click Services "https://github.com/lyqgit/salvo-admin/tree/main/src/service"
    click Mappers "https://github.com/lyqgit/salvo-admin/tree/main/src/mapper"
    click Entities "https://github.com/lyqgit/salvo-admin/tree/main/src/entity"
    click UtilsJWT "https://github.com/lyqgit/salvo-admin/blob/main/src/utils/webtoken.rs"
    click UtilsRedis "https://github.com/lyqgit/salvo-admin/blob/main/src/utils/redis.rs"
    click UtilsMySQL "https://github.com/lyqgit/salvo-admin/blob/main/src/utils/mysql.rs"
    click UtilsMD5 "https://github.com/lyqgit/salvo-admin/blob/main/src/utils/md5.rs"
    click UtilsSystem "https://github.com/lyqgit/salvo-admin/blob/main/src/utils/system.rs"
    click UtilsSystem "https://github.com/lyqgit/salvo-admin/blob/main/src/utils/res.rs"
    click UtilsCaptcha "https://github.com/lyqgit/salvo-admin/blob/main/src/utils/captcha.rs"
    click WSHandler "https://github.com/lyqgit/salvo-admin/blob/main/src/websocket/excel_websocket.rs"
    click Swagger "https://github.com/lyqgit/salvo-admin/blob/main/src/controller/swagger_controller.rs"
    click SQLScripts "https://github.com/lyqgit/salvo-admin/blob/main/sql/*.sql"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef backend fill:#E0FFE0,stroke:#28A745,color:#236A3E
    classDef utils fill:#FFF4D0,stroke:#FFD33D,color:#B38600
    classDef database fill:#FFE0E0,stroke:#D73A49,color:#A12E2E
```
