A Starter Template for Admin Panel Based on Rust and Amis.js/React

English | 简体中文

🎯 Project Goals

• Provide a quick starting point for building admin systems
• Use a modern Rust + Amis.js/React technology stack
• Follow Domain-Driven Design (DDD) and Clean Architecture principles

👀 Online Preview

Since the free plan of Render is used, access may be slow. The instance will freeze after 15 minutes of inactivity, and subsequent access will go through Render’s interstitial page. Please be aware.

https://oxide-admin.onrender.com/_

Please do not modify the password.

• Account: admin
• Password: 123456

✨ Features

• DDD: Separation of adapter (presentation), application services, domain models, and infrastructure layers.
• CQRS: Lightweight CQRS built-in, supporting read/write separation.
• PostgreSQL: Integrated PostgreSQL, based on sqlx.
• Event Bus: Built-in event system to decouple business logic via domain events.
• Dependency Injection: Supported by nject.
• Code Generation: One-click generation of module code such as CRUD, CommandHandler, QueryHandler, etc.
• Timezone Config: Configurable for database and scheduled jobs.
• Comprehensive coverage: complete unit test/integration test;
• API Docs: Generated using utoipa, available at /scalar, configurable to disable.
• Authentication: JWT-based with refresh_token and access_token issuance, validation, and refresh.
• Authorization: Built-in RBAC for flexible menu and API permission control.
• DB Auto Migration: No manual migrations required during deployment.
• Rate Limiting Middleware: Route-level rate limiting.
• Captcha: Prevent brute force and malicious requests.
• Logging & Tracing: Multiple logging options, supports OpenTelemetry.
• Built-in single_flight macro: Reduce DB load.
• File Upload & Access Signature: APIs for single file, image, and chunked upload; supports local FS and S3-compatible storage.
• KV Cache: With TTL support, via redis or moka.
• Background Tasks: Single-node via sqlite, distributed via postgres.
• Scheduled Task: Supports embedded execution or separate execution.
• Graceful Shutdown: Properly terminates services and releases resources.
• Multi-Source Config: Supports env vars, .env, and CLI args.
• Feature Flags: Supports flipt.
• I18n: Supports i18n using fluent. both frontend and backend are supported.
• Github CI: Auto build for x86_64-unknown-linux-gnu.
• Docker Image: Provides a Dockerfile for containerized deployment.

🎖️ Built-in Features

Feature	Name	Notes	Enabled by Default
Postgres tls	postgres_tls	Enable tls
KV Storage (choose one only)	kv_redb	Use redb as kv/cache, suitable for monolithic projects	✅
	kv_redis	Use redis as kv/cache, suitable for distributed projects
	kv_redis_tls	Use redis as kv/cache with TLS enabled
Background Tasks (choose one only)	bg_sqlite	Use sqlite for background tasks, suitable for monolithic projects
	bg_postgres	Use postgres for background tasks, suitable for distributed projects	✅
Cache (choose one only)	cache_moka	Use moka for cache, suitable for monolithic projects	✅
	cache_redis	Use redis for cache, suitable for distributed projects
Scheduled Tasks	serve_with_sched	Embed scheduled tasks in web server process (single-node). When disabled, can run separately via `server sched` (distributed).	✅
Object Storage (choose one only)	object_storage_fs	Use local filesystem	✅
	object_storage_s3	Use S3-compatible service as object storage
	object_storage_s3_tls	Use S3-compatible service with TLS enabled
Logging & Trace (multiple options allowed)	trace_console	Log output to console	✅
	trace_rolling	Rolling logs in JSON format
	trace_otlp	Integrate with OpenTelemetry, suitable for distributed projects
	trace_otlp_tls	Integrate with OpenTelemetry with TLS enabled
Feature Flags (choose one only)	flag_flipt	Use flipt as feature flag, suitable for distributed projects

Modify in bin/server/Cargo.toml.

🎈 Frontend

• Architecture: Powered by Amis.js low-code with rich components for fast CRUD, extendable with React custom components.
• Optimization: Auto obfuscation, gzip compression (brotli optional) at build time.
• Embedding: Static assets embedded into binaries.

⚙️ Tech Stack

• Backend: Rust + Axum + Nject + SQLx + Postgres
• Frontend: Amis.js + React + TypeScript + Rsbuild
• Tools: just + Bun

📁 Project Structure

oxide_admin/
├── app/                    # Rust backend
│   ├── adapter/            # API layer (REST endpoints)
│   ├── application/        # Application layer (use cases/services)
│   ├── domain/             # Domain layer (entities/value objects)
│   ├── infrastructure/     # Infrastructure layer (technical details)
│         └── port/             # Domain implementations
│         └── migration/        # Database migrations
│         └── repository/       # Repository implementations
├── frontend/             # Frontend app
├── target/               # Build output
└── Cargo.toml            # Workspace config

Strictly follows DDD design principles to ensure maintainability and scalability.

🛠️ Quick Start

Please ensure that you have installed Rust and Bun, as well as just.

Clone the project and initialize

git clone git@github.com:shmy/oxide_admin.git
cd oxide_admin
# start a postgres
docker compose up -d
# setup env
cp .env.example .env
# install sqlx-cli & cargo-watch
cargo install sqlx-cli cargo-watch
# setup sqlx migration
just setup

Run Backend

just dev

The backend listens on 127.0.0.1:8080 by default, and the frontend will have a dev server to proxy;

Run Frontend

cd frontend
bun install
bun run dev

Access http://127.0.0.1:3000/_

📦 Build Commands

• Local Architecture:

just build

• Cross Compilation: Linux/x86_64-unknown-linux-musl

Ensure that cross is installed, use cargo install cross to install.

just build_linux_x86_64_musl

• Cross Compilation: Windows/x86_64-pc-windows-msvc

Ensure that xwin is installed, use cargo install cargo-xwin to install.

just build_windows_x86_64_msvc

• Build Docker image

just build_image

🉑 Test

Install the following tools

cargo install cargo-llvm-cov
cargo install cargo-nextest
cargo install hurl

Run

just test

Generate Coverage Report

just test_coverage

📃 Code Generation

cargo g scaffold -h

More

cargo g -h