# litchixian/rulo architecture

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

- Interactive diagram: https://gitdiagram.com/litchixian/rulo
- Repository: https://github.com/litchixian/rulo

## Overview

1. **Top-level shape**
   - This repo is split into two product surfaces plus deployment/support assets:
     - `rulo-api`: Rust backend workspace
     - `rulo-admin`: Vue 3 admin frontend
     - `bin/`: Docker/K3s deployment scripts
     - `migrations/` and `sql/`: schema bootstrap and historical database dumps
   - The architecture is a classic admin-platform split: browser UI talks to a Rust HTTP API, which talks to PostgreSQL and Redis.

2. **Backend runtime and boot path**
   - The backend is an Axum application (`rulo-api/app`) built on Tokio async runtime.
   - `app/src/main.rs` and `app/src/lib.rs` are the entry points; `common/src/bootstrap.rs` and `common/src/config.rs` handle startup/config loading.
   - The server is configured from TOML/environment, with `DATABASE_URL` expected for PostgreSQL access and Redis used for shared state.

3. **Backend layering**
   - Most backend domains follow the same internal shape:
     - `router.rs` defines HTTP routes
     - `handler.rs` contains request/response handling
     - `service.rs` contains business logic
     - `model.rs` defines payloads/domain structs
   - This repeats across `system/*`, `ai/*`, and `swagger/*`, so the diagram should show a consistent “route → handler → service → DB/cache” pipeline.

4. **Core business domains**
   - The `system` module is the main product surface and contains:
     - authentication (`auth`)
     - users (`user`)
     - roles (`role`)
     - permissions (`permission`)
     - menus (`menu`)
     - departments (`dept`)
     - audit logging (`audit`)
     - monitoring (`monitor`)
     - files (`file`)
   - These are the primary admin-platform building blocks and likely represent the RBAC/admin data model.

5. **Auth and RBAC boundary**
   - Authentication is JWT-based, with password hashing via Argon2 as noted in the README.
   - Authorization is centered around users, roles, menus, and permissions; this is reinforced by the presence of `permission_service_test.rs`, `role_service_test.rs`, and `user_service_test.rs`.
   - `macros/` contains procedural macros (`syn`, `quote`) for compile-time permission checks, making authorization partly a code-level boundary rather than only a runtime middleware concern.

6. **Shared backend infrastructure**
   - `common/` is the shared platform layer used across modules:
     - typed config and error/result handling
     - request extractors
     - application state
     - constants
     - utilities for IDs, IPs, JWT, passwords, Redis, serialization, and storage
   - `common/src/state.rs` is important for the diagram because it likely holds shared DB/cache/config handles injected into handlers/services.

7. **Cross-cutting middleware and control plane**
   - `app/src/middleware.rs` and `app/src/middleware/rate_limit.rs` show that request governance is handled centrally.
   - `system/audit/middleware.rs` suggests audit capture is also a cross-cutting concern, not just a normal business endpoint.
   - Logging is structured with `tracing`, so observability is a first-class backend concern.

8. **Non-RBAC feature areas**
   - `ai/` provides chat-related endpoints and services, exposed via its own router.
   - `file/` handles file operations, likely tying into storage utilities in `common`.
   - `monitor/` exposes server/health/metrics style data for the admin UI.
   - `swagger/` provides API documentation routes, separating docs from business endpoints.

9. **Persistence and initialization**
   - PostgreSQL is the system of record; `migrations/20260423000000_init.sql` seeds schema and default accounts.
   - `sql/dump-rulo-202604230951.sql` appears to be a full database snapshot for reference or restoration.
   - Redis is a secondary store used for session/token-related data and rate limiting, not the primary data source.

10. **Frontend architecture**
   - `rulo-admin` is a Vue 3 + TypeScript SPA built with Vite and Element Plus.
   - Its internal structure mirrors an admin console:
     - `src/api/admin/*` for backend API wrappers
     - `src/store/*` for Pinia state
     - `src/router/router.ts` for routing
     - `src/layout/*` for shell layouts
     - `src/view/*` for pages such as login, home, system management, monitor, profile, changelog, and about
   - `public/config.json` indicates the frontend reads environment/runtime backend configuration rather than hardcoding it.

11. **Frontend-to-backend data flow**
   - UI actions in Vue views call `src/api/admin/*.ts`, which use Axios via `src/util/request.ts`.
   - Stores (`user`, `layout`) manage session and UI state across pages.
   - The login flow and route guards are central to the app shell; `src/directive/auth.ts` suggests element-level permission gating in the UI as well.

12. **Deployment and environment boundary**
   - `bin/deploy-bak/rulo-docker` and `bin/deploy-bak/rulo-k3s` contain Docker and K3s deployment paths, including Nginx config and Kubernetes manifests.
   - This indicates the app is designed to run containerized, with an edge/web server layer in front of the frontend and API during deployment.
   - The repository therefore has three operational boundaries: browser SPA, Rust API, and infrastructure/runtime services (PostgreSQL, Redis, container platform).

13. **How to draw the architecture**
   - The clearest diagram is:
     - browser/user → Vue SPA
     - SPA → Axum API
     - API → PostgreSQL and Redis
     - API → optional storage/AI/documentation side paths
   - Inside the API, show shared `common` infrastructure feeding every module, and show `system/auth` and RBAC as the central control plane that governs most other admin endpoints.

Main entry points: [`rulo-api/app/src/main.rs`](https://github.com/litchixian/rulo/blob/master/rulo-api/app/src/main.rs) (API Entry), [`rulo-api/migrations/20260423000000_init.sql`](https://github.com/litchixian/rulo/blob/master/rulo-api/migrations/20260423000000_init.sql) (PostgreSQL), [`rulo-admin/src/main.ts`](https://github.com/litchixian/rulo/blob/master/rulo-admin/src/main.ts) (Admin SPA), [`rulo-api/app/src/router.rs`](https://github.com/litchixian/rulo/blob/master/rulo-api/app/src/router.rs) (API Router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client UI"]
  node_browser(("Browser<br/>user/client"))
  node_admin_app["Admin SPA<br/>Vue 3 app<br/>[main.ts]"]
  node_ui_api["API Clients<br/>Axios wrappers"]
  node_ui_store["UI Store<br/>Pinia state"]
  node_ui_router["Route Shell<br/>Vue router<br/>[router.ts]"]
end

subgraph group_api["Rust API"]
  node_api_entry["API Entry<br/>Axum binary<br/>[main.rs]"]
  node_api_router["API Router<br/>HTTP routing<br/>[router.rs]"]
  node_system_ctrl["System Core<br/>admin domain<br/>[system.rs]"]
  node_auth_mod["Auth<br/>[auth.rs]"]
  node_rbac_mod["RBAC<br/>users/roles/perm"]
  node_ops_mod["Ops<br/>audit/monitor/file"]
  node_ai_mod["AI Chat<br/>chat API<br/>[ai.rs]"]
  node_docs_mod["Swagger<br/>docs routes<br/>[swagger.rs]"]
end

subgraph group_shared["Shared Core"]
  node_bootstrap["Bootstrap<br/>startup/config<br/>[bootstrap.rs]"]
  node_state_cfg["State & Config<br/>shared core<br/>[state.rs]"]
  node_util_core["Utilities<br/>jwt/redis/storage<br/>[util.rs]"]
  node_perm_macros["Permission Macros<br/>proc macros<br/>[lib.rs]"]
end

subgraph group_ops["Deploy & Data"]
  node_postgres[("PostgreSQL<br/>primary DB")]
  node_redis[("Redis<br/>cache/store<br/>[redis_constant.rs]")]
  node_migrations["Migrations<br/>schema bootstrap"]
  node_deploy["Deploy Scripts<br/>docker/k3s<br/>[k3s-deploy.yaml]"]
end

node_browser -->|"uses"| node_admin_app
node_admin_app -->|"navigates"| node_ui_router
node_admin_app -->|"shares state"| node_ui_store
node_admin_app -->|"calls"| node_ui_api
node_ui_api -->|"HTTP"| node_api_entry
node_api_entry -->|"starts with"| node_bootstrap
node_bootstrap -->|"loads"| node_state_cfg
node_api_entry -->|"mounts"| node_api_router
node_api_router -->|"routes"| node_system_ctrl
node_api_router -->|"routes"| node_ai_mod
node_api_router -->|"routes"| node_docs_mod
node_system_ctrl -->|"includes"| node_auth_mod
node_system_ctrl -->|"includes"| node_rbac_mod
node_system_ctrl -->|"includes"| node_ops_mod
node_auth_mod -->|"uses"| node_redis
node_auth_mod -->|"reads/writes"| node_postgres
node_rbac_mod -->|"reads/writes"| node_postgres
node_ops_mod -->|"reads/writes"| node_postgres
node_ops_mod -->|"uses"| node_redis
node_ai_mod -->|"reads/writes"| node_postgres
node_api_entry -->|"build-time auth"| node_perm_macros
node_rbac_mod -->|"enforced by"| node_perm_macros
node_api_entry -->|"packages to"| node_deploy
node_migrations -->|"initializes"| node_postgres

click node_admin_app "https://github.com/litchixian/rulo/blob/master/rulo-admin/src/main.ts"
click node_ui_api "https://github.com/litchixian/rulo/tree/master/rulo-admin/src/api/admin"
click node_ui_store "https://github.com/litchixian/rulo/tree/master/rulo-admin/src/store"
click node_ui_router "https://github.com/litchixian/rulo/blob/master/rulo-admin/src/router/router.ts"
click node_api_entry "https://github.com/litchixian/rulo/blob/master/rulo-api/app/src/main.rs"
click node_api_router "https://github.com/litchixian/rulo/blob/master/rulo-api/app/src/router.rs"
click node_system_ctrl "https://github.com/litchixian/rulo/blob/master/rulo-api/app/src/system.rs"
click node_auth_mod "https://github.com/litchixian/rulo/blob/master/rulo-api/app/src/system/auth.rs"
click node_rbac_mod "https://github.com/litchixian/rulo/tree/master/rulo-api/app/src/system"
click node_ops_mod "https://github.com/litchixian/rulo/tree/master/rulo-api/app/src/system"
click node_ai_mod "https://github.com/litchixian/rulo/blob/master/rulo-api/app/src/ai.rs"
click node_docs_mod "https://github.com/litchixian/rulo/blob/master/rulo-api/app/src/swagger.rs"
click node_bootstrap "https://github.com/litchixian/rulo/blob/master/rulo-api/common/src/bootstrap.rs"
click node_state_cfg "https://github.com/litchixian/rulo/blob/master/rulo-api/common/src/state.rs"
click node_util_core "https://github.com/litchixian/rulo/blob/master/rulo-api/common/src/util.rs"
click node_perm_macros "https://github.com/litchixian/rulo/blob/master/rulo-api/macros/src/lib.rs"
click node_postgres "https://github.com/litchixian/rulo/blob/master/rulo-api/migrations/20260423000000_init.sql"
click node_redis "https://github.com/litchixian/rulo/blob/master/rulo-api/common/src/constant/redis_constant.rs"
click node_migrations "https://github.com/litchixian/rulo/blob/master/rulo-api/migrations/20260423000000_init.sql"
click node_deploy "https://github.com/litchixian/rulo/blob/master/bin/deploy-bak/rulo-k3s/k3s-deploy.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_admin_app,node_ui_api,node_ui_store,node_ui_router toneBlue
class node_api_entry,node_api_router,node_system_ctrl,node_auth_mod,node_rbac_mod,node_ops_mod,node_ai_mod,node_docs_mod toneAmber
class node_bootstrap,node_state_cfg,node_util_core,node_perm_macros toneMint
class node_postgres,node_redis,node_migrations,node_deploy toneRose
```

## Components

### Client UI

Vue admin console and browser interaction layer

- **Browser**: user/client · Administrator using the web console
- [Admin SPA](https://github.com/litchixian/rulo/blob/master/rulo-admin/src/main.ts): Vue 3 app · Main frontend application shell · `rulo-admin/src/main.ts`
- [API Clients](https://github.com/litchixian/rulo/tree/master/rulo-admin/src/api/admin): Axios wrappers · Frontend request layer for backend domains · `rulo-admin/src/api/admin`
- [UI Store](https://github.com/litchixian/rulo/tree/master/rulo-admin/src/store): Pinia state · Shared session and layout state · `rulo-admin/src/store`
- [Route Shell](https://github.com/litchixian/rulo/blob/master/rulo-admin/src/router/router.ts): Vue router · Page routing and navigation guards · `rulo-admin/src/router/router.ts`

### Rust API

Axum backend workspace and business domains

- [API Entry](https://github.com/litchixian/rulo/blob/master/rulo-api/app/src/main.rs): Axum binary · Backend startup and server entrypoints · `rulo-api/app/src/main.rs`
- [API Router](https://github.com/litchixian/rulo/blob/master/rulo-api/app/src/router.rs): HTTP routing · Top-level route composition for modules · `rulo-api/app/src/router.rs`
- [System Core](https://github.com/litchixian/rulo/blob/master/rulo-api/app/src/system.rs): admin domain · Primary RBAC and platform management surface · `rulo-api/app/src/system.rs`
- [Auth](https://github.com/litchixian/rulo/blob/master/rulo-api/app/src/system/auth.rs): JWT auth · Login, token, and cache-backed session handling · `rulo-api/app/src/system/auth.rs`
- [RBAC](https://github.com/litchixian/rulo/tree/master/rulo-api/app/src/system): users/roles/perm · Users, roles, permissions, menus, and departments · `rulo-api/app/src/system`
- [Ops](https://github.com/litchixian/rulo/tree/master/rulo-api/app/src/system): audit/monitor/file · Audit logging, monitoring, and file operations · `rulo-api/app/src/system`
- [AI Chat](https://github.com/litchixian/rulo/blob/master/rulo-api/app/src/ai.rs): chat API · Chat-oriented endpoints and services · `rulo-api/app/src/ai.rs`
- [Swagger](https://github.com/litchixian/rulo/blob/master/rulo-api/app/src/swagger.rs): docs routes · API documentation endpoints · `rulo-api/app/src/swagger.rs`

### Shared Core

Common runtime, config, state, and macros

- [Bootstrap](https://github.com/litchixian/rulo/blob/master/rulo-api/common/src/bootstrap.rs): startup/config · Config loading, app state, and server bootstrap · `rulo-api/common/src/bootstrap.rs`
- [State & Config](https://github.com/litchixian/rulo/blob/master/rulo-api/common/src/state.rs): shared core · Application state, config, constants, and errors · `rulo-api/common/src/state.rs`
- [Utilities](https://github.com/litchixian/rulo/blob/master/rulo-api/common/src/util.rs): jwt/redis/storage · Common helpers for IDs, JWT, passwords, Redis, and storage · `rulo-api/common/src/util.rs`
- [Permission Macros](https://github.com/litchixian/rulo/blob/master/rulo-api/macros/src/lib.rs): proc macros · Compile-time authorization checks · `rulo-api/macros/src/lib.rs`

### Deploy & Data

Database, Redis, schema, and deployment assets

- [PostgreSQL](https://github.com/litchixian/rulo/blob/master/rulo-api/migrations/20260423000000_init.sql): primary DB · System of record for users, roles, and admin data · `rulo-api/migrations/20260423000000_init.sql`
- [Redis](https://github.com/litchixian/rulo/blob/master/rulo-api/common/src/constant/redis_constant.rs): cache/store · Shared cache, tokens, and rate-limit state · `rulo-api/common/src/constant/redis_constant.rs`
- [Migrations](https://github.com/litchixian/rulo/blob/master/rulo-api/migrations/20260423000000_init.sql): schema bootstrap · Initial schema and seed data · `rulo-api/migrations/20260423000000_init.sql`
- [Deploy Scripts](https://github.com/litchixian/rulo/blob/master/bin/deploy-bak/rulo-k3s/k3s-deploy.yaml): docker/k3s · Container and cluster deployment assets · `bin/deploy-bak/rulo-k3s/k3s-deploy.yaml`

## Connections

- Browser → Admin SPA: uses · Administrator interacts with the SPA
- Admin SPA → Route Shell: navigates · Route-based page shell and guards
- Admin SPA → UI Store: shares state · Stores session and layout data
- Admin SPA → API Clients: calls · Views call typed API wrappers
- API Clients → API Entry: HTTP · Frontend requests reach the Rust backend
- API Entry → Bootstrap: starts with · Bootstraps config and application state
- Bootstrap → State & Config: loads · Config, constants, error/result types, and shared state
- API Entry → API Router: mounts · Server assembles top-level routing
- API Router → System Core: routes · Admin product surface
- API Router → AI Chat: routes · Chat surface
- API Router → Swagger: routes · Documentation surface
- System Core → Auth: includes · Authentication boundary
- System Core → RBAC: includes · Users, roles, permissions, menus, departments
- System Core → Ops: includes · Audit, monitoring, and files
- Auth → Redis: uses · Token/session cache and rate-limit support
- Auth → PostgreSQL: reads/writes · Credential and user data
- RBAC → PostgreSQL: reads/writes · Core admin entities live in the database
- Ops → PostgreSQL: reads/writes · Audit and monitoring data persistence
- Ops → Redis: uses · Shared runtime/cache state where needed
- AI Chat → PostgreSQL: reads/writes · Chat features may persist state
- API Entry → Permission Macros: build-time auth · Compile-time permission checks supplement runtime auth
- RBAC → Permission Macros: enforced by · Permissions are checked through macros
- API Entry → Deploy Scripts: packages to · Backend is containerized for Docker/K3s deployment
- Migrations → PostgreSQL: initializes · Schema bootstrap and seed data