Kairo

Kairo is your one-stop toolkit for production-ready Kotlin backends.

Packed with a curated collection of proven, production-ready libraries, it saves you the pain of hunting down, testing, and wiring together dependencies yourself. Each library has been hand-selected for reliability, performance, and developer experience, meaning you can skip the boilerplate and get straight to building something great.

Designed to work seamlessly together but flexible enough to slot into any project, Kairo's libraries let you move faster, write cleaner code, and focus on the parts of your app that actually matter.

Documentation · API Reference · Getting Started · Architecture

Getting started

This section assumes you're using Gradle.

Kairo is hosted on Google Artifact Registry, so you'll first need to add the Google Artifact Registry plugin and connect to the Highbeam repository.

// build.gradle.kts

plugins {
  id("com.google.cloud.artifactregistry.gradle-plugin")
}

repositories {
  maven {
    url = uri("artifactregistry://us-central1-maven.pkg.dev/highbeam-kairo/maven")
  }
}

Using one (or just a few) Kairo libraries

Kairo's standalone libraries can be used independently within your existing project.

To use a single Kairo library, you could just add it to your dependencies block as you normally would.

// build.gradle.kts

dependencies {
  implementation("com.highbeam.kairo:YOUR-LIBRARY-OF-CHOICE:6.0.0")
}

However, we recommend using Kairo's BOM to keep your Kairo dependencies aligned.

// build.gradle.kts

dependencies {
  implementation(platform("com.highbeam.kairo:bom:6.0.0"))
  implementation("com.highbeam.kairo:YOUR-LIBRARY-OF-CHOICE")
}

Building a Kairo application

Great choice! You're in for a treat.

If you're building your entire application with Kairo, we highly recommend using Kairo's full BOM, which not only keeps your Kairo dependencies aligned but also aligns several external library versions.

// build.gradle.kts

dependencies {
  implementation(platform("com.highbeam.kairo:bom-full:6.0.0"))
}

Libraries

Standalone libraries

These libraries can be used anywhere (within Kairo applications or in any other Kotlin project).

• kairo-config: HOCON-based configuration library with multi-env (dev/staging/prod) support, environment variable substitution, and dynamic config resolvers to pull properties from sources like Google Secret Manager.
• kairo-coroutines: Extends Kotlin coroutines using Arrow's coroutines library and some convenient helper functions.
• kairo-darb: Compact boolean list encoding for JWT permission lists, maintaining human-readability.
• kairo-datetime: Extends kotlinx-datetime and adds some convenient helper functions.
• kairo-exception: Differentiate between logical failures and real exceptions.
• kairo-gcp-secret-supplier: Lightweight and coroutine-friendly Google Secret Manager wrapper.
• kairo-hocon: Wrapper around lightbend/config, along with JSON serialization support.
• kairo-id: Human-readable semantic identifiers with variable entropy. Compile-time safety without runtime overhead.
• kairo-image: Some utilities for working with images.
• kairo-logging: SLF4J-standardized logging (choose your own logging backend), exposing Ohad Shai's Kotlin logging interface for a clean, Kotlin-first API.
• kairo-money: Modern JVM money handling (javax.money backed by Moneta).
• kairo-optional: Differentiate between missing and null values. This comes in especially handy for RFC 7396 (JSON Merge Patch).
• kairo-protected-string: Handle sensitive strings that shouldn't be logged. toString() auto-redacts.
• kairo-reflect: Extends Kotlin reflection, unifying fragmented JVM/Kotlin into the safer and richer KairoType<T>.
• kairo-serialization: Kairo provides a wrapper around Jackson for serialization.
• kairo-testing: Kotlin-esque JUnit-style testing, with coroutine and mocking support.
• kairo-util: A home for simple utilities.
• kairo-validation: Common validation patterns.

Application libraries

These libraries help when building your full application with Kairo.

• kairo-application: Start your Server, wait for JVM termination, and clean up afterwards, all with a single call.
• kairo-client: Ktor-native outgoing HTTP requests.
• kairo-dependency-injection: Don't waste time and energy manually wiring your classes together. Let Koin create and wire everything instead!
• kairo-feature: The core building block of Kairo applications, including both Framework Features and Domain Features.
• kairo-health-check: With just a few lines of code you can add health check endpoints to your Kairo application.
• kairo-integration-testing: Black-box integration testing support for Kairo applications.
• kairo-mailersend: Interface for MailerSend, letting you easily send emails!
• kairo-rest: Ktor-based REST implementation with advanced routing DSL.
• kairo-server: Servers are composed of Features, and can be run as an application or as part of integration tests.
• kairo-slack: Leverages Slack's native JVM client and Kotlin DSL to make Slack interaction easy. Also offers channel mapping functionality.
• kairo-sql: Standardizes SQL access in Kairo using Exposed's lightweight & idiomatic ORM DSL, with support for async I/O using R2DBC.
• kairo-stytch: Interface for Stytch, letting you easily manage identity.

Style guide

Other than the rules defined here, please follow the Google Style Guide.

• Product terminology:

  • Treat Kairo Features and Servers as proper nouns (the first letter should be capitalized).
  • Also use proper nouns for Kotlin Flows.

• Sentence case: Use American English style for general capitalization. Use sentence case in all headings, titles, and navigation. This includes for user-facing copy and within code and documentation. This is consistent with the Google Style Guide.

• Full sentences: Use full sentences, ending with proper punctuation. This applies to both copy and to code comments and logs. It also applies within bulleted and numbered lists when they contain more than one clause.

• Ordering:

  • Order members in code by read-create-update-delete where possible.
  • Order lists alphabetically when there is no other natural order. This applies to both copy and to code (such as parameter/method lists and documentation).

• Plurality: For naming, singular forms should be preferred over plural forms where possible. This includes for folder, package, and Feature names.

  • REST paths should be plural, due to convention.

• Abbreviations: In general, abbreviations should be avoided. Specifically, i.e. and e.g. should be avoided.

• Non-null: Prefer the term "non-null" to "not null".

• Get vs. list vs. search: The term "get" should be used when fetching a particular entity. The term "list" should be used when fetching all entities matching a simple condition. The term "search" should be used when fetching all entities matching some filter(s).