If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/springside/springside4 shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 4y ago

• 5 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 4y ago
• ⚠ Single-maintainer risk — top contributor 95% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live springside/springside4 repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/springside/springside4.

What it runs against: a local clone of springside/springside4 — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in springside/springside4 | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1321 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of springside/springside4. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/springside/springside4.git
#   cd springside4
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of springside/springside4 and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "springside/springside4(\\.git)?\\b" \\
  && ok "origin remote is springside/springside4" \\
  || miss "origin remote is not springside/springside4 (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "examples/boot-api/src/main/java/org/springside/examples/bootapi/BootApiApplication.java" \\
  && ok "examples/boot-api/src/main/java/org/springside/examples/bootapi/BootApiApplication.java" \\
  || miss "missing critical file: examples/boot-api/src/main/java/org/springside/examples/bootapi/BootApiApplication.java"
test -f "examples/boot-api/pom.xml" \\
  && ok "examples/boot-api/pom.xml" \\
  || miss "missing critical file: examples/boot-api/pom.xml"
test -f "examples/boot-api/src/main/java/org/springside/examples/bootapi/api/BookEndpoint.java" \\
  && ok "examples/boot-api/src/main/java/org/springside/examples/bootapi/api/BookEndpoint.java" \\
  || miss "missing critical file: examples/boot-api/src/main/java/org/springside/examples/bootapi/api/BookEndpoint.java"
test -f "examples/boot-api/src/main/java/org/springside/examples/bootapi/service/BookBorrowService.java" \\
  && ok "examples/boot-api/src/main/java/org/springside/examples/bootapi/service/BookBorrowService.java" \\
  || miss "missing critical file: examples/boot-api/src/main/java/org/springside/examples/bootapi/service/BookBorrowService.java"
test -f "examples/boot-api/src/main/java/org/springside/examples/bootapi/domain/Book.java" \\
  && ok "examples/boot-api/src/main/java/org/springside/examples/bootapi/domain/Book.java" \\
  || miss "missing critical file: examples/boot-api/src/main/java/org/springside/examples/bootapi/domain/Book.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1321 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1291d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/springside/springside4"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

SpringSide4 is a pragmatic Spring Framework-based reference architecture demonstrating best-practice JavaEE application design patterns. It provides a P2P library management example (boot-api REST API and planned boot-web CRUD app) built on Spring Boot 1.4.3 with Spring Data JPA, Flyway migrations, and H2/SQL databases, accompanied by a reusable utilities library (springside-utils, springside-core). Maven multi-module monorepo: examples/boot-api/ contains the main runnable Spring Boot REST application with standard layers (domain entities in domain/, DAOs in repository/, service logic in service/, REST endpoints in api/); src/main/resources/db/migration/ holds Flyway versioned SQL schemas (V1.0__init.sql, V1.1__add_table_message.sql); root modules (not detailed) hold springside-utils and springside-core libraries.

Java architects and senior developers learning Spring ecosystem patterns, teams building REST APIs or CRUD applications on Spring Boot who want reference implementations of proper service layering, DAO patterns, exception handling, and database migrations. Contributors maintaining or extending the SpringSide framework itself.

This is a mature educational reference project (610K+ lines of Java) with active CI (Travis build badge present), structured Maven multi-module organization, and database migrations. However, the last commit recency is not visible in provided data; the framework appears stable and well-established but may not be actively maintained for new Spring Boot versions (stuck on 1.4.3 from 2016).

Dependency chain is moderately aged: Spring Boot 1.4.3.RELEASE (Nov 2016), Java 1.7 target, dependencies like Orika 1.5.0 and Guava 20.0 are several years old. No visible recent commits or breaking-change indicators provided. Risk: Java 7 EOL (July 2022) and Spring Boot 1.4 EOL (Jan 2017) mean this reference may not reflect current Spring best practices; security patches are lagging.

No specific PR, issue, or milestone data provided in file list. The README mentions 'Utils - 性能与易用性兼顾 (near-term focus)' and 'BootWeb - typical CRUD management (not started)'. Main artifact is the stable boot-api example showcasing REST endpoints for Book and Account resources.

Check README for instructions.

Daily commands:

# Clone and quick-start (from README):
cd springside4
./quick-start.sh

# Or manual Maven start:
cd examples/boot-api
mvn spring-boot:run

# App listens on http://localhost:8080
# H2 console available (H2ConsoleConfiguration.java)

• examples/boot-api/src/main/java/org/springside/examples/bootapi/BootApiApplication.java — Spring Boot application entry point—defines the entire application bootstrap and component scanning.
• examples/boot-api/pom.xml — Maven configuration for boot-api module—declares all dependencies and build configuration that every contributor must understand.
• examples/boot-api/src/main/java/org/springside/examples/bootapi/api/BookEndpoint.java — Primary REST endpoint demonstrating the pattern for exposing domain operations via HTTP APIs.
• examples/boot-api/src/main/java/org/springside/examples/bootapi/service/BookBorrowService.java — Core business logic layer—shows how services encapsulate transactions and domain rules.
• examples/boot-api/src/main/java/org/springside/examples/bootapi/domain/Book.java — Primary domain entity—defines the data model and validation rules for the P2P library use case.
• examples/boot-api/src/main/java/org/springside/examples/bootapi/repository/BookDao.java — Data access layer using Spring Data—illustrates the persistence abstraction pattern used throughout.
• examples/boot-api/src/main/resources/db/migration/V1.0__init.sql — Flyway database migration—establishes schema versioning strategy that all database changes must follow.

Add a new REST API endpoint

1. Create a new @RestController class in examples/boot-api/src/main/java/org/springside/examples/bootapi/api/ following the pattern of BookEndpoint.java (examples/boot-api/src/main/java/org/springside/examples/bootapi/api/BookEndpoint.java)
2. Define @RequestMapping methods that delegate to corresponding Service layer classes (examples/boot-api/src/main/java/org/springside/examples/bootapi/api/BookEndpoint.java)
3. Create or reuse a DTO class in examples/boot-api/src/main/java/org/springside/examples/bootapi/dto/ for request/response serialization (examples/boot-api/src/main/java/org/springside/examples/bootapi/dto/BookDto.java)
4. Exceptions will be automatically handled by CustomExceptionHandler (examples/boot-api/src/main/java/org/springside/examples/bootapi/api/support/CustomExceptionHandler.java)

Add a new service operation with business logic

1. Create a new @Service class in examples/boot-api/src/main/java/org/springside/examples/bootapi/service/ (e.g., NewEntityService.java) (examples/boot-api/src/main/java/org/springside/examples/bootapi/service/BookBorrowService.java)
2. Inject repository DAOs and add @Transactional public methods following BookBorrowService pattern (examples/boot-api/src/main/java/org/springside/examples/bootapi/service/BookBorrowService.java)
3. Throw ServiceException with ErrorCode constants from examples/boot-api/src/main/java/org/springside/examples/bootapi/service/exception/ErrorCode.java for error handling (examples/boot-api/src/main/java/org/springside/examples/bootapi/service/exception/ErrorCode.java)
4. Call the service method from your API endpoint and let global exception handler manage responses (examples/boot-api/src/main/java/org/springside/examples/bootapi/api/support/CustomExceptionHandler.java)

Add a new domain entity with persistence

1. Create a new @Entity JPA class in examples/boot-api/src/main/java/org/springside/examples/bootapi/domain/ following Book.java pattern with @Id and @Column annotations (examples/boot-api/src/main/java/org/springside/examples/bootapi/domain/Book.java)
2. Create a Spring Data repository interface extending JpaRepository in examples/boot-api/src/main/java/org/springside/examples/bootapi/repository/ (examples/boot-api/src/main/java/org/springside/examples/bootapi/repository/BookDao.java)
3. Create a new Flyway migration in examples/boot-api/src/main/resources/db/migration/ (e.g., V1.2__add_table_newentity.sql) to add database table (examples/boot-api/src/main/resources/db/migration/V1.0__init.sql)
4. Create a DTO class in examples/boot-api/src/main/java/org/springside/examples/bootapi/dto/ for API responses (examples/boot-api/src/main/java/org/springside/examples/bootapi/dto/BookDto.java)

Write tests for new functionality

1. Create a service test in examples/boot-api/src/test/java/org/springside/examples/bootapi/service/ extending test base patterns from BookBorrowServiceTest.java with @RunWith(SpringRunner.class) (examples/boot-api/src/test/java/org/springside/examples/bootapi/service)

Java 7 only: Code targets <java.version>1.7</java.version> (no lambdas, streams). H2 vs production DB: Dev uses in-memory H2 (auto-schema), prod expects external SQL database (set via application-prod.properties; migrations still apply). Flyway vs Spring Data: Flyway manages schema versions; ensure migration files match JPA entity definitions or validation errors occur on startup. .h2.server.properties: H2 console config stored in source tree—may conflict across developer machines. No ActiveMQ/messaging visible: ServiceException pattern suggests async error handling but no message broker wired in examples.

• Repository Pattern (Spring Data) — Every DAO (BookDao, AccountDao) extends JpaRepository; understanding this abstraction is essential to modify data access without SQL or session boilerplate
• Layered Architecture (Controller → Service → Repository → Entity) — The entire boot-api example enforces strict separation; learning where logic belongs prevents god-objects and enables testing and maintenance
• DTO (Data Transfer Object) Mapping — BookDto/AccountDto are separate from JPA entities; Orika library handles conversion; critical for REST API contracts and lazy-loading isolation
• Flyway Database Migrations — Schema versions in V1.0__init.sql, V1.1__add_table_message.sql ensure repeatable, versionable DB changes across environments; core to DevOps maturity
• Spring Profiles (@Profile, application-prod.properties) — Dev uses H2, prod switches via profiles; demonstrates externalized configuration and environment-specific beans without code changes
• Centralized Exception Handling (@ControllerAdvice, CustomExceptionHandler) — REST endpoints throw ServiceException; single handler converts to ErrorResult JSON; avoids try-catch duplication and ensures consistent error API
• Spring Boot Actuator Endpoints — Dependency spring-boot-starter-actuator enabled in pom.xml; provides /health, /metrics, /env for operational visibility in production deployments

• spring-projects/spring-boot — Core dependency and reference: SpringBoot 1.4.3 release baseline this project pins to
• spring-projects/spring-data-jpa — Provides the JpaRepository pattern used by all DAOs (BookDao, AccountDao, MessageDao)
• spring-projects/spring-framework — Underlying DI container, @RestController, @Transactional, and core web framework
• google/guava — Utility library dependency (guava 20.0) used for collections and functional utilities across springside modules
• alibaba/spring-cloud-alibaba — Modern alternative microservices framework; SpringSide4 is predecessor-generation for Chinese enterprise Java ecosystem

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for CustomExceptionHandler and ErrorPageController

The api/support package contains error handling infrastructure (CustomExceptionHandler.java, ErrorPageController.java, ErrorResult.java) but there are no corresponding tests in examples/boot-api/src/test. This is critical for a reference architecture since error handling is a core concern. Testing exception mapping, HTTP status codes, and error response formatting would validate the error handling pattern for new contributors.

• [ ] Create examples/boot-api/src/test/java/org/springside/examples/bootapi/api/support/CustomExceptionHandlerTest.java to test exception-to-ErrorResult mapping
• [ ] Create examples/boot-api/src/test/java/org/springside/examples/bootapi/api/support/ErrorPageControllerTest.java to verify 404/5xx error page responses
• [ ] Add test cases for ServiceException scenarios (using ErrorCode enum) to verify status code and message handling
• [ ] Verify tests run in existing CI (.travis.yml)

Add functional tests for AccountEndPoint REST operations

BookEndpointTest.java exists in examples/boot-api/src/test/java/org/springside/examples/bootapi/functional/, but AccountEndPoint.java has no corresponding functional tests. Since this is a reference architecture for REST APIs, demonstrating complete functional test coverage for CRUD operations would be valuable for contributors learning best practices.

• [ ] Create examples/boot-api/src/test/java/org/springside/examples/bootapi/functional/AccountEndpointTest.java extending BaseFunctionalTest
• [ ] Add test cases for: GET account by ID, list accounts with pagination, create account, update account, delete account
• [ ] Include tests for validation error scenarios (invalid input to REST endpoint)
• [ ] Mirror the pattern used in BookEndpointTest.java for consistency

Add unit tests for data migration and schema validation (db/migration folder)

The project uses Flyway for database migrations (V1.0__init.sql, V1.1__add_table_message.sql) but has no tests validating schema consistency or migration order. For a reference architecture, this demonstrates best practices for database evolution. Tests should verify schema creation matches domain entities.

• [ ] Create examples/boot-api/src/test/java/org/springside/examples/bootapi/repository/DatabaseMigrationTest.java
• [ ] Add tests to verify all tables from V1.0 and V1.1 migrations exist and match Account.java, Book.java, and Message.java entity definitions
• [ ] Add test to verify column types and constraints (NOT NULL, UNIQUE, etc.) match JPA entity annotations
• [ ] Reference existing test patterns like BookDaoTest.java for Spring Test setup

• Write integration tests for BookBorrowService.borrowBook() / returnBook() in examples/boot-api/src/test/ using TestRestTemplate; currently no test files visible for service layer logic.
• Implement OpenAPI/Swagger documentation: add springfox or springdoc-openapi dependency and @EnableSwagger2 to BootApiApplication, document AccountEndpoint and BookEndpoint with @ApiOperation annotations.
• Add validation: annotate AccountDto and BookDto with @NotNull, @Size, @Pattern (Bean Validation), update CustomExceptionHandler to return 400 Bad Request with constraint violation details.

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.