TB CLAUDE.md

Project Overview

ThingsBoard is an open-source IoT platform. Java 17, Spring Boot 3.4, Maven multi-module project.

Build Commands

# Full build with tests skipped
mvn -T1C license:format clean install -DskipTests

# Build specific modules (also builds dependencies)
mvn -T2 license:format clean install -DskipTests --projects common/data,dao --also-make

# Build only protobuf-containing modules
./build_proto.sh

# Format license headers (required before commit — build will fail license:check otherwise)
mvn license:format

Running Tests

# Run a single test class
mvn test -pl dao -Dtest=DeviceServiceTest

# Run a single test method
mvn test -pl dao -Dtest=DeviceServiceTest#testFindDeviceById

Module Structure

Module	Purpose
common/	Shared libraries: data model, proto, actor system, queue, transport API, cache, DAO API, etc.
rule-engine/	Rule engine API (rule-engine-api) and built-in rule node implementations (rule-engine-components)
dao/	Data access layer — JPA (PostgreSQL) for entities, Cassandra/TimescaleDB for time-series
transport/	Protocol transports: mqtt, http, coap, lwm2m, snmp
application/	Main Spring Boot application — REST controllers, services, actor system wiring
ui-ngx/	Angular frontend
edqs/	Entity Data Query Service
msa/	Microservices architecture packaging

Architecture

Message Flow

Transport (MQTT/HTTP/CoAP/LwM2M/SNMP)
  → TransportService → encodes to TbMsg
  → Queue (Kafka or in-memory)
  → RuleChainActor → RuleNodeActor → TbNode.onMsg()
  → tellSuccess() / tellNext() / tellFailure() → next RuleNodeActor(s)
  → Services (Telemetry, Attributes, Alarm, RPC, etc.)
  → DAO Layer (JPA + Cassandra)
  → Database (PostgreSQL + Cassandra/TimescaleDB)

Actor System (common/actor/)

Custom actor framework (not Akka). Core interface: TbActor with process(TbActorMsg), init(TbActorCtx), destroy(). Managed by TbActorSystem which creates dispatchers (thread pools) and handles parent-child actor relationships. Actor IDs: TbEntityActorId, TbStringActorId.

Key Files

• Entity SQL schema: @dao/src/main/resources/sql/schema-entities.sql
• Main application config: application/src/main/resources/thingsboard.yml
• Proto definitions: common/proto/src/main/proto/

Conventions

• License headers are required on all source files. The license:check goal runs automatically during build. Run mvn license:format to auto-fix headers.
• After changing .proto files, rebuild with ./build_proto.sh or mvn compile on affected modules.