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/alibaba/COLA 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 — Slowing — last commit 11mo ago

• Last commit 11mo ago
• 14 active contributors
• Distributed ownership (top contributor 28% of recent commits)
• LGPL-2.1 licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 11mo ago
• ⚠ LGPL-2.1 is copyleft — check downstream compatibility

_{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 alibaba/COLA repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/alibaba/COLA.

What it runs against: a local clone of alibaba/COLA — 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 alibaba/COLA | Confirms the artifact applies here, not a fork | | 2 | License is still LGPL-2.1 | 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 ≤ 363 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(LGPL-2\\.1)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"LGPL-2\\.1\"" package.json 2>/dev/null) \\
  && ok "license is LGPL-2.1" \\
  || miss "license drift — was LGPL-2.1 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 "cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/pom.xml" \\
  && ok "cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/pom.xml" \\
  || miss "missing critical file: cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/pom.xml"
test -f "cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/Application.java" \\
  && ok "cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/Application.java" \\
  || miss "missing critical file: cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/Application.java"
test -f "cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/application/ChargeServiceI.java" \\
  && ok "cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/application/ChargeServiceI.java" \\
  || miss "missing critical file: cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/application/ChargeServiceI.java"
test -f "cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/domain/charge/chargerule/ChargeRule.java" \\
  && ok "cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/domain/charge/chargerule/ChargeRule.java" \\
  || miss "missing critical file: cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/domain/charge/chargerule/ChargeRule.java"
test -f "cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/domain/gateway/AccountGateway.java" \\
  && ok "cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/domain/gateway/AccountGateway.java" \\
  || miss "missing critical file: cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/domain/gateway/AccountGateway.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 363 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~333d)"
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/alibaba/COLA"
  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).

COLA (Clean Object-Oriented & Layered Architecture) is a Java architectural framework that provides battle-tested patterns and Maven archetypes for building enterprise applications with clean separation of concerns. It defines a standardized four-layer structure (adapter, application, domain, infrastructure) and ships with cola-archetype-light as a ready-to-use project scaffold, eliminating boilerplate and enforcing architectural discipline across teams. Monorepo structure: cola-archetypes/ contains Maven archetype definitions (cola-archetype-light is the reference implementation); archetype-resources/ provides the template project structure with domain/, application/, adapter/, and infrastructure/ packages following DDD principles. The archetype generates a working Spring Boot application with pre-built ChargeService example.

Java backend engineers and architects at scale who need to structure domain-driven design applications without ad-hoc layering decisions; teams building Alibaba-style microservices who want guaranteed consistency across repositories; developers coming from messy Spring Boot projects seeking battle-tested architectural guardrails.

Highly mature and production-grade: COLA has reached v5 (5.x-SNAPSHOT in pom.xml), is actively maintained by Alibaba, supports Java 17+, has CI/CD via GitHub Actions (fast CI and multiply-java-versions CI), and is published to Maven Central. Significant community adoption indicated by GitHub stars and dependents-repo badge.

Low risk: minimal external dependencies (mainly Maven-managed), strong company backing (Alibaba), active CI/CD pipeline testing multiple Java versions, and LGPL-2.1 licensing. Only risk: archetype-based approach means breaking changes to cola-archetype-light would require regenerating projects, and the framework assumes team discipline to follow the architecture.

Active development on v5 (SNAPSHOT builds), with CI workflows validating against multiple Java versions (Java 17+), dependabot.yml indicating dependency updates are being managed, and the archetype continuously refined. The cola-component-dto library is published to Maven Central, indicating ongoing releases.

git clone https://github.com/alibaba/COLA.git && cd COLA && mvn clean install && mvn archetype:generate -DarchetypeGroupId=com.alibaba.cola -DarchetypeArtifactId=cola-archetype-light

Daily commands: After generating from archetype: mvn clean spring-boot:run (Application.java is the Spring Boot entry point); or mvn test to run the bundled tests for ChargeService and domain entities.

• cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/pom.xml — Root Maven configuration defining project structure, dependencies, and build plugins for COLA light archetype projects
• cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/Application.java — Entry point for COLA applications; initializes Spring Boot and defines the main application configuration
• cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/application/ChargeServiceI.java — Core application service interface demonstrating COLA's layered architecture pattern for business operations
• cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/domain/charge/chargerule/ChargeRule.java — Domain-level abstraction for charge calculation rules; demonstrates domain-driven design patterns central to COLA
• cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/domain/gateway/AccountGateway.java — Gateway interface defining contract between domain and infrastructure layers; critical for COLA's dependency inversion pattern
• cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/adapter/ChargeController.java — REST adapter layer demonstrating how external requests are translated into domain operations following COLA patterns

Add a New Charge Plan Type

1. Create a new ChargePlan subclass in domain/charge/chargeplan/ directory (cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/domain/charge/chargeplan/BasicChargePlan.java)
2. Add corresponding ChargeRule implementation in domain/charge/chargerule/ directory (cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/domain/charge/chargerule/BasicChargeRule.java)
3. Register new plan type in ChargeRuleFactory.getChargeRule() method (cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/domain/charge/chargerule/ChargeRuleFactory.java)
4. Create unit tests in test/domain/ verifying plan calculation logic (cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/test/java/domain/ChargeRecordPlanTest.java)

Add a New API Endpoint

1. Create request/response DTOs in application/dto/ directory for new operation (cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/application/dto/ChargeRequest.java)
2. Add new method to ChargeServiceI interface and implement in ChargeServiceImpl (cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/application/ChargeServiceI.java)
3. Create @RestController endpoint in adapter/ChargeController.java calling the service method (cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/adapter/ChargeController.java)
4. Add integration tests in test/application/ChargeServiceTest.java (cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/test/java/application/ChargeServiceTest.java)

Add Infrastructure Gateway Implementation

1. Define gateway interface in domain/gateway/ directory (cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/domain/gateway/AccountGateway.java)
2. Create concrete implementation in infrastructure/ directory extending gateway contract (cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/infrastructure/AccountGatewayImpl.java)
3. Configure implementation as Spring Bean in Application.java or config class (cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/Application.java)
4. Create infrastructure tests with WireMock mocks in test/infrastructure/ (cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/test/java/infrastructure/WireMockBasicTest.java)

1. Archetype generation idempotency: regenerating from the same archetype with different parameters can cause file conflicts; handle via clean directories. 2) Java 17+ is required (per badge in README) — projects using Java 8-16 will fail at compile-time. 3) The archetype template uses Spring Boot conventions (Application.java with @SpringBootApplication) but Spring Boot version is inherited from parent POM (check cola-framework-archetypes-parent). 4) DDD discipline is assumed — the architecture is only effective if domain logic stays in domain/ and doesn't leak into application/ or adapter/.

• Domain-Driven Design (DDD) — COLA's entire structure is built around DDD principles — the domain/ layer must contain rich entity and value object logic, not just data; understanding ubiquitous language and aggregates is essential to using COLA correctly.
• Hexagonal Architecture (Ports & Adapters) — COLA's four-layer model (adapter ↔ application ↔ domain ↔ infrastructure) is a realization of hexagonal architecture; the adapter layer represents ports, allowing domain logic to remain technology-agnostic.
• Value Objects vs Entities — COLA distinguishes entities (like ChargeRecord with identity) from value objects (like Money); understanding this boundary prevents treating Money as a primitive and losing domain semantics.
• Application Service Pattern — ChargeServiceImpl exemplifies the application service layer that orchestrates domain logic without exposing it; this is the orchestration boundary that prevents domain logic from leaking into adapters.
• Maven Archetype — COLA distributes via Maven archetypes (not libraries), meaning projects are scaffolded once then evolve independently; understanding how archetypes work (archetype-metadata.xml, archetype-resources/) is essential to extending COLA.
• Data Transfer Objects (DTOs) — COLA's adapter layer uses explicit DTOs (ChargeRequest, ChargeRecordDto) to decouple API contracts from domain models; this prevents domain entities from becoming service contracts and enables schema evolution.
• Layered Architecture (N-tier) — COLA's four-layer structure (adapter, application, domain, infrastructure) is a disciplined take on N-tier architecture that enforces unidirectional dependency rules: adapter calls application, application calls domain, domain is pure business logic.

• alibaba/arthas — Alibaba's Java diagnostic tool frequently used alongside COLA for runtime profiling and troubleshooting of layered applications in production.
• spring-projects/spring-boot — The underlying framework that COLA archetypes scaffold upon; COLA assumes Spring Boot conventions (Application.java, @SpringBootApplication, dependency injection).
• citerus/dddsample-core — Canonical DDD reference implementation in Java; COLA directly implements the layered architecture patterns established by DDDSample.
• alibaba/seata — Alibaba's distributed transaction framework that pairs naturally with COLA for coordinating transactions across layered, service-oriented architectures.
• apache/maven-archetype — The Maven plugin ecosystem that powers COLA's code-generation-via-archetype approach; understanding this enables customizing COLA archetypes.

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 comprehensive integration tests for cola-archetype-light template generation

The cola-archetype-light is a Maven archetype that generates new COLA projects, but there are no visible integration tests verifying that generated projects actually compile and run correctly. New contributors could add tests that invoke the archetype and validate the generated project structure, dependencies, and basic functionality. This is critical since archetype issues directly impact developer experience for all users creating new COLA projects.

• [ ] Create src/test/java directory in cola-archetype-light with archetype integration tests
• [ ] Add Maven Archetype Integration Test (AIT) in src/test/resources following Maven archetype testing conventions
• [ ] Verify generated Application.java, controllers, services, and domain entities compile without errors
• [ ] Add CI step in .github/workflows/ci.yaml to run archetype integration tests
• [ ] Document archetype testing approach in cola-archetypes/README.md

Add unit tests for domain layer charge calculation rules (chargerule package)

The domain/charge/chargerule directory contains multiple rule implementations (BasicChargeRule, FamilyChargeRule, FixedTimeChargeRule, CompositeChargeRule) and a ChargeRuleFactory, but no test files are visible in the provided structure. These are core business logic components that should have comprehensive unit test coverage demonstrating correct charge calculations for each plan type.

• [ ] Create src/test/java/domain/charge/chargerule directory in cola-archetype-light
• [ ] Add BasicChargeRuleTest with test cases for different call durations and rates
• [ ] Add FamilyChargeRuleTest verifying family member discount logic
• [ ] Add FixedTimeChargeRuleTest for fixed-time plan calculations
• [ ] Add CompositeChargeRuleTest validating rule composition and delegation
• [ ] Add ChargeRuleFactoryTest verifying correct rule creation by ChargePlanType

Add GitHub Actions workflow for validating archetype generation across multiple Java versions

While there's a ci_by_multiply_java_versions.yaml for the main build, there's no evidence of archetype-specific testing across Java versions. Since cola-archetype-light generates projects that should work on Java 17+, contributors should add a dedicated workflow that generates a sample project using the archetype on multiple Java versions (17, 21, etc.) and verifies it compiles and runs successfully.

• [ ] Create .github/workflows/archetype-generation-matrix.yaml
• [ ] Matrix test across Java 17, 21, and latest LTS versions
• [ ] Use mvn archetype:generate to create test projects from cola-archetype-light
• [ ] Run mvn clean compile and mvn clean test on generated projects
• [ ] Add workflow status badge to cola-archetypes/README.md
• [ ] Document archetype compatibility matrix in project documentation

• Add missing example in cola-archetype-light for infra layer: create a concrete Repository implementation (e.g., ChargeRecordRepository with JPA annotations) and persistence adapter, filling the gap between domain/charge entities and a real database. Files to create: src/main/java/infrastructure/repository/ChargeRecordRepositoryImpl.java
• Document the Money → MoneyConverter pattern: add JavaDoc and a conversion example test showing how to marshall domain value objects to/from database columns, since MoneyConverter.java exists but has no usage demonstrated in the archetype.
• Add Integration test template: create src/test/java/integration/ChargeServiceIntegrationTest.java showing how to test application services end-to-end with a real(or test) Spring context, since only unit tests are present.

The COLA archetype project has a reasonable security posture as a framework/template repository. The primary concerns are: (1) personal email exposure in POM metadata, (2) lack of visibility into actual dependency versions and potential vulnerabilities, (3) unverified security practices in generated code templates, and (4) potential credential exposure in test files. The project uses modern Java (17+), has automated CI/CD, and proper licensing, which are positive security indicators. No critical vulnerabilities were identified in the available configuration, but code-level analysis would be needed to assess the actual template implementations.

• Medium · Email Address Exposed in POM Configuration — cola-archetypes/cola-archetype-light/pom.xml (developers section). The developer's email address is displayed in plain text in the pom.xml file (25216348(at)qq.com). While obfuscated with '(at)', this is still a form of PII exposure in a public repository that could be harvested by automated tools. Fix: Consider using a generic email address or organization email instead of personal email. Alternatively, configure Maven to exclude sensitive developer information from public builds.
• Medium · Missing Dependency Version Management — cola-archetypes/cola-archetype-light/pom.xml. The pom.xml uses a snapshot version (5.x-SNAPSHOT) and relies on a parent POM for dependency management. The actual dependency versions are not visible in the provided content, which could lead to inconsistent or vulnerable transitive dependencies being pulled in. Fix: Implement explicit dependency version pinning and use dependency-check Maven plugin to scan for known vulnerabilities. Regularly audit transitive dependencies.
• Low · Archetype Template Security Not Verified — cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/. The maven-archetype packaging generates project templates that will be used to scaffold new projects. Without visibility into the actual template contents (Application.java, DTOs, etc.), it's unclear if security best practices are enforced in generated code patterns. Fix: Ensure generated templates include security best practices such as: input validation, output encoding, parameterized queries, authentication/authorization checks, and secure dependency declarations.
• Low · HTTP Configuration File Present — cola-archetypes/cola-archetype-light/src/test/charge.http. A charge.http test file is present in the repository. While test files are expected, HTTP requests stored in version control could accidentally expose credentials or sensitive endpoints. Fix: Ensure the charge.http file does not contain actual credentials, API keys, or production endpoint URLs. Use environment variables or separate configuration files for sensitive test data.
• Low · Missing Security Configuration in Generated Application — cola-archetypes/cola-archetype-light/src/main/resources/archetype-resources/src/main/java/. The archetype includes gateway implementations (AccountGatewayImpl, SessionGatewayImpl) and REST controllers but no visible security framework configuration (Spring Security, authentication filters, etc.) in the provided file structure. Fix: Ensure generated projects include pre-configured security frameworks. The archetype should enforce authentication, authorization, and HTTPS enforcement by default.

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.