Engineering standards

StackRivet’s engineering standards aren’t a style guide that lives only in a wiki — they’re encoded in AI guardrails, ArchUnit tests and CI gates, so a violation fails the build. This page summarizes the standards that govern the codebase; the project ships its full engineering-standards, architecture-governance and code-review documents alongside the code.

Invariants

Layering

• Controller → Service → Domain → Mapper, one direction only — never cross a layer.
• The entity never leaves the persistence boundary; use DTOs and VOs.

Security

• Default-deny; every protected endpoint declares @PreAuthorize.
• No plaintext passwords; no password / token / secret / captcha in logs.
• A rights check precedes every signed URL for a private file.

Data

• All schema changes go through Flyway — no manual production changes.
• Every list API paginates, pageSize max 200; sort uses a whitelist.
• Tables use the sr_ prefix and the standard columns.

Async & files

• Heavy work (import, export, generator writes) runs as an async task with an idempotencyKey, retry, error category and timeout.
• The Asset Service is the only file system; business tables store asset_id, never a URL.

Frontend

• Use the StackRivet design system; never ship default Element Plus chrome.

Process

• New business modules go through the generator, not freeform.
• Every commit has a reproducible Verified: line — no vague phrases.
• Branch lifespan ≤ 3 days; PR ≤ 500 lines of code.

Dependency discipline

One default way per problem, and a narrow dependency surface:

• Framework-first. Reach for JDK 21 built-ins, then Spring’s own utilities, then a mature domain library — before adding anything new. A narrow utility library is allowed only when those genuinely fall short, justified per case.
• No grab-bag utility libraries. Catch-all “toolbox” libraries (e.g. Hutool) are banned by the Maven enforcer — they encourage scattered, hard-to-audit usage. Hand-writing crypto, encoding or collection helpers is likewise an anti-pattern.
• No reflective bean mapping. DTO/VO mapping is explicit and hand-written (or compile-time generated), so a renamed or missing field fails the compile rather than silently mis-mapping.
• License review on every dependency. Because StackRivet has a commercial Enterprise tier and private deployment, copyleft (GPL / AGPL) cannot enter the default distribution — Apache-2.0 / MIT / BSD are preferred, and every selection ADR records the license.

CI gates

Merging to the main branch runs, at minimum:

1. Backend format check, unit tests, integration tests
2. Database migration validation
3. Code-generator snapshot tests
4. Frontend lint, typecheck, unit tests
5. Playwright E2E
6. Docker Compose smoke test
7. ArchUnit (or equivalent) architecture-boundary tests
8. CLI doctor smoke test

Release adds JDK 25 forward-compat, MySQL 9.7 smoke, real Aliyun OSS round-trip, CodeQL (or equivalent) and SBOM / signed-release checks.

The principle

Small teams and AI tools can’t be relied on to remember discipline, so StackRivet turns the discipline into something that runs: tests that fail, gates that block, rules an AI must read. That’s what keeps generated and hand-written code at the same standard.