# StackRivet-Server

**Repository Path**: xtym/stackrivet-server

## Basic Information

- **Project Name**: StackRivet-Server
- **Description**: 开源 AI 原生 Java 企业应用后端 / Spring Boot 后台管理系统框架，内置 RBAC、代码生成、OpenAPI、审计、资产存储、异步任务，适合 SaaS 与企业中后台快速开发。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-16
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# StackRivet Server

[![License](https://img.shields.io/badge/license-Apache--2.0-5E63E0)](LICENSE)
[![JDK](https://img.shields.io/badge/JDK-21-5E63E0)](pom.xml)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-4.0.6-5E63E0)](stackrivet-bom/pom.xml)
[![Docs](https://img.shields.io/badge/docs-stackrivet.zkthink.com-5E63E0)](https://stackrivet.zkthink.com/docs)

English | [简体中文](README.zh-CN.md)

AI-native Java enterprise backend for Spring Boot and Vue teams.

StackRivet Server is the open-source Community backend of StackRivet: a modular monolith that helps Java teams build real enterprise applications with RBAC, row-level data permissions, audit logs, governed code generation, Asset Service, async tasks, observability, and AI-readable engineering rules.

[Website](https://stackrivet.zkthink.com) · [Docs](https://stackrivet.zkthink.com/docs) · [Admin UI](https://github.com/zkmall/stackrivet-admin-ui) · [Live Demo](https://stackrivet-admin.zkthink.com) · [中文文档](https://stackrivet.zkthink.com/zh/docs)

> Generate governed business modules, not loose CRUD. Keep architecture, permissions, audit, OpenAPI, tests, object storage and upgrade paths in the same delivery flow.

## Why StackRivet Server

Most Java admin frameworks can create CRUD. Real projects need more certainty.

- **AI guardrails**: `AGENTS.md`, `llms.txt`, module rules and development standards make Codex, Cursor and Claude Code work inside explicit boundaries.
- **Governed code generation**: generate backend code, frontend pages, menus, permissions, OpenAPI annotations and test scaffolding together.
- **Enterprise access control**: Spring Security, JWT, RBAC, menu/button/API permissions and row-level data permission enforcement.
- **Production-ready Asset Service**: Local, S3-compatible and Aliyun OSS storage, signed URLs, metadata checks and multipart-upload paths.
- **Observable delivery baseline**: traceId, Actuator, Micrometer, optional OpenTelemetry profile, SBOM generation and CI gates.
- **Upgradeable customization path**: Flyway migrations, module manifests, generated-file discipline and clear architecture rules.

## Quick Start

Start the backend data stores, build the Maven reactor and run the boot app.

```bash
# Redis backs JWT revocation and the actuator health check.
docker compose up -d mysql redis

mvn install -DskipTests=true
mvn -pl stackrivet-app spring-boot:run
```

Then start the admin UI in the sibling repository:

```bash
cd ../stackrivet-admin-ui
pnpm install
pnpm dev
```

Open the admin console at `http://127.0.0.1:5173/`.

OpenAPI is available at `/v3/api-docs` and `/swagger-ui`, but it requires a bearer token. The management port is separate and loopback-bound by default:

```bash
curl http://127.0.0.1:9090/actuator/health
```

For the guided path, use the public docs:

- [Quick Start](https://stackrivet.zkthink.com/docs/getting-started/quick-start)
- [Installation](https://stackrivet.zkthink.com/docs/getting-started/installation)
- [Generate a Module](https://stackrivet.zkthink.com/docs/guides/generate-a-module)
- [Deployment](https://stackrivet.zkthink.com/docs/guides/deployment)

## What Is Included

| Area | Included in Community |
| --- | --- |
| Runtime | JDK 21, Spring Boot 4.0.6, Spring Security, MyBatis-Plus, Flyway |
| Architecture | Modular monolith, Maven reactor, architecture-boundary tests |
| System | Users, departments, posts, roles, menus, dictionaries, parameters |
| Security | JWT, RBAC, menu/button/API permissions, row-level data permissions |
| Audit | Login logs, operation logs, exception logs, traceId correlation |
| Generator | Table import, type mapping, template rendering, governed write-out |
| Asset Service | Local, S3-compatible, Aliyun OSS, signed URLs, multipart upload path |
| Import / Export | Framework-neutral CSV / XLSX import-export core, ready to compose with async tasks |
| Async Tasks | Task state machine, progress, retry/cancel states, local execution bridge |
| Observability | Actuator, Micrometer, traceId, optional OpenTelemetry profile |
| Plugin Base | Module manifest loader, permission/menu/dictionary registration |
| Delivery | Docker Compose, Dev Container, CLI doctor, SBOM, CI workflows |

## Module Map

The reactor builds 16 Maven modules. The default application assembles the core modules into `stackrivet-app`; the SnailJob adapter is built for compatibility but stays out of the default runtime unless you opt in.

| Module | Responsibility |
| --- | --- |
| `stackrivet-bom` | Centralized dependency BOM for Spring Boot, MyBatis-Plus, springdoc, object storage SDKs, EasyExcel and ArchUnit |
| `stackrivet-parent` | Parent POM, compiler `release=21`, plugin management and dependency rules |
| `stackrivet-common` | `R<T>`, `PageR<T>`, traceId holder, business exceptions and shared primitives |
| `stackrivet-security` | Login, JWT, RBAC, data permission context and token management |
| `stackrivet-system` | Users, departments, posts, roles, menus, dictionaries and parameters |
| `stackrivet-audit` | Operation, login and exception logs with traceId correlation |
| `stackrivet-asset` | Asset metadata, storage adapters, signed URLs and multipart upload |
| `stackrivet-generator` | Database introspection, type mapping, template rendering and governed write-out |
| `stackrivet-import-export` | Framework-neutral CSV / XLSX import-export core using EasyExcel for XLSX and a pure-JDK CSV path |
| `stackrivet-task` | Async task state machine, local execution bridge, scheduler SPI and job-handler registry |
| `stackrivet-observability` | Actuator, Micrometer, traceId and optional OpenTelemetry profile |
| `stackrivet-plugin` | Module manifest loader and permission/menu/dictionary registration |
| `stackrivet-cli` | Thin CLI; currently exposes `doctor` |
| `stackrivet-demo` | Ticket CRUD demo and scheduled-job handler examples |
| `stackrivet-scheduler-snailjob` | Optional SnailJob adapter; not a dependency of `stackrivet-app` |
| `stackrivet-app` | Spring Boot entrypoint, runtime assembly and ArchUnit boundary tests |

Architecture boundaries are enforced by [`ArchitectureTest`](stackrivet-app/src/test/java/com/stackrivet/app/architecture/ArchitectureTest.java).

## Engineering Rules

Read these before changing code:

- [`AGENTS.md`](AGENTS.md)
- [`llms.txt`](llms.txt)
- [`docs/development-standards.md`](docs/development-standards.md)
- [`CONTRIBUTING.md`](CONTRIBUTING.md)

Hard rules in short:

- Controller -> Service -> Domain -> Mapper. Do not cross layers.
- Entities stay inside the persistence boundary; APIs use DTO / VO.
- Protected endpoints declare `@PreAuthorize(...)`.
- Database changes go through Flyway.
- Business tables store `asset_id`, not raw file URLs.
- Do not log secrets, passwords, tokens or signed URLs.
- Generated modules should go through the generator flow, not freeform copy-paste.

## Development Checks

```bash
mvn -pl stackrivet-<module> -am test
mvn -pl stackrivet-app test -Dtest=ArchitectureTest
mvn verify
```

The CI workflows cover JDK 21 + JDK 25 compatibility, CodeQL, Dependabot and release-trust checks.

## Community and Commercial Editions

This repository contains the Apache-2.0 Community backend. Public Community documentation is hosted on the StackRivet website:

- [English docs](https://stackrivet.zkthink.com/docs)
- [中文文档](https://stackrivet.zkthink.com/zh/docs)
- [Pricing and edition boundaries](https://stackrivet.zkthink.com/pricing)

Pro and Enterprise materials are delivered separately to licensed customers. They are not part of this public repository.

## License

Apache License 2.0. See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).