iot-dc3/dc3/agents/backend.md

Backend conventions

Read this when changing Java modules, REST/gRPC contracts, or drivers. Entry point and cross-cutting rules: AGENTS.md.

Layering

Business modules follow this flow:

Controller (WebFlux) -> Service (BO) -> Reactive repository (R2DBC)

• Controllers implement the BaseController interface and return typed Mono<T>/Flux<T> payloads.
• Keep the request path non-blocking; use Reactor-native R2DBC publishers end to end.
• Services extend BaseService<B, Q>, work in business objects, and own business rules.
• Reactive repositories use DatabaseClient/R2dbcEntityTemplate and explicit tenant predicates.
• Do not expose persistence objects from controllers or facade contracts.

Common types:

Type	Module	Role
BaseService<B,Q>	dc3-common-public	base CRUD service contract
BaseController	dc3-common-web	reactive controller helpers and user/tenant context
RFC 9457 problem details	dc3-common-web	standard HTTP error body (application/problem+json)
BaseBO, BaseVO, BaseDTO	dc3-common-model	shared business, web, and transfer fields
BaseBuilder	dc3-common-model	MapStruct conversion base
TenantOwned	dc3-common-public	marker for tenant-scoped entities

Shared code placement

Place code according to ownership and dependency direction, not Java visibility. A public method is not automatically shared infrastructure.

• Put framework-neutral contracts, request/pagination/tree entities, tenant markers, and broadly reusable utilities in dc3-common-public.
• Put platform-wide constants and top-level shared domain/wire/persistence enums in dc3-common-constant.
• Put BO/VO/DTO bases, builders, validation groups, extensions, and shared transport models in dc3-common-model; those models may reference enums owned by dc3-common-constant.
• Keep framework- or capability-specific public helpers in the narrowest owning module, such as gRPC conversion in dc3-common-api, WebFlux helpers in dc3-common-web, and broker adapters in the dc3-mq-* family.
• Keep constants and nested enums used by only one module, protocol, configuration object, or implementation beside that owner. Reserve top-level *Constant classes and top-level public enums for dc3-common-constant; use a concern-specific local name such as *Limits/*Defaults, a nested enum, or a private field until the concept becomes a stable cross-module contract.
• Do not duplicate cross-module wire names, header names, routing identifiers, cache-key fragments, or persistence codes. Define one canonical symbol in dc3-common-constant and migrate callers together.
• Preserve the dependency floor: dc3-common-constant must not depend on other DC3 modules, and dc3-common-public must not depend on capability modules.

Tenant safety

Tenant isolation is a hard requirement.

• Preserve tenant scope in every new query and mutation.
• Carry tenant IDs through gRPC requests whenever the contract supports them.
• Include tenant context in cache keys for tenant-owned data.
• Validate ownership before returning or mutating data across service boundaries.
• Do not add tenantId IS NULL shortcuts unless the data model explicitly defines global records.
• Treat missing tenant validation as a correctness and security defect, not a convenience trade-off.

Facade boundaries

Business code must use facade interfaces for cross-service calls.

• Contracts belong in dc3-common-facade-api.
• Transport-backed implementations belong in dc3-common-facade-grpc.
• In-process implementations belong in the matching module: dc3-common-facade-local-auth, dc3-common-facade-local-data, or dc3-common-facade-local-manager.
• dc3-common-facade-local is a dependency aggregator and does not contain implementation sources.
• Keep controllers and services independent from transport details unless they are explicit transport adapters.

gRPC contracts

Proto files live under dc3-api/*/src/main/protobuf.

When changing a contract:

1. Update the .proto file.
2. Compile the affected API module to regenerate sources.
3. Update server implementations and client builders/stubs together.
4. Preserve backward compatibility where practical.
5. Verify tenant propagation and standard gRPC status errors.

Servers are Spring beans extending generated *ImplBase classes. Reuse shared stub configuration; do not construct ad hoc channels in business code.

Driver SDK

Drivers implement protocol behaviour through the SPI types in dc3-common-driver; shared runtime services handle registration, scheduling, and value dispatch.

Primary extension points are DriverProtocol, DriverLifecycle, DriverMetadataListener, DriverHealth, DeviceHealth, and DriverCommand. Prefer existing SDK plumbing over driver-specific infrastructure.

Driver application.yml metadata is user-facing:

• Keep name, attribute-name, and remark in English.
• Treat driver code values as routing-stable identifiers. Changing one requires a metadata and RabbitMQ migration plan.

CRUD verbs

CRUD-shaped names reflect result cardinality across Service, Controller, Facade, gRPC server, and proto RPCs:

Action	Java	HTTP	gRPC
create one	add(BO)	/add	n/a
delete by ID	delete(Long)	/delete	n/a
update one	update(BO)	/update	n/a
return one	getXxx(...)	/get_xxx	GetXxx
return many	listXxx(...)	/list_xxx	ListXxx

• Base CRUD comes from BaseService<B,Q>: add, delete, update, getById, and list(Q).
• Reserve select* for raw store persistence operations.
• Do not introduce find*, query*, or fetch* as primary CRUD verbs.
• HTTP paths are lowercase snake_case and mirror Java names.
• Use getStatusByPage(Q) for status maps and dispatchRead/dispatchWrite for command dispatch, following existing contracts.

Models and enums

• DOs model database storage; BOs model business semantics; VOs/DTOs model web or transport input/output.
• Persistent write paths accept BOs in services. Controllers and transport adapters convert VO/DTO input to BO.
• Read-only projections may return VOs directly when a duplicate BO would add no business meaning.
• Use MapStruct builders for VO/BO/DO conversion, including enum/index conversion.
• Do not leak database-coded Byte, Integer, or String flags when a domain enum exists or should exist.
• *FlagEnum is for boolean-like toggles, *StatusEnum for state machines, and *TypeEnum for classifications.
• Enum constants use descriptive UPPER_SNAKE_CASE; enum code values use lowercase tokens.
• Do not introduce magic flag constants such as private static final Byte DEFAULT = 1.
• Do not expose secrets in VOs. Exclude apiKey, password, secret, token, and credential fields from serialization and Lombok @ToString.

Web API and OpenAPI

• Controllers return typed payloads and never expose DOs; errors use RFC 9457 problem details.
• Apply grouped validation consistently and keep validation/exception messages in English.
• Document REST endpoints with springdoc annotations; do not maintain a parallel handwritten OpenAPI spec.
• Each business controller package needs the appropriate GroupedOpenApi bean, gateway aggregation route, and Swagger UI entry.
• Shared WebFlux/springdoc configuration belongs in dc3-common-web and must be registered through AutoConfiguration.imports when component scanning will not discover it.
• Docs are enabled in development-style profiles and disabled in production. Export a running stack with make openapi.

Configuration and logging

• Custom configuration-property prefixes use dc3.*.
• Prefer validated, typed @ConfigurationProperties over scattered @Value fields.
• YAML deployment values use ${ENV:default} placeholders.
• WebFlux base paths use spring.webflux.base-path, not server.servlet.context-path.
• Use English, stable event names and parameterized SLF4J messages.
• Prefer structured fields such as tenantId={}, userId={}, deviceId={}.
• Never log tokens, passwords, credentials, full request bodies, or raw private payloads at info level.
• Pass caught exceptions to warn/error logs unless stack-trace suppression is intentional.