litchixian/rulo

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.