BoscaDeveloper Documentation

Architecture Overview

How the workspace organizes domain code, generates wiring, and connects applications to infrastructure.

Core/Impl Split

Backend domains generally separate contracts from implementations:

  • core-* modules define contracts: interfaces, models, and annotations. They publish to Maven so any module in any repository can depend on the contract without pulling in the implementation.
  • Implementation modules provide concrete classes: repositories backed by PostgreSQL, services with business logic, and GraphQL controllers.

When extending a domain, depend on another domain's core contracts and call its service interfaces. Keep SQL and persistence details in the module that owns the data.

KSP Code Generation

KSP (Kotlin Symbol Processing) generates dependency injection, database, GraphQL, route, and job wiring at compile time. Follow these patterns when adding code that must also run in GraalVM native images.

AnnotationWhat KSP Generates
@RepositoryFull JDBC implementation from the interface's @Query SQL
@ServiceImplementationDI provider registration
@TypeController / @FieldGraphQL resolver wiring
@RouteControllerHTTP route handler registration + DI provider
@JobDefinitionJob executor provider and enqueue helpers
@JobEventdispatch() extension that enqueues jobs and publishes to pub-sub
@Schemas / @SchemaSchema file merging across modules
Generated code goes to build/generated/ksp/ and must never be committed.

Key Abstractions

Bosca uses abstracted infrastructure services. The code works against interfaces, not specific products.

CacheManager

Central registry of named caches providing the distributed (remote) cache tier. The backing store is selected at startup via configuration — implementations exist for Redis and NATS KV. Your code never interacts with the backing store directly; it works through ServiceCache and RequestCache, which delegate to CacheManager.

PubSubService

The publish-subscribe abstraction. Channels are named strings, messages are serialized to JSON. subscribe() returns a Kotlin Flow. Implementations exist for both NATS and Redis pub-sub.

kotlin

JobQueue

Durable job queue abstraction with at-least-once delivery semantics. Implementations exist for NATS JetStream and Redis. Job enqueuing is deferred until after any open database transaction commits.

Server Architecture

The main backend is assembled into two applications:

  • bosca-server — Serves the GraphQL API over Netty (queries, mutations, subscriptions via WebSocket).
  • bosca-runner — Processes background jobs from the job queue.

Both load domain libraries through application-specific provider registrars. The server is a composition root: business logic belongs in the domain modules. Dedicated applications serve Git transport, artifacts, analytics collection, and BML messages; Studio is the administration UI.

Build from the workspace root

settings.gradle.kts maps component directories to Gradle projects. Local io.bosca:* dependencies resolve to these projects without publishing to Maven Local. JVM modules use Java 25. For example:

bash

Start with Infrastructure to run from source, or Run Bosca Locally to use published images.

Async-First

All I/O uses Kotlin suspend functions throughout the stack. JDBC blocking calls are dispatched to a virtual-thread-per-task executor (DatabaseDispatcher) so they don't block coroutine thread-pool threads.