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/xkcoding/spring-boot-demo 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.

GO — Healthy across all four use cases

• 9 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 87% 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 xkcoding/spring-boot-demo repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/xkcoding/spring-boot-demo.

What it runs against: a local clone of xkcoding/spring-boot-demo — 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 xkcoding/spring-boot-demo | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | 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 ≤ 683 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of xkcoding/spring-boot-demo. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/xkcoding/spring-boot-demo.git
#   cd spring-boot-demo
#
# 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 xkcoding/spring-boot-demo and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT 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 "demo-activiti/src/main/java/com/xkcoding/activiti/SpringBootDemoActivitiApplication.java" \\
  && ok "demo-activiti/src/main/java/com/xkcoding/activiti/SpringBootDemoActivitiApplication.java" \\
  || miss "missing critical file: demo-activiti/src/main/java/com/xkcoding/activiti/SpringBootDemoActivitiApplication.java"
test -f "demo-activiti/src/main/resources/application.yml" \\
  && ok "demo-activiti/src/main/resources/application.yml" \\
  || miss "missing critical file: demo-activiti/src/main/resources/application.yml"
test -f "demo-activiti/pom.xml" \\
  && ok "demo-activiti/pom.xml" \\
  || miss "missing critical file: demo-activiti/pom.xml"
test -f "demo-activiti/src/main/java/com/xkcoding/activiti/config/SecurityConfiguration.java" \\
  && ok "demo-activiti/src/main/java/com/xkcoding/activiti/config/SecurityConfiguration.java" \\
  || miss "missing critical file: demo-activiti/src/main/java/com/xkcoding/activiti/config/SecurityConfiguration.java"
test -f "demo-activiti/src/main/java/com/xkcoding/activiti/util/SecurityUtil.java" \\
  && ok "demo-activiti/src/main/java/com/xkcoding/activiti/util/SecurityUtil.java" \\
  || miss "missing critical file: demo-activiti/src/main/java/com/xkcoding/activiti/util/SecurityUtil.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 683 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~653d)"
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/xkcoding/spring-boot-demo"
  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).

Spring Boot Demo is a comprehensive learning project containing 55+ completed integration examples demonstrating Spring Boot best practices across workflow automation, caching, messaging, security, and data persistence. It serves as a reference implementation for integrating 40+ enterprise technologies (Activiti, Redis, RabbitMQ, Kafka, Elasticsearch, MongoDB, Dubbo) into Spring Boot applications with working code examples for each. Monorepo structure with 66 independent Maven modules (demo-activiti, demo-actuator, demo-admin, etc.), each self-contained under com.xkcoding package hierarchy with standardized layout: src/main/java (application code), src/main/resources (configuration), src/test/java (tests). All modules inherit from parent pom.xml at repository root, centralizing dependency management.

Java developers learning Spring Boot in depth, especially those building enterprise applications who need concrete, copy-paste-ready examples of integrating workflow engines, distributed systems, security frameworks, and data stores without starting from scratch.

Actively developed and mature for educational purposes: 66 planned demos with 55 completed, well-organized multi-module Maven structure, GitHub Actions CI/CD pipeline (maven.yml), Codacy code quality integration, and badges indicating Java 1.8+ and Spring Boot 2.1.0. This is a reference project, not a framework, so production-readiness depends on which specific demo module you use.

Low risk as an educational repository—no external API dependencies or production data concerns. However, dependency versions may drift (Spring Boot 2.1.0 from 2019, some demos use older Activiti 7.1.0.M2 milestone versions). Single maintainer (xkcoding) means PR review velocity depends on their availability. Individual demo modules may have breaking changes if their underlying libraries (Activiti, Dubbo, Kafka) update major versions.

Project tracks 66 planned integrations with ~55 completed; TODO.md and TODO.en.md list remaining items. GitHub/Gitee issue templates and PR templates are configured, suggesting active community intake. Latest visible work includes modules for distributed rate limiting (Redis + Lua), multiple datasources (JPA/Mybatis), and containerization (Docker). No specific recent commit data visible in file list, but CI pipeline (maven.yml) indicates builds are automated.

git clone https://github.com/xkcoding/spring-boot-demo.git && cd spring-boot-demo && mvn clean install. Then enter any demo module (e.g., cd demo-activiti && mvn spring-boot:run) to start that specific example.

Daily commands: cd <specific-demo-module> && mvn spring-boot:run. For example: cd demo-actuator && mvn spring-boot:run will start the actuator monitoring demo on default Spring Boot port (typically 8080 with endpoints at /actuator). Individual modules have application.yml in src/main/resources defining server port and datasource config.

• demo-activiti/src/main/java/com/xkcoding/activiti/SpringBootDemoActivitiApplication.java — Entry point for the Activiti workflow engine integration demo; all contributors must understand the application bootstrap and Activiti configuration initialization.
• demo-activiti/src/main/resources/application.yml — Core configuration file defining Activiti datasource, JPA, and workflow engine properties that affect all module functionality.
• demo-activiti/pom.xml — Dependency manifest for Activiti, Spring Boot, and security libraries; critical for understanding what versions and frameworks are in use.
• demo-activiti/src/main/java/com/xkcoding/activiti/config/SecurityConfiguration.java — Security and authentication configuration for the Activiti demo; essential for understanding user/role handling in workflow execution.
• demo-activiti/src/main/java/com/xkcoding/activiti/util/SecurityUtil.java — Utility class for extracting security context and user information; used throughout the codebase for process task assignment.
• demo-activiti/src/main/resources/processes/team01.bpmn — BPMN 2.0 workflow definition file; the actual business process that the Activiti engine executes and routes tasks through.

• SpringBootDemoActivitiApplication (Spring Boot, Activiti) — Main entry point; bootstraps Spring Boot context and Activiti engine
  • Failure mode: If main class fails to start, entire application is unavailable; check database connectivity and BPMN file syntax.
• SecurityConfiguration (Spring Security) — Configures Spring Security authentication providers, user details, and authorization rules for workflow access
  • Failure mode: If misconfigured, users cannot authenticate or access workflow tasks; resulting in 403 Forbidden or task assignment failures.
• SecurityUtil (Spring Security) — Extracts authenticated user from Spring Security context for task assignment and audit logging
  • Failure mode: If SecurityUtil returns null, task assignment fails; process instances may hang waiting for user assignment.
• Activiti ProcessEngine (Activiti) — Core workflow execution engine; manages process definitions, instances, tasks, and variable state
  • Failure mode: Engine initialization failure or database schema corruption prevents all workflow operations; startup fails.
• BPMN Process Definitions (team01.bpmn) (BPMN 2.0) — Declarative workflow definitions in BPMN XML; defines tasks, gateways, sequence flows, and user assignments
  • Failure mode: Invalid BPMN syntax or missing task assignments cause process to deadlock or fail at runtime.

• HTTP Client → Spring Boot Controller (implied) — Client submits workflow action (start process, claim task, complete task)
• Spring Boot Controller → SecurityUtil — Extract authenticated user identity from Spring Security context
• SecurityUtil → Activiti ProcessEngine — Pass user context to engine for task assignment and audit logging

Add a New BPMN Workflow Process

1. Create a new BPMN 2.0 XML file in src/main/resources/processes/ directory (demo-activiti/src/main/resources/processes/)
2. Define your process with tasks, gateways, and sequence flows using Activiti BPMN syntax (demo-activiti/src/main/resources/processes/your_process.bpmn)
3. Activiti auto-detects BPMN files on startup; no additional Java code needed to register the process definition

Integrate Custom User/Role Tasks

1. Update SecurityUtil.java to add custom methods that extract user roles and group memberships from Spring Security context (demo-activiti/src/main/java/com/xkcoding/activiti/util/SecurityUtil.java)
2. In your BPMN process, set task assignees using expressions like ${securityUtil.getCurrentUser()} (demo-activiti/src/main/resources/processes/team01.bpmn)
3. Ensure SecurityConfiguration.java defines user details and authority mappings (demo-activiti/src/main/java/com/xkcoding/activiti/config/SecurityConfiguration.java)

Configure Activiti Datasource & Engine

1. Edit application.yml to set datasource URL, username, password, and Activiti engine properties (demo-activiti/src/main/resources/application.yml)
2. Add JPA and Activiti specific configurations (e.g., activiti.database-schema-update, spring.jpa.hibernate.ddl-auto) (demo-activiti/src/main/resources/application.yml)
3. Spring Boot will auto-wire the Activiti ProcessEngine bean on application startup

• Activiti 6.x / 7.x — Industry-standard BPMN 2.0 workflow engine providing process definition, execution, task management, and audit trails for complex business workflows.
• Spring Boot 2.1.0 — Auto-configuration framework that simplifies Activiti setup, datasource management, security integration, and application lifecycle.
• Spring Security — Provides authentication, authorization, and user context extraction for assigning workflow tasks to authenticated users and enforcing role-based access.
• Relational Database (H2/MySQL/PostgreSQL) — Persists process instances, task definitions, and execution history; required for workflow state management and audit compliance.

• BPMN XML files deployed with application rather than dynamically uploaded

  • Why: Simplifies version control, testing, and ensures process definitions are code-reviewed before deployment.
  • Consequence: Process definitions require application restart to update; dynamic process versioning is not supported out-of-the-box.

• Single embedded Activiti engine per application instance

  • Why: Reduces deployment complexity and external service dependencies.
  • Consequence: Horizontal scaling requires load balancing and shared database; no dedicated workflow server for multi-tenant scenarios.

• User assignment via Spring Security principal and SecurityUtil extraction

  • Why: Integrates workflow with existing authentication system; reduces custom user management code.
  • Consequence: Workflow task assignment is tightly coupled to Spring Security; external LDAP/OAuth changes require SecurityUtil updates.

• Does not provide a workflow UI or task dashboard; this is a backend engine demo.
• Does not support multi-tenant process isolation at the engine level.
• Does not include clustering or distributed process execution without external coordination.
• Does not handle long-running async jobs with external callbacks; uses in-process task execution only.

Each demo module requires its own external service/database setup (MySQL for Activiti, Redis for caching demos, RabbitMQ for messaging). application.yml files hardcode localhost connection strings—running multiple demos simultaneously may cause port conflicts. Some older demos (Activiti 7.1.0.M2 is a milestone, not GA) may have compatibility issues with Java 9+. JPA and MyBatis demos may require schema initialization (Flyway demos show the pattern, but not all modules use it). Lombok annotation processor must be enabled in IDE (IntelliJ: Settings > Build > Compiler > Annotation Processors). Multi-datasource demos require careful ClassLoader/bean name management—see demo code for @Primary annotations.

• BPMN (Business Process Model and Notation) — Activiti demo uses .bpmn workflow files (demo-activiti/src/main/resources/processes/team01.bpmn); understanding BPMN XML structure is essential to extending workflow automation examples
• AOP (Aspect-Oriented Programming) + Cross-Cutting Concerns — Multiple demos use AOP for logging, rate limiting, and security; xkcoding explicitly mentions 'aopLog' for recording web requests and Zookeeper-based distributed locking via AOP
• Token Bucket Rate Limiting (Guava RateLimiter + Redis + Lua) — Project implements both single-machine rate limiting (Guava RateLimiter) and distributed rate limiting (Redis + Lua scripts); critical pattern for production systems at scale
• RBAC (Role-Based Access Control) — Demo-security and Activiti integration showcase dynamic RBAC permission checking; essential for understanding Spring Security configuration patterns used across multiple demos
• Message Queue Patterns (Producer/Consumer, Topic/Queue) — RabbitMQ and Kafka demos illustrate async messaging patterns central to distributed systems; understanding queue vs. topic semantics (RabbitMQ exchanges vs. Kafka partitions) is prerequisite
• ORM Query Patterns (N+1 problem, lazy loading, eager fetching) — Multiple ORM demos (JPA, MyBatis, MyBatis-Plus, BeetlSQL) demonstrate different fetch strategies; understanding these tradeoffs is critical for database performance optimization
• Spring Boot Actuator Endpoints & Micrometer Metrics — demo-actuator provides production monitoring; Micrometer integration for Elasticsearch 7.x demo shows how to export custom metrics to observability platforms

• spring-projects/spring-boot — Official Spring Boot repository; provides the framework foundation and latest releases that all 66 demos depend on
• alibaba/spring-cloud-alibaba — Complements this repo with Alibaba ecosystem integrations (Nacos, Sentinel, Seata); demos in xkcoding repo reference Dubbo which is part of this ecosystem
• thymeleaf/thymeleaf — Official Thymeleaf template engine repo; referenced in demo-template-engine and part of the Spring Boot templating stack demonstrated here
• mybatis/mybatis-3 — Core MyBatis framework used in demo-mybatis, demo-mybatis-plus, and common-mapper demos; essential for understanding ORM patterns shown
• spring-projects/spring-security — Official Spring Security repository; powers the RBAC authentication and authorization demonstrated in demo-security and Activiti security configs

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 demo-activiti workflow execution

The demo-activiti module only has a basic ApplicationTests class with no actual workflow testing. Given that this is a learning repo focused on Spring Boot + Activiti integration, contributors should add comprehensive integration tests that verify BPMN process execution, task creation, and process variables using the team01.bpmn file already present in the project.

• [ ] Extend SpringBootDemoActivitiApplicationTests.java with @SpringBootTest setup and embedded H2 database configuration
• [ ] Add test cases for BPMN process deployment verification in src/test/java/com/xkcoding/activiti/
• [ ] Create ProcessEngineTest class to verify team01.bpmn workflow: process start, task query, task completion, and variable handling
• [ ] Add test fixtures or test data setup for SecurityUtil integration with Activiti identity service

Create comprehensive README.md for demo-activiti module

While demo-actuator has a README.md file, demo-activiti lacks documentation explaining how to run the module, configure the database, understand the team01.bpmn workflow diagram, and use the SecurityConfiguration. This is critical for a learning-focused repository.

• [ ] Create demo-activiti/README.md with setup instructions (database configuration, Maven build steps)
• [ ] Document the team01.bpmn process flow and explain how SecurityUtil.java integrates with Activiti
• [ ] Add example API usage or curl commands for triggering the workflow (if controller exists)
• [ ] Include troubleshooting section for common Activiti setup issues with Spring Boot

Add GitHub Actions workflow for running demo-activiti tests with MySQL service

The existing .github/workflows/maven.yml likely runs tests, but demo-activiti requires MySQL for Activiti table initialization. A dedicated workflow or service container configuration would ensure the activiti-spring-boot-starter can properly initialize schema during CI/CD.

• [ ] Extend .github/workflows/maven.yml to include MySQL 5.7+ service container for demo-activiti module tests
• [ ] Add database initialization SQL or Liquibase configuration to demo-activiti/src/main/resources/
• [ ] Verify spring.datasource properties in application.yml work with GitHub Actions MySQL container
• [ ] Add conditional build step to skip demo-activiti tests if MySQL service is unavailable (or make it required)

• Add integration tests to demo-activiti/src/test and demo-actuator/src/test directories (only SpringBootDemoActivitiApplicationTests.java exists as a template). Target: write 3-5 test cases per module covering the core @Configuration beans and REST endpoints.
• Document the 11 incomplete demos listed in TODO.md—create skeleton demo-<feature> directories with pom.xml templates and application.yml stubs for features like Apache Camel, Spring Cloud Config, and Micrometer. This unblocks contributors from implementing full versions.
• Add a comparison matrix to README.md showing which ORM (JPA/MyBatis/MyBatis-Plus/BeetlSQL) works best for use cases like batch inserts, complex joins, or read-only queries—extract this from existing demo-jpa, demo-mybatis, demo-mybatis-plus modules' source code and README snippets.

The demo-activiti module has significant security concerns. The primary issues are: (1) use of an outdated, unsupported Activiti milestone version from 2019 without security patches, (2) unspecified MySQL connector version likely pointing to a vulnerable release, (3) lack of visible Spring Security configuration despite having SecurityConfiguration class, and (4) missing security headers configuration. The codebase appears to be a learning/demonstration project rather than production-ready code. Immediate action required: upgrade Activiti to stable release, pin MySQL driver version, implement Spring Security with proper headers, and conduct a full dependency vulnerability audit. The project should not be deployed to any environment handling sensitive data without comprehensive security hardening.

• High · Outdated Activiti Version — demo-activiti/pom.xml - activiti-spring-boot-starter dependency. The project uses Activiti 7.1.0.M2 (Milestone 2), which is a pre-release version from 2019. This version is no longer maintained and likely contains known security vulnerabilities. Milestone/beta releases should never be used in production as they lack security patches. Fix: Upgrade to the latest stable Activiti version (7.1.0 or later stable release). Review release notes for security patches. Consider using the officially maintained Alfresco Activiti releases.
• High · Vulnerable MySQL Connector Dependency — demo-activiti/pom.xml - mysql-connector-java dependency. The pom.xml includes mysql-connector-java without specifying a version. The parent POM version is not provided, making it impossible to determine which version of the MySQL connector is being used. Older versions contain multiple known CVEs (e.g., CVE-2021-2471, CVE-2021-2109). Fix: Explicitly specify a patched version of mysql-connector-java (8.0.33 or later). Consider migrating to mysql-connector-j (8.1.0+) which is the newer official driver. Review dependency management in parent POM.
• Medium · Missing Security Headers Configuration — demo-activiti/src/main/java/com/xkcoding/activiti/config/SecurityConfiguration.java. No security headers are configured in the visible Spring Boot configuration. The application appears to be a Spring Boot web application (spring-boot-starter-web) without explicit Spring Security configuration visible, potentially missing HSTS, CSP, X-Frame-Options, and other critical security headers. Fix: Implement Spring Security with proper security headers configuration. Add HttpHeaders configuration for HSTS, Content-Security-Policy, X-Content-Type-Options, X-Frame-Options, and X-XSS-Protection.
• Medium · Activiti Default Security Configuration — demo-activiti/src/main/java/com/xkcoding/activiti/config/SecurityConfiguration.java. Activiti 7.1.0.M2 has known security issues with its default configuration. The SecurityConfiguration class exists but its implementation is not visible. Activiti can be vulnerable to unauthorized workflow manipulation if not properly secured. Fix: Ensure Activiti REST API endpoints are properly secured with authentication and authorization. Implement role-based access control. Review Activiti security documentation for proper configuration.
• Medium · Unversioned Dependencies in Parent POM — demo-activiti/pom.xml - parent POM reference. The parent POM version reference is not shown. Spring Boot and other critical dependencies may not be pinned to specific versions, allowing transitive dependency vulnerabilities and unpredictable behavior. Fix: Ensure the parent POM (spring-boot-demo) explicitly versions all dependencies. Use dependency management to control transitive dependency versions. Run regular dependency audits with 'mvn dependency-check:check'.
• Low · Lombok Dependency Security Consideration — demo-activiti/pom.xml - lombok dependency. While Lombok is marked as optional, it is a compile-time annotation processor that modifies bytecode. Using older versions of Lombok can introduce security-relevant code generation issues. Fix: Keep Lombok updated to the latest version. Consider the security implications of annotation processors in your build pipeline. Review generated bytecode in security-critical code paths.

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.