Skip to content

CLAUDE.md

Latest commit

 

History

History
87 lines (70 loc) · 4.18 KB

CLAUDE.md

File metadata and controls

87 lines (70 loc) · 4.18 KB
Raw

stackrivet-server · Claude Code project memory

Scope: backend only. JDK 21 + Spring Boot 4.0.6 + MyBatis-Plus 3.5.16 + Flyway, packaged as a modular monolith. The frontend (Vue 3) lives at ../stackrivet-admin-ui/ (separate git repo). Public docs are published at https://stackrivet.zkthink.com/docs. This file is Claude-specific memory; AGENTS.md is the tool-neutral authority.

§1 · Authority

  • Hard rules for code changes come from AGENTS.md and docs/development-standards.md.
  • Module boundary is enforced by ArchUnit tests in stackrivet-app/src/test/.
  • Public concepts / edition boundaries live in the published docs at https://stackrivet.zkthink.com/docs.
  • Public website copy rules do not override backend engineering rules; use them only as product context.
  • Database schema lives in Flyway migrations. Table prefix sr_; never invent schema outside migrations.
  • API contract: base path /api/v1; unified response {code, message, data, traceId}; max pageSize=200.

§2 · 16-module layout

stackrivet-bom
stackrivet-parent
stackrivet-common         ← R<T>, PageR<T>, exceptions, traceId
stackrivet-security       ← auth, RBAC, data permissions
stackrivet-system         ← user / dept / post / role / menu / dict / param
stackrivet-audit          ← operation / login / exception logs
stackrivet-asset          ← Asset metadata + StorageAdapter
stackrivet-generator      ← code generator
stackrivet-import-export  ← Excel / CSV
stackrivet-task           ← async task state machine
stackrivet-observability  ← Actuator / Micrometer / OTel profile
stackrivet-plugin         ← module manifest registry
stackrivet-cli            ← thin CLI
stackrivet-demo           ← ticket CRUD demo + scheduled-job handler demos
stackrivet-scheduler-snailjob ← optional SnailJob 2.0 adapter (opt-in; NOT an app dependency)
stackrivet-app            ← Boot entry + ArchUnit tests

Forbidden cross-cuts (ArchUnit fails the build):

  1. stackrivet-common depends on anything in StackRivet → cycle.
  2. Controller → Mapper directly → bypasses transaction and audit.
  3. Returning Entity from Controller → over-exposure and lazy-load risk.
  4. stackrivet-demo referenced by any core module → demos pollute core.

§3 · Tech defaults (do not silently drift)

Layer Default Forward
JDK 21 25 verified in CI
Spring Boot 4.0.6 4.1.x when GA (separate branch only)
Spring Framework 7.0.7 follows Boot BOM
Spring Security 7.0.5 follows Boot BOM
Jackson 3.x (tools.jackson) follows Boot BOM
MyBatis-Plus 3.5.16 (mybatis-plus-spring-boot4-starter) follows Boot BOM
springdoc 3.0.3 follows Boot 4
MySQL 8.4 LTS 9.7 LTS smoke
PostgreSQL 18.4 -

§4 · Verification commands

mvn verify                                          # full reactor
mvn -pl stackrivet-<module> test                    # single module
mvn -pl stackrivet-app spring-boot:run              # run the app
mvn -pl stackrivet-app test -Dtest=ArchitectureTest # boundary check

§5 · Common pitfalls

  • Build with JDK 21 or later. maven.compiler.release=21 pins the bytecode target, so newer JDKs (25 is verified in CI) compile fine; just make sure JAVA_HOME points at JDK 21+.
  • Flyway loads db/migration/common (dialect-neutral) and db/migration/${stackrivet.db.vendor:mysql} (per-vendor), configured in stackrivet-app/src/main/resources/application.yml. Vendor-specific DDL goes in the matching subdirectory; the schema baseline is V1__baseline.sql in each vendor directory.

§6 · Proposal workflow

For non-trivial changes, start from a public issue/RFC or an explicit PR note that explains scope, non-goals, public API/schema/security impact and verification. Maintainers may mirror accepted decisions into private planning docs, but contributors should not need private docs to review the change.

§7 · Cross-repo references

  • Universal AI guide: AGENTS.md
  • Machine-readable map: llms.txt
  • Backend development standards: docs/development-standards.md
  • Public docs: https://stackrivet.zkthink.com/docs
  • Frontend implementation rules: ../stackrivet-admin-ui/AGENTS.md