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/jetlinks/jetlinks-community 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

• Last commit 3w ago
• 7 active contributors
• Apache-2.0 licensed
• CI configured
• ⚠ Single-maintainer risk — top contributor 81% of recent commits
• ⚠ No test directory detected

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

What it runs against: a local clone of jetlinks/jetlinks-community — 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 jetlinks/jetlinks-community | 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 2.11 exists | Catches branch renames | | 4 | Last commit ≤ 50 days ago | Catches sudden abandonment since generation |

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

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

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 50 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~20d)"
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/jetlinks/jetlinks-community"
  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).

JetLinks is a fully reactive, enterprise-grade IoT platform built on Spring Boot 3.x, WebFlux, Netty, Vert.x, and Reactor. It provides unified device connection management across multiple protocols (TCP, MQTT, UDP, CoAP, HTTP), standardized physical model management, real-time data processing, device alarming, and rules-engine-driven automation—enabling rapid IoT system deployment without managing low-level network complexity. Modular monorepo organized as jetlinks-components/ containing common-component/ (base utilities, auth, buffer management) and upstream modules. Root pom.xml coordinates version 2.11.0-SNAPSHOT dependencies. Docker Compose files in docker/ and docker/dev-env/ define local PostgreSQL, Redis, and other service stacks for development. GitHub Actions in .github/workflows/ automate Maven builds for Java 17 and 2.1.x branches.

IoT system architects and backend engineers who need to ingest, manage, and process data from heterogeneous devices at scale. Companies building smart city, industrial IoT, or connected device platforms who want a self-hosted, fully open-source alternative to closed proprietary platforms.

Actively developed and production-ready. Version 2.11.0 is in SNAPSHOT; the project has multiple QQ community groups (647954464 is active), CI/CD workflows (GitHub Actions), and targets Java 17 + Spring Boot 3.4.x indicating modern maintenance. However, this is a community-maintained project (not corporate-backed) with significant technical complexity.

High architectural complexity: it depends on reactive stacks (Reactor, WebFlux, R2DBC), Netty, Vert.x, and optional services (Redis, TimescaleDB, Elasticsearch, TDengine). No visible test coverage metrics in the file list; breaking changes are possible across minor versions given the reactive paradigm shift in Spring Boot 3.x. Single-maintainer risk is moderate—verify before production deployments by checking issue response times and PR merge velocity.

The codebase is on Spring Boot 3.4.x with Java 17 (see maven.yml and pom.xml). Multiple CI pipelines test both current and 2.1.x versions. The SNAPSHOT suffix indicates active development toward version 2.11.0. Common utilities like buffer eviction, auth specs, and property metadata constants are being refined, but specific recent PR or issue activity is not visible in the file list provided.

git clone https://github.com/jetlinks/jetlinks-community.git
cd jetlinks-community
mvn clean install -DskipTests
# Start dependent services (see docker/dev-env/docker-compose.yml)
cd docker/dev-env && docker-compose up -d
# Run the application via IDE run configuration or:
mvn spring-boot:run -pl jetlinks-manager-server

Daily commands:

# Ensure Java 17+, PostgreSQL, Redis running (use docker-compose)
mvn clean package -DskipTests
java -jar jetlinks-manager-server/target/jetlinks-manager-server-2.11.0-SNAPSHOT.jar
# Or via Maven:
mvn spring-boot:run -pl jetlinks-manager-server

Access UI at http://localhost:8080 (exact port/path varies—check README).

• jetlinks-components/common-component/pom.xml: Declares core dependencies (jetlinks-core, jetlinks-supports, hsweb, Reactor, Netty) and version properties that cascade to all submodules.
• jetlinks-components/common-component/src/main/java/org/jetlinks/community/authorize/: Houses authentication specs and RBAC dimension types—critical for securing multi-tenant IoT deployments.
• jetlinks-components/common-component/src/main/java/org/jetlinks/community/buffer/BufferEviction.java: Defines memory/buffer management strategy; essential for handling high-throughput device message streams without OOM.
• docker/dev-env/docker-compose.yml: Specifies local PostgreSQL, Redis, and other service containers required to run the platform locally.
• .github/workflows/maven.yml: CI/CD pipeline that validates builds against Java 17 and Spring Boot 3.4.x—essential reference for local compatibility.
• jetlinks-components/common-component/src/main/java/org/jetlinks/community/PropertyMetadataConstants.java: Constants for unified device property metadata model—core to the 'unified device abstraction' feature.

For protocol adapters: Create a new class under a device-protocol-* module extending the protocol factory from jetlinks-core. For rules/workflows: Edit rule definitions in the rule-engine module; logic flows through reactor-ql. For auth/permissions: Modify classes in jetlinks-components/common-component/src/main/java/org/jetlinks/community/authorize/. For UI/API: The API layer is in a separate front-end repo (not shown here); backend REST endpoints are Spring WebFlux @RestController classes. For buffers/eviction: Extend AbstractBufferEviction in jetlinks-components/common-component/src/main/java/org/jetlinks/community/buffer/.

Java 17+ required: Not compatible with Java 11 or earlier (Spring Boot 3.4.x enforces this). Reactive learning curve: Heavy use of Project Reactor; non-blocking code is mandatory, blocking calls will break everything. PostgreSQL dialect: R2DBC defaults to PostgreSQL; switching databases requires careful driver and SQL dialect changes. Service dependencies: Redis and TimescaleDB must be running before starting the platform; Docker Compose is provided but must be explicitly started. SNAPSHOT versions in pom.xml: Version 2.11.0-SNAPSHOT may have unstable APIs—lock dependencies or use released versions for production. Configuration: Spring Boot properties are not shown in the file list; check application.yml or application-dev.properties in source root (not listed).

• Reactive Streams (Project Reactor, WebFlux) — JetLinks is built entirely on async, non-blocking I/O via Reactor Mono/Flux; understanding publishers, subscribers, and backpressure is mandatory to modify or extend this platform without deadlocks or memory leaks.
• Unified Device Model (Physical Model Abstraction) — JetLinks abstracts heterogeneous IoT devices (from different vendors, using different protocols) into a single property/event/command model; this is the core value proposition and explains why PropertyMetadataConstants and device-protocol adapters are central.
• Protocol Adapters (TCP, MQTT, CoAP, HTTP) — Multiple network protocol handlers feed into a unified message pipeline; understanding the adapter pattern here is essential for adding new device types or protocol support.
• R2DBC (Reactive Relational Database Connectivity) — Non-blocking database driver used instead of JDBC; essential to understand why JetLinks avoids thread-per-request models and scales horizontally.
• Rule Engine (Event-Driven Automation) — Alarms, scene automation, and data forwarding are all driven by rules; the reactor-ql dependency (visible in pom.xml) suggests rule evaluation happens in streaming pipelines, not batch jobs.
• Multi-Tenant RBAC (Role-Based Access Control with Org Dimensions) — JetLinks supports enterprise multi-tenancy; OrgDimensionType and AuthenticationSpec enable fine-grained data permission control across organizations and users—critical for SaaS deployments.
• Time-Series Data Storage (TimescaleDB, TDengine, Elasticsearch) — IoT platforms generate massive volumes of device telemetry; pluggable time-series backends (optional in the architecture) enable long-term analytics and high-cardinality metric storage.

• thingsboard/thingsboard — Direct competitor in the open-source IoT platform space; offers similar multi-protocol device management and rule engines but with different architecture (non-reactive, Java 8+).
• apache/streampipes — Apache IoT data ingestion and processing platform; complementary for visual rule building and data pipelining if JetLinks handles device connectivity.
• jetlinks/jetlinks-core — Core library that JetLinks Community depends on (imported as jetlinks-core and jetlinks-supports in pom.xml); contains the fundamental device abstraction and protocol interfaces.
• hs-web/hsweb-framework — Backend framework dependency (hsweb-starter, hsweb-authorization-api in pom.xml); provides the RBAC and data permission infrastructure JetLinks builds upon.
• jetlinks/jetlinks-ui-vue — Official Vue.js frontend for JetLinks Community; where web dashboard and device management UIs are implemented (separate repo from this one).

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 unit tests for buffer eviction strategies in jetlinks-components/common-component

The buffer component has multiple eviction strategies (DiskFreeEviction, DiskUsageEviction, SizeLimitEviction) but no visible test coverage in the file structure. Given this is a core IoT platform handling data buffering and persistence, these eviction policies are critical for production stability. New tests would validate edge cases like disk space thresholds, concurrent buffer access, and memory pressure scenarios.

• [ ] Create src/test/java/org/jetlinks/community/buffer/ directory
• [ ] Write DiskFreeEvictionTest covering low-disk scenarios and eviction triggers
• [ ] Write SizeLimitEvictionTest covering buffer size limits and overflow handling
• [ ] Write BufferSettingsTest covering configuration parsing and validation
• [ ] Add integration test for PersistenceBuffer under concurrent read/write operations

Add GitHub Actions workflow to validate protocol adapter compatibility across multiple Java versions

The repo supports multiple protocols (TCP, MQTT, UDP, CoAP, HTTP) and uses reactive frameworks (Netty, Vert.x, Reactor). Currently, workflows exist for maven.yml and pull_request.yml, but there's no explicit multi-version Java validation. Adding a dedicated workflow would catch Java 11/17/21 compatibility issues early, especially important for edge devices that may have different JVM versions.

• [ ] Create .github/workflows/java-compatibility.yml workflow file
• [ ] Configure matrix strategy to test against Java 11, 17, and 21 LTS versions
• [ ] Add protocol-specific module build steps (jetlinks-components modules)
• [ ] Include reactor-ql compilation validation for reactive pipeline compatibility
• [ ] Add artifacts upload for any compatibility reports or warnings

Create documentation and example implementations for the command support framework in common-component

The codebase contains command infrastructure (CrudCommandSupport, CommandSupportManagerProvider, InternalSdkServices) but lacks visible documentation on how to implement custom commands. This is critical for contributors wanting to extend device protocol adapters or add custom operations. Providing concrete examples would lower the barrier to entry.

• [ ] Create docs/COMMAND_FRAMEWORK.md documenting CommandSupportManagerProvider lifecycle
• [ ] Add example implementation in docs/examples/CustomCommandAdapter.java showing how to register custom device commands
• [ ] Document the relationship between DynamicOperationType and Operation interfaces
• [ ] Create docs/examples/ProtocolCommandIntegration.md with MQTT/TCP protocol command examples
• [ ] Add troubleshooting guide for common command registration and execution issues

• Add integration tests for AbstractBufferEviction subclasses. The jetlinks-components/common-component/src/main/java/org/jetlinks/community/buffer/ package lacks unit test coverage visible in the file list; writing Reactor-based tests for eviction strategies would improve reliability.
• Document the protocol adapter pattern with a worked example. The jetlinks-core dependency is imported but no example custom protocol handler is visible in jetlinks-components/; creating a sample TCP adapter implementation and guide would lower barriers for contributors.
• Add missing Authorization constants documentation. AuthenticationSpec.java and OrgDimensionType.java in jetlinks-components/common-component/src/main/java/org/jetlinks/community/authorize/ have no JavaDoc; annotating these with examples would clarify multi-tenant RBAC usage.

• High · Incomplete Dependency Declaration — jetlinks-components/common-component/pom.xml. The pom.xml file contains a truncated dependency for 'h2-' (H2 Database) with no version specified. This incomplete dependency declaration could lead to version resolution issues and potentially use outdated or vulnerable versions of H2 database driver. Fix: Complete the dependency declaration with a specific version number. Example: <version>2.2.224</version> or later. Ensure the version is not known to have security vulnerabilities.
• High · Use of FST Serialization Library — jetlinks-components/common-component/pom.xml. The codebase includes 'fst' (Fast Serialization) dependency (de.ruedigermoeller:fst). FST has known deserialization vulnerabilities and is not actively maintained. Arbitrary code execution is possible through malicious serialized objects. Fix: Replace FST with actively maintained serialization libraries such as Kryo (with security configurations), or use Java's standard serialization with additional validation. If FST must be used, implement strict object input validation and use a serialization filter.
• High · Potential Unsafe Serialization in Custom Codec — jetlinks-components/common-component/src/main/java/org/jetlinks/community/codec/. The presence of 'ObjectSerializer.java' and 'Serializers.java' in the codec package, combined with FST dependency, suggests custom serialization logic. Without seeing the implementation, there's a risk of unsafe deserialization patterns that could lead to RCE. Fix: Implement strict input validation for all deserialization operations. Use serialization filters (JEP 290). Consider using safer alternatives like JSON with schema validation instead of binary serialization for untrusted data sources.
• Medium · Missing Version Constraint Information — jetlinks-components/common-component/pom.xml. The pom.xml file is truncated and doesn't show the complete dependency list or version management strategy. Critical dependencies like spring-webflux, jetlinks-core, and reactor-ql lack visible version pins, which could lead to transitive dependency vulnerabilities. Fix: Implement a comprehensive dependencyManagement section in the parent POM. Pin all direct and critical transitive dependencies to specific versions. Use tools like Maven Dependency Check or OWASP Dependency-Check to identify vulnerable dependencies regularly.
• Medium · Reactive Framework Security Considerations — jetlinks-components/common-component/src/main/java/org/jetlinks/community/buffer/. The project uses reactive frameworks (Spring WebFlux, Reactor, Netty, Vert.x) which are powerful but require careful security implementation. Common issues include improper timeout configuration, unbounded request handling, and buffer overflow risks. Fix: Implement proper timeout configurations for all reactive operations. Set maximum buffer sizes and request limits. Review BufferSettings and buffer eviction policies to prevent DoS attacks. Add rate limiting and backpressure handling.
• Medium · IoT Protocol Handler Security — jetlinks-components/common-component/ (inferred from description). The platform supports multiple protocols (TCP, MQTT, UDP, CoAP, HTTP) with protocol adaptation logic. These network handlers could be vulnerable to injection attacks, protocol-specific exploits, or malformed packet handling. Fix: Implement strict input validation for all protocol handlers. Use allowlists for acceptable commands and packet structures. Implement rate limiting per protocol and per device. Add comprehensive logging for security-relevant events.
• Medium · Authorization Framework Integration — jetlinks-components/common-component/src/main/java/org/jetlinks/community/authorize/. The project uses hsweb-authorization-api and implements custom authorization specs. The 'OrgDimensionType' and authorization handling could have authorization bypass vulnerabilities if not properly implemented. Fix: Ensure all authorization checks use the framework consistently. Implement comprehensive unit tests for authorization logic. Use annotation-based authorization (@Secured) on all sensitive operations. Conduct regular security audits of authorization implementation.
• Medium · Command Execution Handler Security — undefined. The codebase includes command handlers (CrudCommandHandler, SaveCommandHandler, DeleteCommandHandler, QueryCommandHandler) that process dynamic commands. These could be vulnerable to command injection if user input is not 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.