# insistence/ruoyi-vue3-fastapi architecture

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

- Interactive diagram: https://gitdiagram.com/insistence/ruoyi-vue3-fastapi
- Repository: https://github.com/insistence/ruoyi-vue3-fastapi

## Overview

##### Project Type and Purpose
- This is a full-stack, front-end/back-end-separated rapid-development framework based on Vue3/Element Plus (SPA) and FastAPI (Python).
- Frontend: Single-page application for user interface, routing, state management, and API calls.
- Backend: FastAPI monolith structured by modules (admin, generator, task), providing RESTful APIs, authentication (OAuth2+JWT), scheduling, caching, and code generation.

##### Analyzing the File Structure
- Top level:
- ruoyi-fastapi-frontend – Vue3 SPA with src (views, components, router, store, api), public/index.html, assets, Vite config.
- ruoyi-fastapi-backend – FastAPI app.py/server.py, modules, config, middlewares, exceptions, utils, SQL scripts, requirements.
- Backend layers:
- app.py & server.py – bootstrap and sub_applications registration (static, exception, middleware).
- config – environment, DB (SQLAlchemy), Redis, scheduler, constants, enums.
- middlewares – CORS, GZip, tracing.
- exceptions – error handlers.
- module_admin, module_generator, module_task – each with controller → service → dao → entity (DO/VO).
- utils – common helpers, cron, excel, template (Jinja2), logging, response formatting.
- sql – DDL scripts for MySQL and PostgreSQL.
- Frontend layers:
- src/views – pages by domain (login, dashboard, system, monitor, tool).
- src/api – HTTP wrappers for each backend module.
- src/store – Vuex modules (user, permission, settings).
- src/router – route definitions, permission guards.
- src/components, src/layout, src/plugins, src/utils – reusable UI & logic.

##### Insights from README
- Tech stack: Vue3, Element Plus, FastAPI, SQLAlchemy, MySQL/PostgreSQL, Redis, OAuth2+JWT.
- Core features: user/role/menu/dept/post/dict/config/notice logs, online users, scheduler tasks, system & cache monitoring, code gen via database introspection & Jinja2 templates.
- Deployment: separate build for front (npm/vite) and back (Python app with env files).

a. Main Components
- End User & Browser (Client)
- Frontend SPA (Vue3, Element Plus, Vite)
- HTTP(S) API Gateway (FastAPI server.py/app.py)
- Middleware Layer (CORS, GZip, tracing)
- Authentication & Authorization (OAuth2 + JWT)
- Module Routers & Controllers (admin, generator, task)
- Service Layer (business logic)
- Data Access Layer (DAO, SQLAlchemy)
- Relational Database (MySQL/PostgreSQL)
- Cache & Session Store (Redis)
- Scheduler (APScheduler via get_scheduler)
- Utilities & Templates (Jinja2 for code generation)
- Static File Server (sub_applications/staticfiles)

b. Relationships & Data Flows
1. Browser → SPA assets (HTML/CSS/JS) served by web server or CDN.
2. User actions in SPA → AJAX calls to FastAPI endpoints.
3. FastAPI receives request → passes through global middlewares (CORS, GZip, trace).
4. Authentication middleware checks OAuth2/JWT tokens → injects user context.
5. Router dispatch → Controller method for specific module.
6. Controller calls Service → Service calls DAO → DAO uses SQLAlchemy to execute SQL on RDS.
7. On read/write: DB persistent operations; on cacheable operations: Service may read/write Redis.
8. Scheduler triggers periodic tasks (module_task) via APScheduler → tasks may call services or utils.
9. Generator module uses Jinja2 templates to produce code artifacts (Python, SQL, Vue, JS) on-the-fly.
10. Responses (JSON) returned back to SPA, UI updates accordingly.

c. Architectural Patterns & Principles
- Layered (Controller → Service → DAO → Database)
- Modular Monolith: modules grouped by domain (admin, generator, task)
- Dependency Injection for DB/Redis/Scheduler via get_db, get_redis, get_scheduler
- Middleware pipeline for cross-cutting concerns (CORS, tracing, exception handling)
- Token-based stateless auth (OAuth2 + JWT)
- Template-based code generation (Jinja2)

d. Key Technologies
- Frontend: Vue3, Element Plus, Vue Router, Vuex, Vite
- Backend: FastAPI, SQLAlchemy, Pydantic, Redis, APScheduler, Jinja2
- Data Stores: MySQL/PostgreSQL, Redis
- Auth: OAuth2, JWT
- Build & Deployment: npm, Python scripts, .env files

##### Diagramming Conventions
- Labels: show protocol (HTTP/HTTPS, SQL, Redis CLI, JWT).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser)" 
        direction TB
        EndUser["End User"]:::client
        Browser["Browser"]:::client
    end

    %% Frontend Layer
    subgraph "Frontend (Vue3 SPA)" 
        direction TB
        Assets["SPA Assets\n(HTML/CSS/JS)"]:::frontend
        Views["Views (pages by domain)"]:::frontend
        Router["Routing (Vue Router)"]:::frontend
        Store["State Management (Vuex)"]:::frontend
        API["API Wrappers\n(HTTP calls)"]:::frontend
        Components["Components & Layouts"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (FastAPI Monolith)"
        direction TB
        Bootstrap["API Gateway\n(app.py / server.py)"]:::backend
        subgraph "Middlewares & Exceptions"
            direction TB
            Middlewares["CORS, GZip, Tracing"]:::backend
            Exceptions["Exception Handling"]:::backend
        end
        Auth["Authentication & Authorization\n(OAuth2 + JWT)"]:::backend
        subgraph "Modules"
            direction TB
            subgraph "Admin Module"
                direction TB
                AdminController["Admin Controllers"]:::backend
                AdminService["Admin Services"]:::backend
                AdminDAO["Admin DAO"]:::backend
                AdminEntity["Admin Entities"]:::backend
            end
            subgraph "Generator Module"
                direction TB
                GenController["Gen Controller"]:::backend
                GenService["Gen Service"]:::backend
                GenDAO["Gen DAO"]:::backend
                GenEntity["Gen Entities"]:::backend
                Templates["Code Templates\n(Jinja2)"]:::backend
            end
            subgraph "Task Module & Scheduler"
                direction TB
                TaskScheduler["Scheduler Test"]:::backend
            end
        end
        Utils["Utilities\n(common helpers, cron, excel, logging, response)"]:::backend
        StaticFiles["Static File Server"]:::backend
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        RDBMS["Relational Database\n(MySQL/PostgreSQL)"]:::datastore
        Redis["Cache & Session Store\n(Redis)"]:::datastore
    end

    %% Scheduler Infra
    subgraph "Infrastructure"
        direction TB
        Scheduler["APScheduler"]:::infra
    end

    %% Connections
    EndUser --> Browser
    Browser --> Assets
    Assets --> API
    API -->|HTTP/HTTPS| Bootstrap
    Bootstrap --> Middlewares
    Middlewares --> Auth
    Auth --> AdminController
    Auth --> GenController
    Auth --> TaskScheduler
    AdminController --> AdminService
    AdminService --> AdminDAO
    AdminDAO -->|SQLAlchemy| RDBMS
    GenController --> GenService
    GenService --> GenDAO
    GenDAO -->|SQLAlchemy| RDBMS
    GenService --> Redis
    GenService --> Templates
    TaskScheduler -.->|trigger| Scheduler
    Scheduler --> TaskScheduler
    TaskScheduler --> AdminService
    StaticFiles --> Browser
    Utils --> AdminService
    Utils --> GenService
    Utils --> TaskScheduler

    Views --> Router
    Router --> API
    Store --> API
    Components --> Assets

    %% Click Events
    click Assets "https://github.com/insistence/ruoyi-vue3-fastapi/tree/master/ruoyi-fastapi-frontend/src"
    click Router "https://github.com/insistence/ruoyi-vue3-fastapi/blob/master/ruoyi-fastapi-frontend/src/router/index.js"
    click Store "https://github.com/insistence/ruoyi-vue3-fastapi/tree/master/ruoyi-fastapi-frontend/src/store"
    click API "https://github.com/insistence/ruoyi-vue3-fastapi/tree/master/ruoyi-fastapi-frontend/src/api"
    click Views "https://github.com/insistence/ruoyi-vue3-fastapi/tree/master/ruoyi-fastapi-frontend/src/views"
    click Components "https://github.com/insistence/ruoyi-vue3-fastapi/tree/master/ruoyi-fastapi-frontend/src/components"
    click Bootstrap "https://github.com/insistence/ruoyi-vue3-fastapi/blob/master/ruoyi-fastapi-backend/app.py"
    click Bootstrap "https://github.com/insistence/ruoyi-vue3-fastapi/blob/master/ruoyi-fastapi-backend/server.py"
    click Middlewares "https://github.com/insistence/ruoyi-vue3-fastapi/blob/master/ruoyi-fastapi-backend/middlewares/cors_middleware.py"
    click Middlewares "https://github.com/insistence/ruoyi-vue3-fastapi/blob/master/ruoyi-fastapi-backend/middlewares/gzip_middleware.py"
    click Middlewares "https://github.com/insistence/ruoyi-vue3-fastapi/tree/master/ruoyi-fastapi-backend/middlewares/trace_middleware"
    click Exceptions "https://github.com/insistence/ruoyi-vue3-fastapi/blob/master/ruoyi-fastapi-backend/exceptions/handle.py"
    click Auth "https://github.com/insistence/ruoyi-vue3-fastapi/blob/master/ruoyi-fastapi-backend/module_admin/controller/login_controller.py"
    click Auth "https://github.com/insistence/ruoyi-vue3-fastapi/blob/master/ruoyi-fastapi-backend/module_admin/service/login_service.py"
    click AdminController "https://github.com/insistence/ruoyi-vue3-fastapi/tree/master/ruoyi-fastapi-backend/module_admin/controller"
    click AdminService "https://github.com/insistence/ruoyi-vue3-fastapi/tree/master/ruoyi-fastapi-backend/module_admin/service"
    click AdminDAO "https://github.com/insistence/ruoyi-vue3-fastapi/tree/master/ruoyi-fastapi-backend/module_admin/dao"
    click AdminEntity "https://github.com/insistence/ruoyi-vue3-fastapi/tree/master/ruoyi-fastapi-backend/module_admin/entity"
    click GenController "https://github.com/insistence/ruoyi-vue3-fastapi/blob/master/ruoyi-fastapi-backend/module_generator/controller/gen_controller.py"
    click GenService "https://github.com/insistence/ruoyi-vue3-fastapi/blob/master/ruoyi-fastapi-backend/module_generator/service/gen_service.py"
    click GenDAO "https://github.com/insistence/ruoyi-vue3-fastapi/blob/master/ruoyi-fastapi-backend/module_generator/dao/gen_dao.py"
    click GenEntity "https://github.com/insistence/ruoyi-vue3-fastapi/tree/master/ruoyi-fastapi-backend/module_generator/entity"
    click Templates "https://github.com/insistence/ruoyi-vue3-fastapi/tree/master/ruoyi-fastapi-backend/module_generator/templates"
    click TaskScheduler "https://github.com/insistence/ruoyi-vue3-fastapi/blob/master/ruoyi-fastapi-backend/module_task/scheduler_test.py"
    click Utils "https://github.com/insistence/ruoyi-vue3-fastapi/tree/master/ruoyi-fastapi-backend/utils"
    click RDBMS "https://github.com/insistence/ruoyi-vue3-fastapi/blob/master/ruoyi-fastapi-backend/sql/ruoyi-fastapi.sql"
    click RDBMS "https://github.com/insistence/ruoyi-vue3-fastapi/blob/master/ruoyi-fastapi-backend/sql/ruoyi-fastapi-pg.sql"
    click StaticFiles "https://github.com/insistence/ruoyi-vue3-fastapi/blob/master/ruoyi-fastapi-backend/sub_applications/staticfiles.py"

    %% Styles
    classDef client fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef frontend fill:#FCF3CF,stroke:#7D6608,color:#1B2631
    classDef backend fill:#D5F5E3,stroke:#117A65,color:#1B2631
    classDef datastore fill:#FADBD8,stroke:#922B21,color:#1B2631
    classDef infra fill:#E8DAEF,stroke:#6C3483,color:#1B2631
```
