opik-backend

Opik Backend

Architecture

• Layered: Resource → Service → DAO (never skip layers)
• DI: Guice modules, constructor injection with @Inject
• Databases: MySQL (metadata, transactional) + ClickHouse (analytics, append-only)

Naming Conventions

Plural Names (Resources, Tests, URLs, DB Tables)

• Resource classes: TracesResource, SpansResource, DatasetsResource (not TraceResource)
• Resource test classes: TracesResourceTest, SpansResourceTest, DatasetsResourceTest (not TraceResourceTest)
• URL paths: /v1/private/traces, /v1/private/spans (not /v1/private/trace)
• DB table names: traces, spans, feedback_scores (not trace, span, feedback_score)

Singular Names (DAO, Service)

• DAO classes: TraceDAO, SpanDAO, DatasetDAO (not TracesDAO)
• Service classes: TraceService, SpanService, DatasetService (not TracesService)

// ✅ GOOD
@Path("/v1/private/traces")
public class TracesResource { }

// ✅ GOOD - DAO and Service use singular
public class TraceDAO { }
public class TraceService { }

// ✅ GOOD - test classes match plural resource name
public class TracesResourceTest { }

// ❌ BAD - singular test class
public class TraceResourceTest { }

// ❌ BAD - singular resource/URL
@Path("/v1/private/trace")
public class TraceResource { }

// ❌ BAD - plural DAO/Service
public class TracesDAO { }
public class TracesService { }

Lombok Conventions

Records and DTOs

• Always annotate records/DTOs with @Builder(toBuilder = true)
• Use builders (not constructors) when instantiating records
• For internal records (built programmatically, never validated by Bean Validation), use Lombok @NonNull on required fields — it generates a runtime null check at construction
• For request-body DTOs validated via @Valid cascade (Jakarta validators like @NotNull/@NotBlank/@Size), use Jakarta annotations only — do not stack @NonNull on top. Bean Validation already enforces the contract at the API boundary; doubling up is redundant noise