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.
| Annotation | What KSP Generates |
|---|---|
@Repository | Full JDBC implementation from the interface's @Query SQL |
@ServiceImplementation | DI provider registration |
@TypeController / @Field | GraphQL resolver wiring |
@RouteController | HTTP route handler registration + DI provider |
@JobDefinition | Job executor provider and enqueue helpers |
@JobEvent | dispatch() extension that enqueues jobs and publishes to pub-sub |
@Schemas / @Schema | Schema file merging across modules |
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.
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:
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.