How yangzongzhuan/ruoyi-cloud works
1. Top-level shape
- This repo is a distributed, front-end/back-end separated microservice platform.
- The runtime is split into one Vue UI plus several Spring Boot services: gateway, auth, business modules, and a visual monitoring service.
- bootstrap.yml in each service, plus the docker/ and bin/ scripts, indicate the system is designed to run as independently deployable services rather than a monolith.
2. Request entry and edge layer
- All browser traffic starts at ruoyi-ui, is served behind Nginx in production, and then routed to ruoyi-gateway.
- ruoyi-gateway is the main edge boundary: it applies auth checks, XSS filtering, captcha validation, URL blacklist checks, and route rules before forwarding to backend services.
- This is also where the system centralizes API exposure and common request handling concerns.
3. Authentication and token flow
- ruoyi-auth is the dedicated authentication service.
- It handles login, registration, unlock, password checks, and token issuance/refresh through TokenController and its login services.
- The common security module provides the shared token/session logic, and Redis is used for permission/auth state as described in the README.
- Feign request interception and inner-auth annotations suggest service-to-service calls carry propagated identity context.
4. Business service boundaries
- ruoyi-modules/ruoyi-system is the core business administration service: users, roles, menus, departments, posts, configs, notices, login logs, and operation logs.
- ruoyi-modules/ruoyi-job owns scheduling and job execution, backed by Quartz-style scheduling utilities and job logs.
- ruoyi-modules/ruoyi-file owns file upload/storage/download and abstracts storage behind local vs MinIO implementations.
- ruoyi-modules/ruoyi-gen is the code generator, which reads database metadata and renders source/templates for Java, SQL, JS/TS, and Vue.
- ruoyi-visual/ruoyi-monitor is the monitoring/ops surface for runtime health and security-restricted admin views.
5. Shared API contracts
- ruoyi-api/ruoyi-api-system holds cross-service DTOs and OpenFeign-style remote interfaces such as user, file, and log services.
- Fallback factories live here too, which means backend services are loosely coupled through remote contracts with explicit failure handling.
- This module is the main boundary for service-to-service dependencies and should be drawn as a shared contract layer, not an executable service.
6. Common platform libraries
- ruoyi-common-core supplies the shared foundation: response objects, base entities/controllers, constants, exceptions, utilities, pagination, XSS helpers, and Excel/file helpers.
- ruoyi-common-security centralizes authorization, login checks, Feign header propagation, global exception handling, and web/security auto-configuration.
- ruoyi-common-log adds the @Log aspect and async log persistence behavior.
- ruoyi-common-redis, ruoyi-common-datascope, ruoyi-common-datasource, ruoyi-common-sensitive, and ruoyi-common-swagger are platform capabilities reused by multiple services.
7. Data access and storage
- The main transactional data store is MySQL, and each business service has its own mapper layer and SQL mapping files.
- Redis is used as the shared cache/session/permission store, especially for auth and security state.
- File storage is pluggable: local filesystem or MinIO in ruoyi-file.
- Database scripts under sql/ and Dockerized MySQL/Nacos/Redis show the infrastructure is meant to be reproducible and container-friendly.
8. Cross-cutting observability and logging
- Operation logs and login logs are modeled as first-class domain objects in the system service and are also supported by the logging common module.
- ruoyi-visual-monitor provides operational visibility into runtime health, JVM/system metrics, and database connectivity.
- The gateway and common security modules also contain exception handlers, making error handling part of the platform boundary rather than scattered in individual services.
9. Frontend architecture
- ruoyi-ui is a Vue 2 + Element UI application with its own router, store, permission directives, reusable components, and API wrappers.
- The UI is organized by feature areas that mirror backend modules: system management, monitor, tool/code generation, login/register, and dashboard.
- It talks to the backend only through the gateway-facing API layer, not directly to internal services.
10. Platform services and infrastructure
- Nacos is the registry/config center, so service discovery and shared configuration are externalized.
- Sentinel is used for traffic control and fallback behavior.
- Seata support is present for distributed transactions, though it is packaged as a shared dependency module.
- Nginx acts as the web entry point and static asset host; Docker Compose ties together the infrastructure stack and service containers.
11. Code generation pipeline
- The generator module reads table/column metadata from the database, then applies Velocity templates to emit backend and frontend scaffolding.
- The output includes controller/service/mapper/domain files, SQL, and Vue/TS/JS UI pages.
- This is a one-way tooling flow from database schema to generated code, not a runtime business flow.
12. How to draw the architecture
- Draw the browser/UI at the top, Nginx in front of the Vue app, then the gateway as the single ingress point.
- Behind the gateway place auth, system, job, file, generator, and monitor services, with shared Redis/MySQL/MinIO/Nacos infrastructure beneath them.
- Show ruoyi-api and ruoyi-common as shared libraries/contracts spanning the services, and mark logging/security/datascope/redis as cross-cutting concerns.
Main entry points: ruoyi-gateway Gateway · ruoyi-system System Service · ruoyi-auth Auth Service · ruoyi-job Job Service
Components 25
Edge & UI
Browser-facing entry, static hosting, and frontend application.
Backend Services
Independently deployable Spring Boot services behind the gateway.
- Gateway · Single ingress boundary for auth, XSS, captcha, blacklist, and route rules.
ruoyi-gateway - Auth Service · Handles login, registration, unlock, password checks, and token issuance.
ruoyi-auth - System Service · Core administration domain for users, roles, menus, departments, configs, notices, and logs.
ruoyi-modules/ruoyi-system - Job Service · Owns scheduled jobs, execution, and job logs.
ruoyi-modules/ruoyi-job - File Service · Handles upload, storage, and download with pluggable local or MinIO backends.
ruoyi-modules/ruoyi-file - Generator · Builds backend and frontend scaffolding from database metadata and templates.
ruoyi-modules/ruoyi-gen - Monitor · Operational visibility surface for health, JVM, system, and database checks.
ruoyi-visual/ruoyi-monitor
Shared Platform
Reusable contracts and common libraries spanning services.
- API Contracts · Shared remote interfaces, DTOs, models, and fallback factories for service-to-service calls.
ruoyi-api/ruoyi-api-system - Core Common · Base entities, responses, constants, utilities, pagination, XSS, Excel, and helpers.
ruoyi-common/ruoyi-common-core - Security Common · Login checks, token logic, Feign propagation, inner auth, and exception handling.
ruoyi-common/ruoyi-common-security - Log Common · @Log aspect and async log persistence support.
ruoyi-common/ruoyi-common-log - Redis Common · Redis configuration and service helpers shared across services.
ruoyi-common/ruoyi-common-redis - Data Scope · Row-level data scope annotation and aspect.
ruoyi-common/ruoyi-common-datascope - Datasource · Master/slave datasource annotations and routing support.
ruoyi-common/ruoyi-common-datasource - Sensitive · Sensitive-data annotations and JSON desensitization.
ruoyi-common/ruoyi-common-sensitive - Swagger · SpringDoc auto-configuration and API documentation support.
ruoyi-common/ruoyi-common-swagger
Infrastructure
External runtime dependencies and deployment stack.
- MySQL · Primary transactional database for business modules and generator metadata.
sql - Redis · Shared cache, session, permission, and auth-state store.
docker/redis - MinIO · Optional file storage backend for the file service.
docker/ruoyi/modules/file - Nacos · Service discovery and externalized configuration.
docker/nacos - Sentinel · Traffic shaping and fallback support in the platform.
- Seata · Distributed transaction support packaged as a shared platform dependency.
ruoyi-common/ruoyi-common-seata
Connections 32
- Browser → Nginx: loads site · Users access the application through the web entry point.
- Nginx → ruoyi-ui: serves app · Nginx serves the Vue frontend and static assets.
- ruoyi-ui → Gateway: API calls · The frontend talks to backend services only through the gateway.
- Gateway → Auth Service: login flow · Gateway routes authentication-related requests to the auth service.
- Gateway → System Service: business APIs · Gateway forwards administrative and system management requests.
- Gateway → Job Service: schedule APIs · Gateway forwards job and job-log requests.
- Gateway → File Service: file APIs · Gateway forwards upload and download requests.
- Gateway → Generator: generator APIs · Gateway forwards code-generation requests.
- Gateway → Monitor: ops views · Gateway exposes the monitoring surface behind platform security rules.
- Auth Service → Redis: tokens/state · Auth relies on Redis for shared login and permission state.
- Auth Service → API Contracts: remote user · Auth uses shared remote contracts and models for cross-service calls.
- System Service → MySQL: reads/writes · System service persists administration data and logs in MySQL.
- Job Service → MySQL: reads/writes · Scheduler state and logs are stored in MySQL.
- File Service → MySQL: metadata · File records and related metadata are stored in MySQL.
- File Service → MinIO: stores files · File service can persist binaries in MinIO or local storage.
- Generator → MySQL: reads schema · Generator reads table and column metadata from the database.
- System Service → API Contracts: contracts · System service shares DTOs and remote interfaces with other services.
- File Service → API Contracts: contracts · File service participates in the shared remote contract layer.
- System Service → Security Common: security · System service uses shared auth, permissions, and web security support.
- Auth Service → Security Common: security · Auth service uses shared token and login infrastructure.
- Gateway → Security Common: edge security · Gateway uses common security for request handling and exception boundaries.
- System Service → Log Common: audit logging · System service records business and operation logs through the shared log module.
- Job Service → Log Common: audit logging · Job service can emit structured business logs.
- Monitor → Security Common: restricted access · Monitoring views are protected by shared security rules.
- System Service → Data Scope: row scope · System service applies data-scope filtering for authorization-aware queries.
- System Service → Datasource: db routing · System service can use master/slave datasource routing support.
- System Service → Sensitive: masking · Sensitive fields can be masked in serialized responses.
- Gateway → Sentinel: fallback · Gateway integrates traffic control and fallback behavior.
- Auth Service → Nacos: register/config · Service discovery and configuration are externalized through Nacos.
- Gateway → Nacos: register/config · Gateway is discovered and configured through Nacos.
- System Service → Seata: tx support · Business services can participate in distributed transactions via Seata support.
- Job Service → Seata: tx support · Scheduler service shares distributed transaction support when needed.