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/changmingxie/tcc-transaction 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

• 5 active contributors
• Distributed ownership (top contributor 46% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago

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

What it runs against: a local clone of changmingxie/tcc-transaction — 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 changmingxie/tcc-transaction | 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-2.x exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 499 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "changmingxie/tcc-transaction(\\.git)?\\b" \\
  && ok "origin remote is changmingxie/tcc-transaction" \\
  || miss "origin remote is not changmingxie/tcc-transaction (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-2.x >/dev/null 2>&1 \\
  && ok "default branch master-2.x exists" \\
  || miss "default branch master-2.x no longer exists"

# 4. Critical files exist
test -f "tcc-transaction-api/src/main/java/org/mengyun/tcctransaction/api/Compensable.java" \\
  && ok "tcc-transaction-api/src/main/java/org/mengyun/tcctransaction/api/Compensable.java" \\
  || miss "missing critical file: tcc-transaction-api/src/main/java/org/mengyun/tcctransaction/api/Compensable.java"
test -f "tcc-transaction-api/src/main/java/org/mengyun/tcctransaction/api/TransactionContext.java" \\
  && ok "tcc-transaction-api/src/main/java/org/mengyun/tcctransaction/api/TransactionContext.java" \\
  || miss "missing critical file: tcc-transaction-api/src/main/java/org/mengyun/tcctransaction/api/TransactionContext.java"
test -f "tcc-transaction-api/src/main/java/org/mengyun/tcctransaction/api/Xid.java" \\
  && ok "tcc-transaction-api/src/main/java/org/mengyun/tcctransaction/api/Xid.java" \\
  || miss "missing critical file: tcc-transaction-api/src/main/java/org/mengyun/tcctransaction/api/Xid.java"
test -f "tcc-transaction-core/src/main/java/org/mengyun/tcctransaction/AbstractConfig.java" \\
  && ok "tcc-transaction-core/src/main/java/org/mengyun/tcctransaction/AbstractConfig.java" \\
  || miss "missing critical file: tcc-transaction-core/src/main/java/org/mengyun/tcctransaction/AbstractConfig.java"
test -f "tcc-transaction-core/src/main/java/org/mengyun/tcctransaction/ClientConfig.java" \\
  && ok "tcc-transaction-core/src/main/java/org/mengyun/tcctransaction/ClientConfig.java" \\
  || miss "missing critical file: tcc-transaction-core/src/main/java/org/mengyun/tcctransaction/ClientConfig.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 499 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~469d)"
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/changmingxie/tcc-transaction"
  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).

tcc-transaction is a Java-based distributed transaction framework implementing the TCC (Try-Confirm-Cancel) pattern for microservices. It solves the problem of maintaining data consistency across multiple databases when a single business operation spans multiple independent services—for example, a payment refund that must atomically debit multiple merchant accounts and credit a platform account. Multi-module Maven project: core TCC engine modules (not fully listed but implied by the pom.xml structure), a React-based admin dashboard at tcc-transaction-admin-web/ with Webpack config and Node.js tooling (package.json, package-lock.json), and documentation at doc/. The project bundles both the transaction framework and a web UI for monitoring/managing transactions.

Java backend engineers and architects building microservice systems who need to coordinate multi-database transactions without distributed locks or eventual consistency compromises. Specifically useful for fintech platforms, payment systems, and e-commerce backends that perform cross-service refunds, transfers, or settlements.

Production-ready. Currently at version 2.1.0 with active maintenance (GitHub Actions CI/CD pipeline present in .github/workflows/release.yml). The codebase is substantial (908KB Java) with a well-documented admin web dashboard (React-based frontend at tcc-transaction-admin-web/). However, the primary maintainer changmingxie appears to be the main driver, and commit recency data is not visible from the provided file list.

Moderate risk. Single maintainer (changmingxie) is a concentration risk for a production-critical library. The codebase's maturity and size suggest stability, but lack of visible recent commit dates or active issue tracking in the file list is concerning. No test files visible in the top 60 files suggests potential test coverage gaps. Heavy reliance on custom transaction management means bugs here directly impact financial operations.

Active release automation via .github/workflows/release.yml. The admin web interface is a React application using Jest testing and Webpack bundling (config/webpack.config.js, config/jest/). Documentation is being maintained (doc/tcc-transaction-dashboard.md exists). Version 2.x release notes reference improved features relative to 1.6.x branch.

Clone the repository, install Maven (Java 1.8+) and Node.js (for the admin web UI). Build the core: mvn clean install. For the admin web: cd tcc-transaction-admin-web && npm install && npm start (which uses the script defined in scripts/start.js and webpack dev server from config/webpackDevServer.config.js).

Daily commands: Core framework: mvn clean install from repo root. Admin web UI: cd tcc-transaction-admin-web && npm install && npm start (runs Webpack dev server on http://localhost:3000 by default, configured in scripts/start.js). Tests: npm test in tcc-transaction-admin-web (uses Jest with config/jest/).

• tcc-transaction-api/src/main/java/org/mengyun/tcctransaction/api/Compensable.java — Core annotation defining TCC transaction methods; every participant service method must use this to mark Try/Confirm/Cancel phases
• tcc-transaction-api/src/main/java/org/mengyun/tcctransaction/api/TransactionContext.java — Transaction context object carrying Xid and propagation metadata across distributed calls; essential for understanding transaction flow
• tcc-transaction-api/src/main/java/org/mengyun/tcctransaction/api/Xid.java — Global transaction identifier structure; required for correlation and logging across services
• tcc-transaction-core/src/main/java/org/mengyun/tcctransaction/AbstractConfig.java — Base configuration class for TCC runtime; defines transaction recovery, storage, and participant registry setup
• tcc-transaction-core/src/main/java/org/mengyun/tcctransaction/ClientConfig.java — Client-side TCC configuration; coordinates transaction management and interceptor registration for Try/Confirm/Cancel
• tcc-transaction-core/src/main/dbscripts/db.sql — Database schema for storing transaction and participant states; required for transaction recovery and state persistence
• pom.xml — Root Maven POM defining BOM and multi-module structure; entry point for understanding module dependencies and build lifecycle

Add a new TCC-enabled microservice method

1. Create a service class with three methods (try, confirm, cancel phases) (tcc-transaction-api/src/main/java/org/mengyun/tcctransaction/api/Compensable.java)
2. Annotate each method with @Compensable(confirmMethod='...', cancelMethod='...', transactionContextParameter=...) specifying phase and context parameter position (Your service class)
3. Accept TransactionContext as a parameter in try method to receive Xid and propagation details (tcc-transaction-api/src/main/java/org/mengyun/tcctransaction/api/TransactionContext.java)
4. Ensure confirm and cancel methods are idempotent by checking internal state or using a dedupe key (Your service class)
5. Enable TCC on your Spring boot application using @EnableTcc on configuration class (tcc-transaction-api/src/main/java/org/mengyun/tcctransaction/api/EnableTcc.java)

Add transaction recovery monitoring to the dashboard

1. Define new API endpoint in backend that queries TCC_TRANSACTION and TCC_PARTICIPANT from database schema (tcc-transaction-core/src/main/dbscripts/db.sql)
2. Add API client method in React to call the backend endpoint (tcc-transaction-admin-web/src/common/api.js)
3. Create new page component to display recovery metrics and list failed transactions (tcc-transaction-admin-web/src/pages/tcc/transaction/index.jsx)
4. Add route and menu link in layout to navigate to new monitoring page (tcc-transaction-admin-web/src/layout/TccLayout.jsx)

Implement a custom transaction storage backend

1. Extend AbstractConfig and override transaction storage/recovery methods (tcc-transaction-core/src/main/java/org/mengyun/tcctransaction/AbstractConfig.java)
2. Implement a TransactionRepository interface (not shown but inferred from core) to store/retrieve transaction state from your custom backend (e.g., Redis, DynamoDB) (Your repository implementation)
3. Register your custom repository bean in ClientConfig or Spring context (tcc-transaction-core/src/main/java/org/mengyun/tcctransaction/ClientConfig.java)
4. Ensure your implementation stores Xid, participant status, and transaction status as defined in the SQL schema for recovery compatibility (tcc-transaction-core/src/main/dbscripts/db.sql)

• Spring Framework + AOP — Declarative @Compensable annotation and method interception enable transparent TCC instrumentation without modifying business logic
• Relational Database (SQL schema) — ACID guarantees and recovery log durability are essential for transaction state persistence and replay after failure
• React + Redux — Rich admin dashboard for monitoring transaction states, manual recovery, and task queue inspection across distributed services
• Maven multi-module — Separates API contract (tcc-transaction-api) from core engine (tcc-transaction-core) and admin UI, allowing selective dependency and flexible deployment

• Two-phase commit with synchronous confirmation

  • Why: Guarantees strong consistency and immediate rollback on failure; matches the TCC pattern definition
  • Consequence: Long-running transactions block resources; not suitable for truly long-lived operations or high-latency remote calls; requires idempotency in confirm/cancel phases

• Annotation-based method marking (@Compensable) instead of explicit orchestration

  • Why: Simplifies developer experience and avoids boilerplate; achieves loose coupling between try/confirm/cancel
  • Consequence: Requires runtime bytecode instrumentation; harder to debug transaction flow; less explicit control over phase ordering

• Centralized transaction manager coordinating all participants

  • Why: Simplifies consistency guarantee and recovery logic; single decision point for confirm vs. cancel
  • Consequence: Introduces single point of failure for the TCC manager itself; scales poorly with very high transaction volumes; requires TCC manager high

The admin web UI (tcc-transaction-admin-web/) is a separate Node.js application from the core Java framework—both must be built/deployed separately. Idempotency is explicitly required for Confirm and Cancel operations (mentioned in README) but not enforced by the framework itself; implementers must ensure their business logic satisfies this constraint or face duplicate processing bugs. The framework coordinates across independent databases, so network failures during Confirm/Cancel phases require retry logic and observability that may not be obvious from initial usage. No explicit documentation visible on required database schema or table structure for the transaction log itself.

• TCC Pattern (Try-Confirm-Cancel) — This is the core transaction model implemented by the entire framework; understanding the three phases and their invariants (Try reserves resources, Confirm uses them, Cancel releases them) is fundamental to using this library correctly
• Idempotency (in distributed systems) — The README explicitly states Confirm and Cancel operations must be idempotent because retries may occur; this is a non-negotiable property of TCC implementations that users of this framework must guarantee in their business logic
• Two-Phase Commit (2PC) — TCC is a form of distributed 2PC; understanding the voting phase (Try) and commit phase (Confirm/Cancel) helps explain why TCC requires explicit callback methods rather than implicit locking
• Eventual Consistency vs. Strong Consistency — This framework provides strong consistency guarantees across services (no final-state divergence), unlike eventual consistency approaches; critical for understanding when to use TCC vs. alternatives like event sourcing
• Activity Manager / Saga Orchestrator — The framework contains a central activity manager component (not visible in top files but mentioned in README) that coordinates all service Try calls and decides whether to invoke Confirm or Cancel; understanding this as the transaction coordinator is essential
• Resource Reservation Pattern — Try phase in TCC pre-allocates and freezes resources (e.g., freezing merchant account balance) to ensure Confirm will succeed; this prevents the 'dirty reads' that plague eventual consistency systems
• Retry and Timeout Handling — Because Confirm/Cancel operations may fail due to network issues, the framework needs built-in retry capability with exponential backoff; the README mentions this requirement explicitly but implementation details are key to avoiding lost transactions

• seata/seata — Alternative distributed transaction framework in Java supporting AT (auto-commit) and TCC modes; most direct competitor in the same ecosystem
• apache/camel — Integration framework often used alongside TCC for orchestrating multi-service transactions and event-driven workflows in microservices
• alibaba/canal — Companion tool for capturing database change streams; commonly used with TCC frameworks to detect and recover from failed transaction states
• dtm-labs/dtm — Newer distributed transaction manager written in Go; shows alternative TCC implementation patterns and comparison point for protocol design
• changmingxie/spring-cloud-rest-tcc — Official example project by the same author demonstrating REST-based TCC integration patterns with Spring Cloud

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 tcc-transaction-admin-web API endpoints

The admin web frontend has API integration files (src/common/api.js, src/common/http.js) but there are no visible test files beyond App.test.js. The package.json indicates Jest is configured but API endpoints lack test coverage. This would ensure the dashboard communication with the backend is reliable.

• [ ] Create src/common/tests/api.test.js to test API endpoint construction and parameter handling
• [ ] Create src/common/tests/http.test.js to mock HTTP requests and test error handling scenarios
• [ ] Add test cases for transaction search, task management, and domain registry API calls referenced in src/pages/tcc/**/index.jsx files
• [ ] Update package.json test script if needed to include coverage reporting

Add GitHub Actions workflow for Node.js frontend build and test validation

The repo has a release.yml workflow but no CI pipeline for the tcc-transaction-admin-web frontend. Given the complex webpack config and React build setup, automating frontend build validation on PRs would catch configuration issues early and ensure the dashboard remains buildable.

• [ ] Create .github/workflows/frontend-ci.yml to run on pull requests targeting main/master
• [ ] Add steps to install dependencies (npm ci in tcc-transaction-admin-web/), run npm test, and npm run build
• [ ] Configure Node.js version matrix (14.x, 16.x, 18.x) to test across LTS versions
• [ ] Add artifact upload for build output to catch webpack errors and bundle size regressions

Add comprehensive documentation for admin dashboard configuration and deployment

The doc/ folder has dashboard markdown (tcc-transaction-dashboard.md) but deployment and configuration details are sparse. The config/ folder has env.js, webpack.config.js, and webpackDevServer.config.js but no documentation explaining environment setup, API endpoint configuration, or deployment procedures for the admin web.

• [ ] Expand doc/tcc-transaction-dashboard.md with sections on environment configuration (env.js usage, required environment variables)
• [ ] Document the build process: create doc/ADMIN_WEB_DEPLOYMENT.md explaining npm scripts (start, build, test) and webpack configuration
• [ ] Add configuration examples showing how to point the frontend to different backend environments (dev, staging, prod)
• [ ] Document package.json dependencies and explain the purpose of key devDependencies related to React, webpack, and testing

• Add integration tests for the TCC flow using an in-memory database or H2; the top 60 files show no visible test suite structure, which is a gap for a financial transaction framework
• Document the transaction state machine with a state diagram in doc/ (the README explains Try-Confirm-Cancel but lacks formal state transition documentation for failed retries and timeout handling)
• Create a 'Getting Started' code example in the doc/ folder showing a minimal two-service refund scenario with complete Try/Confirm/Cancel method implementations (README has the concept but no runnable sample code path is visible)

• High · Incomplete Maven POM Configuration Snippet — pom.xml. The provided pom.xml file is truncated and incomplete. The maven-resources-plugin version property is cut off mid-value, making it impossible to perform a complete dependency vulnerability analysis. The full POM structure is needed to identify outdated or vulnerable dependencies. Fix: Provide the complete pom.xml file. After obtaining it, run 'mvn dependency-check:check' or use OWASP Dependency-Check to identify vulnerable dependencies. Update dependencies to their latest secure versions.
• High · Potential Hardcoded Configuration Exposure — tcc-transaction-admin-web/config/env.js, tcc-transaction-admin-web/src/common/constants.js. The project structure contains multiple configuration files including tcc-transaction-admin-web/config/env.js and tcc-transaction-admin-web/src/common/constants.js that may contain sensitive configuration data, API endpoints, or environment-specific values. These files could expose sensitive information if committed to version control. Fix: Never commit sensitive configuration to version control. Use environment variables for sensitive data. Implement .gitignore rules to exclude .env files, config files with secrets, and use a secrets management system (e.g., HashiCorp Vault, AWS Secrets Manager).
• High · Frontend API Communication Security Risk — tcc-transaction-admin-web/src/common/http.js, tcc-transaction-admin-web/src/common/api.js. The frontend application (tcc-transaction-admin-web/src/common/http.js) likely handles API calls. Without reviewing the actual implementation, there's a risk of insecure API communication, missing CSRF protection, or improper authentication token handling. Fix: Ensure all API calls use HTTPS/TLS. Implement CSRF token validation. Use secure, HTTP-only cookies for session tokens. Validate and sanitize all API responses. Implement proper authentication and authorization checks.
• Medium · Potential XSS Vulnerability in React Components — tcc-transaction-admin-web/src/pages/tcc/transaction/SearchBox.jsx, tcc-transaction-admin-web/src/pages/tcc/transaction/TableCard.jsx. The React components in tcc-transaction-admin-web/src/pages may render dynamic content. If data binding is improper, XSS attacks are possible, particularly in TableCard.jsx and SearchBox.jsx which likely process user input or dynamic data. Fix: Avoid using dangerouslySetInnerHTML. Use React's built-in JSX escaping for dynamic content. Implement Content Security Policy (CSP) headers. Validate and sanitize all user inputs before rendering. Use a library like DOMPurify for HTML sanitization if needed.
• Medium · Insecure Direct Object References (IDOR) Risk — tcc-transaction-admin-web/src/pages/tcc/, API endpoints handling transactions and tasks. The TCC transaction management system (based on the file structure showing transaction, task, domain management pages) may be vulnerable to IDOR attacks if object IDs are not properly validated or if authorization checks are missing. Fix: Implement proper authorization checks for all resource access. Validate that users can only access their own resources. Use UUIDs instead of sequential IDs where possible. Implement role-based access control (RBAC) or attribute-based access control (ABAC).
• Medium · Missing Security Headers Configuration — tcc-transaction-admin-web/config/webpackDevServer.config.js, tcc-transaction-admin-web/config/webpack.config.js. The webpack and development server configuration files (config/webpack.config.js, config/webpackDevServer.config.js) do not appear to include security headers like Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, or Strict-Transport-Security. Fix: Configure security headers in the web server or application. Add CSP, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Strict-Transport-Security: max-age=31536000; includeSubDomains. Consider using helmet.js for Express servers.
• Medium · Package Lock File and Dependency Management — undefined. The package-lock.json file contains locked dependencies for the Node.js frontend. Without access to the Fix: undefined

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.