DEV Community: Casey Brooks

Designing a User Management system with JWTs, Ktor, and Exposed

Casey Brooks — Fri, 11 Sep 2026 19:30:54 +0000

Every app eventually needs to answer two questions: "who is this person?" and "what are they allowed to do?" Many tutorials either focus on integrating a specific authentication provider like Auth0 or Cognito, or else discuss low-level details like password hashing algorithms. But both of those stop short of the real question we should be asking ourselves: who actually is this person, and what does that mean in terms of how we manage their data and access? This is not just a question of 'did this person log in?', but it's a more fundamental problem of understanding the actual human interacting with your app.

This may sound like a subtle distinction but it matters more than it might seem, and this post will help you understand the difference between identity, authentication, and authorization.

This post is part of a series on the Vesper Design Diaries, building a Production-Grade KMP App on a Bootstrap Budget. See the Series Introduction for context on the Vesper app and this blog series.

Identity vs Authentication vs. Authorization

These words get often used interchangeably, but they describe fundamentally different problems. So before we dive into Vesper's user management system, let's make sure we properly understand these terms.

Identity is the simple fact of who is using the app. This is a distinctly non-technical concept here. It refers to the actual human (or machine) interacting with your system, who takes actions to request and change data within it. In many cases, apps will use something like your email address to identify you as a human, since emails are something that is ubiquitous and stable. People don't change their email very often, and they are not shared, so it's a reasonable way to identify you as a person. Government systems may use something like a Social Security Number or other tax ID, but in general, the idea is that the system uses some stable String value that is uniquely associated with you as the human using the system.

Authentication is identity verification: are you who you say you are? When you log in, you aren't telling the system who you are. Your email, username, SSN, etc. tell the system who you are, but anyone can forge those values and claim to be you (identity theft is a real thing, y'all). What the system is actually asking for is a way to prove that you are actually the person you are claiming to be. A password check, a One-Time-Password (OTP) code sent to your email or phone, a biometric scan: these are all authentication mechanisms. A strong authentication system will commonly use multiple methods of verification (MFA) by requiring you provide proof of both something you have (an email address, your phone's biometrics) and something you know (password, security questions).

Authorization is permission checking: are you allowed to do this specific thing? Even after you've proven who you are, the system still needs to decide whether you can read a particular resource, write to a particular table, or perform a particular action. You could walk up to the Pentagon with your real ID in hand, but the guards would not let you inside the building because you do not have permission to be there.

The naive conflation of these terms works fine until it doesn't, which usually happens the first time you need to support more than one way to authenticate, revoke access without deleting the account, or you need to support different roles among users (such as system admins, moderators, and regular end-users). Having a clear differentiation between your users' identity and the way they prove that they are allowed to perform actions is something that is much easier to define at the beginning of the project than it is to bolt on later.

Why You Still Need Your Own User System

One common shortcut is to delegate authentication entirely to an external provider (Auth0, AWS Cognito, Google Identity) and skip building a user system at all. The provider handles login, issues JWTs, and your backend just validates the token. Simple.

The problem is that the external provider only knows about authentication events. It doesn't know anything about your application's domain. It can't tell you what a user has done in your system, what device they're on, or whether a particular session has been administratively revoked by your own support team. As soon as you need to reason about users from your application's perspective (usage history, per-device push tokens, session management, merging a guest account into a registered one, allowing a user to log in with multiple social accounts), you need your own representation of a user that is independent of any specific authentication provider.

The better framing is that an external OIDC provider is just one possible source of authentication events. Whether a user authenticates via Auth0, passkeys, via an OTP email, personal access tokens, or as an anonymous guest, all of those are paths that eventually produce a JWT, which your backend validates in exactly the same way. The external provider shouldn't replace or become your user management system; it should just be one of a variety of ways to populate it.

Vesper is designed around this from the start. It currently only uses a custom OTP authentication flow, but all of the frontend code is designed to use the same OAuth-style token management and authentication flows, so I'll be able to add Auth0 and native Google/Apple logins later without a big migration effort.

Getting a JWT into the Client

JWT stands for JSON Web Token. It's a signed JSON document: three Base64-encoded segments (header, payload, signature) joined by dots. The payload carries arbitrary claims: a subject identifier, an expiry, custom fields like scope. The signature is what makes it trustworthy: whoever holds the signing secret (or the corresponding public key, for asymmetric schemes) can verify the payload hasn't been tampered with, without contacting anyone else. That self-verifying property is the key that allows a JWT to be trusted as a security credential, guaranteeing the user is who they claim to be as a result of the trust we have in the system that issued the JWT.

With that trust model established, the question becomes: how does the client actually obtain a JWT?

OAuth 2.0 / OIDC is the standard flow used by external providers like Auth0, Cognito, and Google. The user is redirected to the provider's login page, where they authenticate themselves to that provider, using any combination of username/password, social account logins, MFA codes, etc. After authenticating successfully with the provider, they are redirected back to your app with a deep link containing a short-lived authorization code, which is then exchanged for an access token (often JWT, but sometimes opaque) and ID token (always JWT). The resulting JWT is signed by the provider using their private key. Your backend registers a corresponding public key and from then on validation is purely local, no callback to the provider required.

A hand-rolled flow like email OTP works the same way with your own server as the issuer. The user submits their email, your server sends it a short-lived code, and the user presents it back proving they have access to that email inbox. Because of that verified access, your server mints a JWT directly, signed and secured by its own random secret key, so your API server alone is able to mint and verify this JWT.

Both flows produce the same artifact from the client's point of view: a signed JWT to store and attach to requests.

On the client, Vesper stores the access token and refresh token inside the AppStateViewModel as described in the previous post, which persists the full state to multiplatform-settings using each platform's encrypted storage. Because access tokens are short-lived (30 minutes), the client also holds a long-lived refresh token and rotates the pair silently in the background before expiry. When making an API call, we attach the token to an Authorization: Bearer header, which the server then reads and verifies before calling its route handlers.

Ktor's client-side Auth plugin is the standard way to do this (it intercepts 401 responses and retries transparently), but I went a different direction. The Auth plugin is well-suited for standard OIDC flows where the token lifecycle maps cleanly to HTTP status codes and where authentication is more-or-less a binary decision: the user is logged in, or they are not. But I wanted more explicit control over exactly when tokens get refreshed and which call sites are responsible for triggering that flow. I have the client app manually inspecting the JWT's contents and refreshing when approaching the expiry. This reduces noise in the server logs and makes a 401 mean that the user truly was not authenticated (i.e. the refresh token expired, or their session was explicitly revoked), rather than just a signal to refresh the auth token. The result looks something like this:

class GetMyPrayersUseCaseImpl(
    private val httpClient: HttpClient,
    private val getOrRefreshAuthTokenUseCase: GetOrRefreshAuthTokenUseCase,
) : GetMyPrayersUseCase {
    override suspend fun invoke(): List<PrayerDto> {
        val token = getOrRefreshAuthTokenUseCase()
        return httpClient
            .get("/api/v1/protected/prayers") {
                header(HttpHeaders.Authorization, "Bearer $token")
            }
            .body<List<PrayerDto>>()
    }
}

GetOrRefreshAuthTokenUseCase checks whether the stored access token is still valid by parsing its exp claim directly from the Base64 payload (no library needed, it's just JSON) and returns it immediately if it has more than five minutes left. If it's close to expiry, it acquires a mutex before refreshing, re-checks inside the lock (in case another coroutine already refreshed while this one was waiting), and only then calls the refresh endpoint. The mutex prevents the thundering-herd problem where multiple concurrent requests all decide to refresh at the same moment and issue redundant calls.

The explicitness at each call site is the point: it's immediately obvious which use cases touch protected APIs and which don't, and token refresh happens proactively before expiry rather than reactively on a 401. It also allows me to keep the HttpClient and the AppState completely decoupled, which is an intentional data-layer constraint that I will explain in a later post.

Securing server routes with JWTs

Because JWTs contain information for both identifying a user and declaring their authorized access, it's typically needed at multiple points within the API request pipeline. As a best practice, JWT authentication should be handled in multiple layers, but before getting into those details, we first need to understand the structure of a JWT.

The structure of a JWT

A JWT is sent to the server in a header which looks like this:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiZW1haWwiOiJqb2huZG9lQGV4YW1wbGUuY29tIiwic2NvcGUiOiJvcGVuaWQgcHJvZmlsZSBlbWFpbCBhcGk6cHJvdGVjdGVkIiwiaWF0IjoxNTE2MjM5MDIyfQ.S-GCY6udo4ChncUiZucu9kHIHS7OL3S48If2EeSm-IU

When unpacked by the server, we get:

Header={
  "alg": "HS256",
  "typ": "JWT"
}
Payload={
  "sub": "1234567890",
  "name": "John Doe",
  "email": "johndoe@example.com",
  "scope": "openid profile email api:protected",
  "iat": 1516239022
}
Signature=S-GCY6udo4ChncUiZucu9kHIHS7OL3S48If2EeSm-IU

The header tells the server how to verify the signature, which is a core part of the JWT protocol, and the Payload contains the information the server needs to identify the user and authorize their actions. Depending on which service created the JWT, you may get a variety of claims, but at a minimum you should get:

iss (required): Issuer, the URL identifying the OIDC Provider
sub (required): Subject, a stable unique identifier for the user at that issuer
aud (required): Audience, the client_id the token was issued to
iat (required): Issued-at time
exp (required): Expiration time
name (common, not required): The user's full name
email (common, not required): The user's email address
email_verified (common, not required): True if the issuer has confirmed the user can access the email address, such as with a verification link
scope (common, not required): A space-separated list of scopes declaring the resources this JWT permits access to

Every value in the payload was verified by the issuer and signed, so your server is able to trust all of the values it contains. If the JWT claims the email was verified, you can trust that without necessarily needing to send your own email-verification link, for example. And the scope list means the user is actually granting access to the corresponding resources, often by being presented with a consent screen to explicitly confirm they want to provide such information to your server.

Together, all of these values constitute the result of a handshake between your server, an authorization provider, and the end user. It's a secure credential that can be treated like a password, but the "password" in this case isn't used to verify a login and initiate a session, it is the session, being wholly self-contained and including all the information your server needs to accept or reject the use of any particular API endpoint.

Authentication

Ktor's authentication plugin verifies the JWT is legitimate, by checking its signature against the auth provider using the verifier blocks to declare which auth providers may issue JWTs to your server:

fun Application.module() { 
    authentication {
        // verify guest tokens issued by our own API
        jwt("guestToken") {
            verifier(
                JWT.require(Algorithm.HMAC256(jwtConfig.jwtSecret))
                    .withIssuer(jwtConfig.jwtIssuer)
                    .withAudience(jwtConfig.jwtAudience)
                    .build()
            )
            validate { credential -> JWTPrincipal(credential.payload) }
        }

        // verify tokens issued by an OIDC provider like Auth0
        jwt("oidcToken") {
            verifier(
                JWT.require(Algorithm.RSA256(jwtConfig.oidcPublicKey))
                    .withIssuer(jwtConfig.oidcIssuer)
                    .withAudience(jwtConfig.oidcAudience)
                    .build()
            )
            validate { credential -> JWTPrincipal(credential.payload) }
        }
    }
}

and then wrapping your API routes with the authenticate route plugin:

routing {
    authenticate("guestToken", "oidcToken", strategy = AuthenticationStrategy.FirstSuccessful) {
        get("/api/v1/protected/prayers") { ... }
    }
}

Ktor tries each verifier in order and accepts the first that succeeds. The route handler never knows which one matched; it just reads claims off the JWTPrincipal. That's the key property: once inside an authenticate block, identity is proven and the issuer is irrelevant. As long as someone is able to vouch for the validity of the JWT and confirm it contains the necessary data for our routes, the endpoint itself really doesn't need to know anything else. The JWT will provide the stable email claim regardless of whether it came from Google, Auth0, or our own OTP flow, and so we can always associate the JWT back to the user's account, since we can know the JWT came from a trusted source and could not be modified to change the email. We can trust the JWT because we trust the system that minted the JWT.

Authorization

However, proving that a JWT is legitimate is not enough. Ktor's authenticate plugin does not check the content of the JWT for the allowed scopes, so we need to do that manually. You can build a basic Ktor route plugin that allows you to inspect the verified JWT payload, read its claims, and check whether the token allows access to a particular scope declared by your server. A small scopedRoute helper wraps the plugin installation so each route can declare its required scope in a single line rather than calling install(RequireScope) directly.


// Route Plugin
// ---------------------------------------------------------------------------------------------------------------------
class RequireScopeConfig {
    var scope: String = ""
}

val RequireScope = createRouteScopedPlugin("RequireScope", ::RequireScopeConfig) {
    val requiredScope = pluginConfig.scope

    on(AuthenticationChecked) {
        val principal = call.principal<JWTPrincipal>() ?: error("RequireScope must be used with JWT authorization")
        val scopes = principal.payload.getClaim("scope").asString()?.split(" ") ?: emptyList()

        if (requiredScope !in scopes) {
            call.respond(HttpStatusCode.Forbidden, "Missing required scope: $requiredScope")
            finish()
        }
    }
}

fun Route.scopedRoute(path: String, requiredScope: String, build: Route.() -> Unit): Route =
    route(path) {
        install(RequireScope) { scope = requiredScope }
        build()
    }

// Apply to endpoints
// ---------------------------------------------------------------------------------------------------------------------

fun Application.configureRouting() {
    routing {
        authenticate("auth-jwt") {
            scopedRoute("/prayers", "prayer:read") {
                get {
                    call.respondText("Here are your prayers")
                }
                get("/{id}") {
                    call.respondText("Here is your prayer")
                }
            }
        }
    }
}

That's a clean two-level system on its own. But it creates a practical problem: if every route lists its own fine-grained scope, every default device token needs to enumerate all of them, which bloats the JWT, and complicates the process of adding new scopes. They typically need to be registered with the OIDC provider, and also explicitly requested by the client app, so it's best to avoid changing those scopes, if possible.

One way to solve this problem is by letting the auth provider issue a JWT with a very coarse-grained scope, while the server "expands" that one scope into the full suite of actions that are enabled by it. This way, you can allow each endpoint to declare a scope that is narrow and focused on just the one task at hand, while broadly accepting the same scope and re-interpreting it to include/exclude individual endpoints as needed without needing to change the frontend or auth server code.

For Vesper, this works by declaring an enum for all of the possible scopes that may be needed by an API endpoint:

enum class AppAuthTokenScope(val scope: String) {
    ApiProtected("api:protected"),
    PrayerCreate("prayer:create"),
    PrayerRead("prayer:read"),
    ProfileRead("profile:read"),
    ProfileUpdate("profile:update"),
    ProfileVerify("profile:verify"),
    // ...
}
fun AppAuthTokenScope.implies(): Set<AppAuthTokenScope> {
    return when (this) {
        AppAuthTokenScope.ApiProtected -> setOf(
            AppAuthTokenScope.PrayerCreate,
            AppAuthTokenScope.PrayerRead,
            AppAuthTokenScope.PrayerUpdate,
            ...
        )
        else -> setOf(this)
    }
}
fun AppAuthTokenScope.impliedScopes(): Set<AppAuthTokenScope> {
    return implies().flatMap {
        if (it.implies() == setOf(it)) {
            setOf(it)
        } else {
            it.impliedScopes()
        }
    }.toSet()
}

However, it is not expected that the JWT issued by the OIDC provider (or by Vesper's own OTP flow) individually lists all of these scopes. Instead, the standard scope issued is just api:protected. An impliedScopes() function recursively expands it to the full set of fine-grained scopes at validation time on the server, so the token stays compact while route-level checks work against the specific values. This also helps to prevent exposure of private security information to the frontend, as only the server is privy to what other scopes are implied by the api:protected scope, while also allowing that set of implied scopes to change over time.

With this in place, RequireScopeConfig and RequireScope need to be updated to work against the expanded scope list rather than raw strings. The version below replaces both from above, changing the scope field from a plain String to a typed AppAuthTokenScope:

fun expandScope(scope: String): List<AppAuthTokenScope> {
    return AppAuthTokenScope.entries
        .firstOrNull { it.scope == scope }
        ?.impliedScopes()
        ?.map { it.scope }
        ?.toSet()
        ?: setOf(scope)
}

class RequireScopeConfig {
    var scope: AppAuthTokenScope? = null
}

val RequireScope = createRouteScopedPlugin("RequireScope", ::RequireScopeConfig) {
    val requiredScope = pluginConfig.scope ?: error("scope must not be null")

    on(AuthenticationChecked) {
        val principal = call.principal<JWTPrincipal>() ?: error("RequireScope must be used with JWT authorization")
        val scopes = principal.payload.getClaim("scope").asString()?.split(" ")?.flatMap { expandScope(it) } ?: emptyList()

        if (requiredScope !in scopes) {
            call.respond(HttpStatusCode.Forbidden, "Missing required scope: $requiredScope")
            finish()
        }
    }
}

fun Application.configureRouting() {
    routing {
        authenticate("auth-jwt") {
            scopedRoute("/prayers", AppAuthTokenScope.PrayerRead) {
                get {
                    call.respondText("Here are your prayers")
                }
                get("/{id}") {
                    call.respondText("Here is your prayer")
                }
            }
        }
    }
}

Determining Identity

Now that we have verified the JWT and proved they're able to access this specific endpoint, we now need to figure out who exactly they are. The JWT contains claims like sub and email which do not necessarily match up to the equivalent values in our system, so we need a way to map the JWT to our own user DB record.

Database Schema

Vesper's user management rests on three database tables with distinct responsibilities.

user_profiles is the identity record. It holds personal attributes (email, phone, name, date of birth) along with verification state, terms acceptance, and a set of OTP staging columns I'll come back to later. It knows nothing about sessions or tokens.

user_devices represents a physical device (Android, iOS, Web, Desktop, or Server). Each device has a stable device_id string and optionally a push token for notifications. A user profile can have many devices, though "device" is a slight misnomer, as the same physical device may have multiple records if one accesses Vesper from both the web browser and from the mobile app.

user_authorizations is the authorization record. It links a jwt_subject (the JWT sub claim) to both a user_profile_id and a user_device_id. It also holds the refresh token, an expiry, and a revoked flag. This broadly can be thought of as an "active session", and users may have multiple sessions active at once if they're logged in on different devices simultaneously.

Keeping authorization separate from identity means you can revoke a session without touching the user's profile. The revoked flag, combined with the jwt_subject lookup on every authenticated request, gives you per-session logout, remote logout of all other devices, or a full account-wide logout, all with a targeted WHERE clause against user_authorizations.

Matching JWTs to Users

At this point Ktor has already verified the JWT's cryptographic signature and checked the required scope. What remains is resolving the verified sub claim to an active session and the identity attached to it. But "resolving" here can mean two different things depending on whether we've seen this sub before:

Returning user: there is already a user_authorizations row for this jwt_subject. Look it up, run the validity checks, and return.
First login from this issuer: no user_authorizations row exists yet. We need to find or create the user_profile, find or create the user_device, wire them together in user_authorizations, and then run the validity checks.

The call site for route handlers is the same in both cases:

suspend fun ApplicationCall.getCurrentUser(): UserSession {
    val principal = principal<JWTPrincipal>() ?: error("no JWT principal")
    val jwtSubject = principal.payload.subject  // the `sub` claim
    val deviceId   = request.headers["X-Device-Id"] ?: return badRequest("Missing device ID")

    val session = db.findOrCreateSession(jwtSubject, principal.payload, deviceId)

    if (session.authorization.revoked)   return unauthorized("Session has been revoked")
    if (session.authorization.isExpired) return unauthorized("Session has expired")
    if (session.userProfile.banned)      return forbidden("Account is suspended")

    return session
}

data class UserSession(
    val authorization: UserAuthorization,   // user_authorizations row
    val userProfile: UserProfile,           // user_profiles row
    val device: UserDevice,                 // user_devices row
)

findOrCreateSession handles both paths in a single database transaction:

fun findOrCreateSession(jwtSubject: String, claims: JWTPayload, deviceId: String): UserSession {
    // Fast path: we've seen this sub before
    findSessionBySubject(jwtSubject)?.let { return it }

    // First login from this issuer: bootstrap the three tables
    return transaction {
        // The email claim lets us link to an existing profile if the user already
        // has one (e.g. they previously logged in via OTP with the same address).
        // If not, we create a fresh profile seeded from the JWT claims.
        val profile = findProfileByEmail(claims.email)
            ?: createProfile(
                email         = claims.email,
                name          = claims.name,
                emailVerified = claims.emailVerified,
            )

        val device = findOrCreateDevice(deviceId)

        val authorization = createAuthorization(
            jwtSubject    = jwtSubject,
            userProfileId = profile.id,
            userDeviceId  = device.id,
        )

        UserSession(authorization, profile, device)
    }
}

fun findSessionBySubject(jwtSubject: String): UserSession? {
    // SELECT * FROM user_authorizations
    //   JOIN user_profiles ON user_profiles.id = user_authorizations.user_profile_id
    //   JOIN user_devices  ON user_devices.id  = user_authorizations.user_device_id
    //  WHERE user_authorizations.jwt_subject = ?
    val row = db.queryOne(jwtSubject) ?: return null
    return UserSession(row.toUserAuthorization(), row.toUserProfile(), row.toUserDevice())
}

Why `sub`, not `email`, is the stable link

Notice that the fast path queries exclusively on jwt_subject, not on the email claim. This is intentional, and it's the property that lets your app and the OIDC provider evolve their data independently without breaking each other.

The sub claim is the OIDC provider's own stable internal ID for the user. It's issued once and never changes, even if the user changes their email address, their name, or any other profile attribute. Once findOrCreateSession has run for the first time and written that jwt_subject into user_authorizations, the link is established permanently. Everything downstream looks up by user_profile_id, which is your own stable internal ID. The external sub is just the bridge between the two worlds, used exactly once per lookup, at the edge of the system.

After that first login, your user_profiles.email and the email claim in the JWT are completely independent columns:

User changes their email with the OIDC provider. The sub in their JWT stays the same, so findSessionBySubject still resolves to the correct profile. The stale email in the JWT is irrelevant; it was only meaningful during the first-login findProfileByEmail fallback.
User changes their email inside your app. user_profiles.email updates normally. The JWT's email claim is never consulted for an existing session, so there's no conflict and no sync required.
User logs in with a second OIDC provider. That provider issues a different sub. findSessionBySubject returns null, findProfileByEmail finds the existing profile, and a second user_authorizations row is inserted pointing to the same user_profile_id. Now the user can log in via either provider and land on the same account.

The only time the JWT's identity claims (email, name, email_verified) matter is during that first-login bootstrap. After that your profile is the authority on identity, and the OIDC server is the authority on authentication. Neither needs to know what the other is doing.

With that plumbing in place, route handlers reduce to a single call:

get("/api/v1/protected/prayers") {
    val user = call.getCurrentUser()
    val prayers = getPrayers(ownerId = user.userProfile.id)
    call.respond(prayers)
}

Whether the JWT came from the OTP flow, an OIDC provider, or a Personal Access Token, the call is identical; the issuer difference was resolved upstream by the Ktor verifier, and the identity/session link was resolved by findOrCreateSession.

Tying it all together

Here is a high-level walkthrough of a single authenticated request, from the moment the client decides to make a call to the moment the route handler runs.

Client-side Flow

Step 1: The client checks whether it has any tokens at all. If no tokens are in encrypted storage, the user is redirected to the appropriate auth flow to obtain a fresh token pair. Everything below assumes that check passed.

Step 2: The client checks whether the access token is still usable. GetOrRefreshAuthTokenUseCase reads the exp claim directly from the stored access token. If it has more than five minutes of lifetime remaining, it's returned immediately and the request proceeds.

Step 3: If the access token is expiring, the client silently refreshes. A coroutine mutex gates the refresh call so that only one concurrent request actually hits the refresh endpoint. If the refresh fails, the client clears its tokens and sends the user back to the auth flow.

Step 4: The client makes a request with the token in the header. The token is attached to Authorization: Bearer {accessToken} and sent. From the client's perspective, that's all it needs to know: the token either works or it doesn't.

Server-side Flow

Step 1: Ktor receives a request. The server matches it to a route and begins running the request pipeline for that route.

Step 2: Ktor's authenticate block runs. The JWT's signature is verified against the registered verifiers. A non-matching or expired token returns a 401 immediately; the route handler is never touched.

Step 3: The RequireScope plugin runs. The scope claim is expanded through expandScope() and checked against the scope required by this specific route. A missing scope returns a 403.

Step 4: The route handler calls getCurrentUser(). The sub claim is resolved to a UserSession via findOrCreateSession, automatically provisioning profile and device records on first login from a new issuer. The session is then checked for revocation, expiry, and user bans before proceeding.

Step 5: The route handler does its work. With a fully resolved UserSession in hand, the handler performs its work using user.userProfile.id as the stable owner identifier, completely unaware of which auth provider issued the token or how the identity was resolved.

The consistent principle across all of this is that identity, authentication, and authorization are kept separate not just as concepts but as code. Each layer owns one check and passes a stronger guarantee to the next. The result is a pipeline that works identically whether the JWT came from a hand-rolled OTP flow, an OIDC provider, or any future auth mechanism, because by the time the route handler runs, the token has already been forgotten. Each system is self-contained, doesn't leak implementation details into the next layer, and is able to evolve on its own without impacting the rest of the application.

Together, all of this builds a stable foundation upon which we can build the rest of the functionality needed for a complex system.

PS: A note on opaque tokens

Everything in this post assumes the auth provider issues JWTs for access tokens, which is the most common case and the default for many providers. However, some OIDC providers (Auth0 being a notable example) can be configured to issue opaque access tokens instead: short random strings with no parseable payload.

Opaque tokens require slightly different mechanisms for checking expiry on the client and for resolving the user's identity and scope on the server. But those differences are implementation details. The underlying concepts are identical: the client still needs to know when a token is approaching expiry and refresh it proactively, and the server still needs to verify the token, resolve the authorized scope, and map it to a stable user identity before the route handler runs. The shape of the pipeline doesn't change, only the specific tools used at each step.

Building Vesper on Ballast: One State Model to Rule Them All

Casey Brooks — Thu, 03 Sep 2026 16:57:21 +0000

As mentioned in the Series Introduction, Ballast is a foundational piece of the architecture of the Vesper app. Ballast is the architecture of the frontend application, and it is the Kotlin-language interface to the server-side schedules and background queue workloads. An understanding of Ballast and the problems it was designed to solve are crucial for understanding why I built Vesper in the way I did.

This post is part of a series on the Vesper Design Diaries, building a Production-Grade KMP App on a Bootstrap Budget. See the Series Introduction for context on the Vesper app and this blog series.

Full disclosure before anything else: I wrote Ballast. I've been building it for several years, and Vesper is the most complete application I've built with it. Take my recommendation with appropriate skepticism — I'm clearly not a neutral party. That said, Vesper is the real test of whether my own ideas hold up under production conditions, and I think they do.

What Ballast Is and Why I Built It

Ballast started out as a KMP MVI framework, essentially a take on the Redux library popular with React. But Ballast takes the general idea of Redux and expands it to leverage some really nice features of the Kotlin language (like sealed interfaces), while allowing more flexibility to the overall "unidirectional data flow" programming model though the use of Coroutines, all without sacrificing any of the safety that this pattern was created for. Ballast is a highly opinionated library that aims to give you a structure for your code that is easily repeatable, yet adaptable for each individual application.

So what does Ballast look like? The short version: every Screen defines a Contract — a sealed interface of Inputs (things that can happen), a State (the current snapshot), and Events (one-shot side effects like navigation or dialogs). In practice with a pure KMP Compose app, Events are not really used (they are much more necessary with working with legacy Android code). But here's what a Contract in Ballast typically looks like, describing the functionality of a Stopwatch:

object StopwatchContract {
    data class State(
        val elapsedSeconds: Int = 0,
        val isRunning: Boolean = false,
    )

    sealed interface Inputs {
        data object Start : Inputs
        data object Stop : Inputs
        data object Reset : Inputs
        data object Tick : Inputs // posted internally when the stopwatch timer is running
    }

    sealed interface Events
}

The Contract is just a statement of the data that can be displayed to the screen (the State), and the Inputs are the actions the UI and background processes dispatch to change the State. An InputHandler processes each Input and returns an updated State or schedules additional work, while a ViewModel wires them together with a CoroutineScope to control its lifetime.

class StopwatchInputHandler : InputHandler<
        StopwatchContract.Inputs,
        StopwatchContract.Events,
        StopwatchContract.State> {

    override suspend fun InputHandlerScope<
            StopwatchContract.Inputs,
            StopwatchContract.Events,
            StopwatchContract.State>.handleInput(
        input: StopwatchContract.Inputs
    ) = when (input) {
        is StopwatchContract.Inputs.Start -> {
            updateState { it.copy(isRunning = true) }
            sideJob("tick") {
                while (true) {
                    delay(1.seconds)
                    postInput(StopwatchContract.Inputs.Tick)
                }
            }
        }
        is StopwatchContract.Inputs.Stop -> {
            updateState { it.copy(isRunning = false) }
            cancelSideJob("tick") /* cancels the running loop */
        }
        is StopwatchContract.Inputs.Reset -> {
            updateState { it.copy(elapsedSeconds = 0, isRunning = false) }
        }
        is StopwatchContract.Inputs.Tick -> {
            updateState { it.copy(elapsedSeconds = elapsedSeconds + 1) }
        }
    }
}

class StopwatchViewModel(
    coroutineScope: CoroutineScope,
) : BasicViewModel<
        StopwatchContract.Inputs,
        StopwatchContract.Events,
        StopwatchContract.State>(
    coroutineScope = coroutineScope,
    config = BallastViewModelConfiguration.Builder()
        .withViewModel(
            inputHandler = StopwatchInputHandler(),
            initialState = StopwatchContract.State(),
            name = "StopwatchViewModel",
        )
        .also { inputStrategy = FifoInputStrategy.typed() }
        .build(),
    eventHandler = eventHandler { },
)

With Compose, it's best to define each screen with two components: one which is fully Stateless that renders content purely based on the current State, and a Stateful version which gets the ViewModel instance via Dependency Injection and coordinates state and inputs with the Stateless version.

// Stateful — acquires the ViewModel and bridges to the stateless component
@Composable
fun StopwatchScreen() {
    val vm = koinViewModel<StopwatchViewModel>()
    val state by vm.observeStates().collectAsState()
    StopwatchScreenContent(state, postInput = { vm.trySend(it) })
}

// Stateless — receives State and a postInput lambda; no ViewModel reference needed
@Composable
fun StopwatchScreenContent(
    state: StopwatchContract.State,
    postInput: (StopwatchContract.Inputs) -> Unit,
) {
    Column(horizontalAlignment = Alignment.CenterHorizontally) {
        Text(text = "${state.elapsedSeconds}s", style = MaterialTheme.typography.displayLarge)
        Row {
            if (state.isRunning) {
                Button(onClick = { postInput(StopwatchContract.Inputs.Stop) }) { Text("Stop") }
            } else {
                Button(onClick = { postInput(StopwatchContract.Inputs.Start) }) { Text("Start") }
            }
            OutlinedButton(onClick = { postInput(StopwatchContract.Inputs.Reset) }) { Text("Reset") }
        }
    }
}

You'll notice that none of the above code requires annotation processors, code generation, or reflection to function. Ballast has none of that. Every contract, handler, and adapter is code I wrote and can navigate to directly in IntelliJ. When something breaks at 2am, I'm not guessing what a generated class is doing — I'm just reading the actual implementation (or nowadays, having Claude read it).

The "no magic" constraint isn't just aesthetics. On Kotlin Multiplatform, code generation support across all targets is still uneven. Reflection is either unavailable or slow on Native. KSP requires additional Gradle boilerplate and longer compile times, and makes it difficult to find, debug, and modify the generated code. Ballast sidesteps those problems entirely by requiring explicit code. You write more boilerplate upfront, but you get a consistent, debuggable, fully-navigable codebase in return, which can be freely modified or extended without requiring changes to the Ballast library itself.

Historically, the boilerplate problem was solved with scaffold tools, but these days, AI agents are so good at following patterns that you really don't even need that. I used Claude Code to build much of Vesper, and I was honestly shocked at how well it was able to follow the Ballast boilerplate without explicit prompting, given that Ballast is a bespoke library without much adoption. As a coworker told me when first getting introduced to Claude, "Claude loves structure". I completely agree, and Ballast's opinionated nature works with that very well.

The Contract Pattern in Practice

A typical screen in Vesper — such as the Submit Prayer screen — defines a contract like this:

object SubmitPrayerScreenContract {
    data class State(
        val prayerText: String = "",
        val isSubmitting: Boolean = false,
        val isError: Boolean = false,
    ) { 
        // many properties can be derived from the state, and it's best to 
        // co-locate that here to keep the logic out of Compose
        val isPrayerValid = prayerText.isNotEmpty()
    }

    sealed interface Inputs {
        data class UpdatePrayerText(val text: String) : Inputs
        data object Submit : Inputs
    }

    sealed interface Events
}

The InputHandler is a pure function that handles Inputs one-at-a-time (though a Coroutine Channel) and provides APIs
to update the state, start "side jobs" (coroutines that run the "background" of the ViewModel), or send Events or
follow-up Inputs.

class SubmitPrayerScreenInputHandler(
    private val submitPrayer: SubmitPrayerUseCase,
    private val router: Router,
) : InputHandler<Inputs, Events, State> {
    override suspend fun InputHandlerScope<Inputs, Events, State>.handleInput(input: Inputs) = when (input) {
        is Inputs.UpdatePrayerText -> {
            updateState { it.copy(prayerText = input.text) }
        }
        is Inputs.Submit -> {
            val currentState = updateStateAndGet { it.copy(isSubmitting = true) }
            try {
                val prayerResult = submitPrayer(currentState.prayerText)
                updateState { it.copy(isSubmitting = false) }
                sideJob {
                    router.sendAndAwaitCompletion(GoToDestination("/prayers/${prayerResult.id}"))
                }
            } catch(e: Exception) {
                updateState { it.copy(isSubmitting = false, isError = true) }
            }
        }
    }
}

Note that unlike Redux, Ballast does not require a strict 1:1 transformation from the Input to a State. Instead, it just carefully guards the internal StateFlow so that a single Input may safely use Coroutines to make several calls in series, updating the state as it goes. It also ensures Inputs are queued up and processed one-at-a-time in the order they were received, making sure there are no race conditions with your InputHandler code.

Since the InputHandler may have dependencies injected via DI, the InputHandler itself must be injected into a ViewModel's constructor, along with a CoroutineScope to define the lifetime of the ViewModel:

class SubmitPrayerScreenViewModel(
    coroutineScope: CoroutineScope,
    inputHandler: SubmitPrayerScreenInputHandler,
    configurationBuilder: BallastViewModelConfiguration.Builder,
) : BasicViewModel<Inputs, Events, State>(
    coroutineScope = coroutineScope,
    config = configurationBuilder
        .withViewModel(inputHandler = inputHandler, initialState = SubmitPrayerScreenContract.State())
        .build(),
)

The coroutine scope comes in from outside. That's the key design choice: whoever provides the scope owns the ViewModel's lifetime. On a screen, that's the navigation backstack entry or the Compose hierarchy (via rememberCoroutineScope()). For app-wide state, it's the Ktor application lifecycle on the server, or an application-scoped scope on mobile. I'll cover the backstack lifetime management in a dedicated post on navigation. I also have a Koin factory { } function which defines a base BallastViewModelConfiguration.Builder, which add cross-cutting Interceptors into all ViewModels, so I get things like automatic logging and a Debugger attached by default.

Application-Wide State

ViewModels don't need to be limited to just the UI layer, though. Vesper uses an additional AppStateViewModel scoped to an application-wide CoroutineScope which holds the state that needs to outlive any individual screen: auth tokens, theme preference, onboarding status, feature flags. This ViewModel uses a @Serializable State class with the saved-state module to persist all changes to multiplatform-settings. Cold launches restore the state from disk rather than starting blank, and the whole application is gated on this state restoration in the Splash Screen, so we can ensure it was correctly restored before attempting to use any of the AppState data.

For an online-first app like Vesper, this pattern acts as a lightweight data layer that sidesteps the need for a full SQLite database. The app's local storage needs are modest — a handful of preference values and session tokens — and a single serialized State covers all of it without a schema, migrations, a query layer, or DAO mapping code. Auth tokens and other sensitive fields are stored using encrypted storage helpers, making the settings store a safe credential store. Because Ballast processes Inputs sequentially, callers can use sendAndAwaitCompletion to post an Input and suspend until it has been fully handled — including until BallastSavedStateInterceptor has flushed the new state to disk. The ViewModel acts as a fast in-memory cache; sendAndAwaitCompletion gives you the guarantee that the cache and the store are in sync when you need it.

The Same Pattern on the Server

Beyond UI and application state, Ballast also powers the server-side background queues (via ballast-queue) and cron-style scheduled jobs (via ballast-scheduler) — the same Contract/InputHandler model, just with Inputs serialized to a Postgres table and retried on failure rather than processed in memory. Navigation is the same story: ballast-navigation drives routing with a URL-based backstack, using the same Contract pattern you saw above. I'll cover all of these topics in their own posts; the point for now is that learning the Contract/InputHandler shape once gives you a mental model that applies across the entire application stack and across various domains, not just UI state.

Why This Matters for Vesper

Vesper is a relatively simple app, and yet still has around 30 screens to manage, along with an application-wide state machine, non-trivial navigation logic, and a lot of complex platform-specific logic needed to bridge everything together. All of this runs within the Ballast system, making all user interactions and state changes predictable and reliable. New developers (or AI agents) know exactly what to look for in any feature: find the Contract, read the Inputs to know what can happen, read the InputHandler to know how those changes get applied.

The consistency also makes testing straightforward. InputHandler implementations have no framework dependencies — they take domain use cases as constructor arguments, which can be stubbed for tests. The State is a plain data class, which allows us to recreate any possible UI state for previews or snapshot tests. There's nothing to mock at the Ballast layer itself. I can verify the full behavioral logic of any screen by constructing its InputHandler, feeding it Inputs, and asserting on the resulting State — no Compose runtime, no Android emulator, no network.

That same legibility extends to AI-assisted development. Because each screen's logic is fully self-contained in a Contract + InputHandler pair, Claude could confidently generate or modify an InputHandler for a screen it had never seen before, just by pattern-matching against the rest of the codebase. The explicit structure that Ballast requires turns out to be exactly the kind of structure that makes a codebase easily understandable to both humans and machines.

I'll be referring back to Ballast throughout this series. The routing system, the server-side queue, and the saved-state adapter are all built on it. Understanding the basic Contract/InputHandler/ViewModel shape is the prerequisite for all of the other posts. You can find more documentation and examples, as well as additional features not used by Vesper such as Undo/Redo support or Firebase integrations, at github.com/copper-leaf/ballast.

Vesper Design Diaries: Building a Production-Grade KMP App on a Bootstrap Budget

Casey Brooks — Thu, 03 Sep 2026 16:25:06 +0000

On September 3rd I launched Vesper, a cross-platform Christian prayer app for Android and iOS, as my entry in the RevenueCat 2026 Shipaton. This is not just a basic app thrown together quickly for this context, though: I have spent months building it and iterating on the features and design, as I am building it as a real production-grade application to bootstrap a business. I'm publishing this series of technical posts as a retrospective look back on how I built it.

A bit of context

I first got the idea for this app and started working on Vesper in early May. The Shipaton happened to coincide with my already-planned release schedule, so I decided to wait a few extra weeks so I could polish things up and document the technical decisions I'd made along the way for the benefit of the Kotlin community. These posts are written after the fact. I'm not live-blogging the build; I'm looking back at what I built and explaining the 'why' behind my decisions.

Vesper was designed heavily around Ballast, a Kotlin Multiplatform state management library I have maintained for many years. Ballast is mostly my personal opinionated structure for building things like per-screen UI state and app navigation, so part of my motivation for this series is showing what Ballast looks like in a real, production-scale application.

But the things I learned building Vesper apply to anyone looking to make a real-world, production-ready application today, whether you choose to use Ballast or not. While these blogs will describe the actual code of Vesper using Ballast, the general knowledge and ways to think about building software capable of handling production workloads are not specific to Ballast.

Who these posts are for

This is an advanced series. I'm not going to walk through setting up a Ktor project from scratch or explain what a coroutine is. What I will do is focus on higher-level architectural decisions and the tradeoffs that come with them — the kind of thinking that goes into building software you actually intend to maintain and grow over many years.

Vesper is not a throwaway pet project. It's the foundation of what I hope can eventually become a real company. That shapes every decision in the codebase.

That said, I want to be honest about the audience for these posts: most of what I describe here is almost certainly over-architected for a simple side project, and quite probably under-powered for an established company with a real engineering team and real infrastructure budget. The constraint I was working under is the one you find at an early-stage pre-launch startup — needing production-stable code without being able to pay for production-grade services. I built a lot of things myself that I could have paid for as a service (email campaigns, feature flags, push notifications, job queues) not just because I couldn't afford those services yet, but also because I don't yet need many of the advanced features those services provide. That context matters when reading these posts.

That said, the ability to tailor these features to exactly my needs without having to compromise on the available features or uptime of another service is a distinct benefit that I will not throw away lightly. I did not build features like job queues or email marketing directly into Vesper just because I want to save money. By building them myself, I am able to evolve the features and functionality along with the product itself in a way that I would not be able to with a SaaS product. It will be slower, for sure, but that's a luxury that I can afford now, and that I believe will continue to serve Vesper well far into the future and lead to an application that is every bit as stable as one built on SaaS products, but at a fraction of the monthly cost.

With Vesper, I find myself working in a space that I have not found to be documented very well, because most content you'll find online is focused on absolute beginners, or large enterprise customers. It's actually pretty hard to bridge the gap between the two, but I hope to be able to give a glimpse into what it looks like working in the space between those two extremes.

Kotlin Multiplatform is not optional here

The entire application is enabled by Kotlin Multiplatform. Vesper in its current form — a single codebase running across Android, iOS, and eventually web, with domain logic, contracts, and data models shared between the Compose frontend and the Ktor backend — could not exist without it. Some of these posts will focus heavily on specific Kotlin language features or KMP-specific patterns. Others will spend more time on the problem itself and less on the Kotlin mechanics. Either way, I'll make sure there's at least one concrete Kotlin snippet in every post so it's grounded in something real.

About the source code

Vesper is a closed-source application. The code I share in these posts is the only direct look at the internals you'll get. That said, nothing in the repo is a genuine trade secret — it's just a mobile app, and a relatively low-risk one at that. Several of the components I built are self-contained enough that I'd happily extract and publish them as open-source libraries if there's enough interest. I'll call those out explicitly as I go, and I'll be providing code snippets where relevant. But because most of the code is currently closed-source, don't expect to be able to copy-and-paste any of these code snippets into your project and expect it to work.

The Roadmap

The series will cover many topics cross the full spectrum of a full-stack Kotlin Multiplatform app, including Compose frontend, Ktor+Exposed backend, and infrastructure.

I will update this list with links and new entries as I publish the posts, so bookmark this page or follow me on Dev.to if you want to follow along!

Building Vesper on Ballast: One State Model to Rule Them All
Designing a User Management system with JWTs, Ktor, and Exposed
Theming and Dynamic Font Loading in Compose
Deep-Linking and Navigation with KMP
Domain-Driven Development - The Secret Weapon for Maintainable Apps
Contract-Based Development for Sharing Code between Compose and Ktor

What Is Vesper?

While I am not writing these blog posts as marketing for the app itself, it may be helpful for you to have a bit of insight into the core functionality of the app.

Vesper is a prayer app and a community of Believers carrying each other's burdens. We gather 2 or 3 to join with Jesus in prayer, building a daily rhythm of intercession together.

Vesper works on a system of matching submitted prayers anonymously to other users ready to pray for them. It's intentionally not a social network as there is no concept of following, liking, or replying to prayers. It's just a place for Christians to ask for prayer in their time of need, and for other Christians to build a stronger habit of prayer by interceding for those requests.

If you're a follower of Jesus and would like to join the community, you can sign up for the mailing list or find links to download the app and join the community at vesperapp.cc.

But regardless of what you believe, I hope this deeper look into what it took to build Vesper will be helpful and a blessing to you!

0.21.0 Released

Casey Brooks — Mon, 01 Jun 2020 18:47:50 +0000

Being stuck at home may not be the most exciting, but it has given me lots of time to fix bugs and make Orchid better for you! This latest release, 0.21.0, includes many bug fixes identified (and sometimes fixed!) by the community, and also boasts some significant internal changes which improve Orchid's overall performance and prepare a major portion of its functionality to be pulled into a standalone library (which you'll absolutely want to check out when it's released).

This is the official Orchid newsletter, the newest and best documentation site generator. There is a growing need to keep the community up-to-date on all the happenings around Orchid, and here I will share Orchid's progress, milestones, and future plans! Follow along with this series to stay on top of Orchid's newest features, track adoption on Github, and see who's using Orchid!

On Github

The Orchid community is growing larger all the time, and the repo is now at 367 stars!

Orchid also received contributions from Mikko Värri for improvements to sitemaps, and Javier Segovia Córdoba with documentation fixes.

And thank you to everyone else who has been giving Orchid a try, reaching out with questions and feedback, and generally supporting this growing community!

What's New?

Full release notes and a migration guide are available here. Here's a summary of what to expect in 0.21.0:

Experimental sourcedocs are now enabled by default and do not need a CLI flag to use.
Sourcedocs modules can now cross-link between each other for multi-module projects, or those with multiple interlinked sourcesets (like Kotlin MPP).
Collections have become the base unit of organizing groups of pages in Orchid, and there is now a collectionPages menu item to display pages from a collection from any plugin.
Asset management is greatly improved, and support for downloading and inlining CSS and JS assets is now available from config.yml as well as from plugin code.
Diagnostic output across the board is generally improved. Pebble templates are now more descriptive about errors with better line-number tracking (to aid in resolving specific Pebble template issues), and OrchidTest now only shows HTML selectors from the test instead of the entire rendered page.

In Progress

Continued work is underway to support relative URLs (for viewing an Orchid site without needing a local fileserver). In addition, Orchid's resource/file management is a core subsystem that would do well to be a separate library, and work is in progress to move it out of Orchid and into Arcana, it's own library. This library will be Kotlin multiplatform-enabled, bringing Orchid's simple and flexible file-management APIs to Android, iOS, JS, and of course, pure JVM.

Are you interested in getting started with Orchid? There simply is no better way to manage all the documentation for your project, and I'd love to help you get set up!

If you have an open-source project that needs docs, are building a new portfolio, or are building any other kind of static site, I want to work with you to get you set up with Orchid! Comment on this post, send me a PM here on Dev.to, reach out on Gitter, or contact me here and I will be with you every step of the way.

And as always, let me know if you start using Orchid so I can feature you in the next update!

New Snippets plugin, 0.20.0 Released

Casey Brooks — Mon, 30 Mar 2020 17:33:59 +0000

The next major version of Orchid, 0.20.0, is now available! It includes the first introduction of the long-awaited Snippets plugin, as well as a number of smaller quality-of-life improvements throughout. Check out the full release notes here, and stick around for a general update of the development and community around Orchid!

On Github

Orchid is now at 343 stars on Github, and since the last newsletter has received a PR from Bruno Vernay with some improvements to the formatting of blog post filenames.

I also want to give a special thanks to everyone who provided feedback and suggestions for the new Snippets plugin! Both on the proposal issue and on Gitter, your suggestions are what decided the features to include in this first release, and it's my hope that it will provide exactly the solution you're looking for!

And thank you to everyone else who has been giving Orchid a try, reaching out with questions and feedback, and generally supporting this growing community!

What's New?

This latest release is a continuation of the "quality-of-life" improvements that have been suggested by the you and are making Orchid better and easier to use. Some of these changes required breaking the internal API (thus the major version bump to 0.20.0), but this version does not include any deprecations or breaking changes to the public, end-user features. Below are the new features available in 0.19.0:

New Snippets plugin allows you to lookup and embed snippets from code, files, and even external webpages!
The Admin Panel layout got a minor makeover to make it easier to use and more flexible.
Forms and snippets located during the site build are care listed and can be previewed in the admin panel.
Allows Forms to be embedded with a new form tag, instead of only as Components as before.
Replaces default accordion markup with details/summary HTML5 tag for best usage in all themes
Tabbed TemplateTags can now be rendered dynamically! You can now use loops and conditionals to add individual tabs to the body of tabbed tags, instead of having to have them be statically-determined.
Both the base URL and your theme can now be set in config.yml, instead of needing to be set in your Gradle or Maven build scripts.
Improvements to base URL management now allow plugins to provide "helpers" for determining the base URL, such as OrchidNetlify detecting when Orchid is running on Netlify's CI platform and using its build environment variables to find the base URL.
OrchidPosts now relaxes slightly the strict filename requirements for post files.

Full release notes and a migration guide are available here.

In Progress

The changes allowing base URLs to be set from config.yml, instead of being a flag from the CLI or build plugins, brings us closer to having relative urls for generated links instead absolute as they are now. Relative URLs don't include a base URL, but instead provide a path from the current page to the linked one, and will make it possible to view an Orchid site directly in the filesystem instead of needing to start an HTTP server to view it.

There is still work to be done on this, but it's now considered a mid- to short-term goal for Orchid instead of a long-term one, and it will be a huge win for those of you using Orchid for documentation. Thank you to everyone who has been asking for this, I hope to be able to provide this feature for you soon!

Are you interested in getting started with Orchid? There simply is no better way to manage all the documentation for your project, and I'd love to help you get set up!

And as always, let me know if you start using Orchid so I can feature you in the next update!

0.19.0 Released

Casey Brooks — Sun, 23 Feb 2020 23:37:10 +0000

The next major version of Orchid, 0.19.0, is now available! Check out the full release notes here, and stick around for a general update of the development and community around Orchid!

On Github

Orchid is now at 329 stars on Github, and since the last newsletter has received a PR from tomb50 to improve Orchid's Asciidoctor integration. And thank you to everyone else who has been giving Orchid a try, reaching out with questions and feedback, and generally supporting this growing community!

What's New?

Since the release of 0.18.0, I've been able to work on many smaller "quality-of-life" improvements to Orchid that have been suggested by the community. Some of these changes required breaking the internal API (thus the major version bump to 0.19.0), but the last few releases have mainly just been smaller new features and improvements to existing plugins. Below are the new features available in 0.19.0:

Improve Asciidoc formatting. Specifically, other files relative to the source file can now be included.
Automatically add CNAME files to GithubPages deploys, if not already present in the deployed site. The CNAME value will be inferred from the base URL of the site during the deploy.
Adds feedLinks metaComponent to Posts plugin, which adds <link rel='alternate'> tags to page heads, pointing to the generated feed pages.
Images uploaded and referenced from GitLab wikis are now copied over automatically with the rest of the site

Full release notes and a migration guide are available here.

In Progress

Most work over the past month has been refactoring needed to support a better Asciidoctor experience, and generally clean up some of the older parts of the Orchid codebase. This is work that will eventually be extracted to a separate library, so be on the look-out for that!

There is still work to be done with the Asciidoctor integration, but it's getting better all the time, and work on the Snippets plugin will be picking back up soon, too. I've already had some good feedback and suggestions for this feature which I will be taking into account as I build it out, so be sure to leave your thoughts on the appropriate issue, to make this plugin exactly what you need!

Are you interested in getting started with Orchid? There simply is no better way to manage all the documentation for your project, and I'd love to help you get set up!

And as always, let me know if you start using Orchid so I can feature you in the next update!

January 2020 Orchid Newsletter: Gaining Traction

Casey Brooks — Thu, 23 Jan 2020 16:08:40 +0000

It's so incredible to see this project grow from a tiny seedling to the maturing sprout it is now. Especially since the 0.18.0 release, I've seen more people try out Orchid and adopt it for their documentation sites, and I'm so incredibly grateful for each and every download. But this is only the beginning, Orchid still has lots of growing-up to do, so why don't you come along for the ride and help shape the future of Orchid!

On Github

Orchid has been growing so much since December's 0.18.0 release! Its now at 313 stars and version 0.18.2, with more downloads, new sites, and issues created than ever before! And it's all thanks to this wonderful community of individuals believing in a better way to do documentation, so thank you all!

The holidays were fairly quiet in terms of new releases and contributions, but Tom Beadman helped immensely with improving the asciidoctor integration. A small PR with huge impact for improving the quality-of-life for Asciidoctor fans, which now includes support for include::[] macros!

I also merged work Danilo Pianini had done for improving the YouTube tag to support aspect-ratios instead of fixed sized.

What's New?

Now that 0.18.0 is released, I've been able to work on some smaller features I've been wanting to support for a while. I had to restrain myself from working on them for 0.18.0 to prevent feature-creep, but it's been nice finally getting to add the following features:

The OrchidBible plugin has been broken for some time, as the APIs driving it had been decommissioned. I have removed the previously-broken bible() function, which pre-rendered Bible verses, and replaced it with a new Faithlife Reftagger meta-component, which will automatically create popups for all Bible verses it finds on the page!
Support for Mermaid JS markup has been added to the OrchidDiagrams plugin. As Mermaid is a javascript library, support is added through a meta-component instead of using pre-rendered markup like PlantUML.
The youtube template tag in OrchidWritersBlocks can now display videos of a given aspect-ratio, making them better-suited for responsive designs.
OrchidChangelog now supports single-file changelogs, such as the Keep A Changelog format format.

In Progress

Supporting include macros for Asciidoctor was a huge step forward, but there's still work to be done to improve that integration, and you can expect more Asciidoctor improvements in the coming weeks, with image::[] being the next target.

In addition to a few more quality-of-life improvements planned for the near-future, I've begun work on a new OrchidSnippets plugin! More details will come in a future post, but I'd love to get your feedback and suggestions for its implementation and usage in this issue on GitHub!

Are you interested in getting started with Orchid? There simply is no better way to manage all the documentation for your project, and I'd love to help you get set up!

And as always, let me know if you start using Orchid so I can feature you in the next update!

Make a Personal Blog with Orchid

Casey Brooks — Thu, 12 Dec 2019 16:53:26 +0000

Orchid was created to create amazing project documentation sites, but it is by no means limited to documentation. Orchid is equally good at producing blogs for your portfolio site, or even for adding a newsletter to your docs to further
engage with your users!

This tutorial will walk you through how to create a blog, complete with archives for all your posts, and get it deployed to Netlify. If you want to jump right into a working project, you can find everything described here in the OrchidTutorials example project.

orchidhq / OrchidTutorials

A collection of tutorial projects to help you learn how to use Orchid

Orchid Tutorials

This repo contains the projects used in the official Orchid tutorials. Each project top-level directory here is its own project, and can be run by navigating into that project and running the appropriate commands as described in the Orchid tutorials.

View on GitHub

Alternatively, you can simply click the "Deploy to Netlify" button below to automatically clone, build, and deploy the OrchidStarter repo to the Netlify CDN. Most of what is in this tutorial is also included in that site, so you can follow along with this tutorial using the starter repo as well.

This tutorial was originally posted on https://orchid.run. Visit the original tutorial for the most up-to-date version.

Getting Started

We'll be using Gradle for this project, and Orchid runs as a Gradle plugin. So let's get our settings.gradle and we'll also set up the build.gradle:

// settings.gradle
rootProject.name = 'My Awesome Blog'

// build.gradle
// 1. Apply Orchid plugin
plugins {
    id "com.eden.orchidPlugin" version "0.18.0"
}

// 2. Include Orchid dependencies
dependencies {
    orchidCompile "io.github.javaeden.orchid:OrchidBlog:0.18.0"
    orchidCompile "io.github.javaeden.orchid:OrchidFutureImperfect:0.18.0"
    orchidCompile "io.github.javaeden.orchid:OrchidSearch:0.18.0"
    orchidCompile "io.github.javaeden.orchid:OrchidPluginDocs:0.18.0"
}

// 3. Get dependencies from JCenter
repositories {
    jcenter()
}

// 4. Use the 'FutureImperfect' theme, and set the URL it will have on Github Pages
orchid {
    theme = "FutureImperfect"
    baseUrl = "https://project.netlify.com"
    version = "1.0.0"
}

This is all that's required to run your Orchid site! There are still a few things we need to do to set up the blog, but you can run Orchid right now with ./gradlew orchidServe and view the site on http://localhost:8080. It should give you an output like the following:

./gradlew :docs:orchidServe

> Task :docs:orchidServe
Using the following modules: 
--------------------
 * com.eden.orchid.StandardModule

Auto-loaded modules: 
--------------------
 * com.eden.orchid.editorial.EditorialModule
 * com.eden.orchid.impl.compilers.markdown.FlexmarkModule
 * com.eden.orchid.impl.compilers.pebble.PebbleModule
 * com.eden.orchid.kotlindoc.KotlindocModule
 * com.eden.orchid.pages.PagesModule
 * com.eden.orchid.search.SearchModule
 * com.eden.orchid.wiki.WikiModule

Flag values: 
--------------------
-adminTheme: Default
-baseUrl: https://project.netlify.com
-defaultTemplateExtension: peb
-dest: ...
-dryDeploy: false
-environment: debug
-logLevel: VERBOSE
-port: 8080
-src: ...
-task: serve
-theme: Editorial
-version: 1.0.0

[INFO] Orchid: Running Orchid version 0.16.0, site version unspecified in debug environment
[INFO] OrchidWebserver: Webserver Running at http://localhost:8080
[INFO] OrchidWebsocket: Websocket running at http://localhost:8081/
[INFO] TaskServiceImpl: Build Starting...
[INFO] GeneratorServiceImpl: Indexing [10000: assets]
[INFO] GeneratorServiceImpl: Indexing [1000: home]
[INFO] GeneratorServiceImpl: Indexing [1000: kotlindoc]
[INFO] GeneratorServiceImpl: Indexing [1000: pages]
[INFO] GeneratorServiceImpl: Indexing [1000: wiki]
[INFO] GeneratorServiceImpl: Indexing [11: sitemap]
[INFO] GeneratorServiceImpl: Indexing [10: indices]
[INFO] GeneratorServiceImpl: Generating [10000: assets]
[INFO] GeneratorServiceImpl: Generating [1000: home]
[INFO] GeneratorServiceImpl: Generating [1000: kotlindoc]
[INFO] GeneratorServiceImpl: Generating [1000: pages]
[INFO] GeneratorServiceImpl: Generating [1000: wiki]
[INFO] GeneratorServiceImpl: Generating [11: sitemap]
[INFO] GeneratorServiceImpl: Generating [10: indices]

Build Metrics:
┌───────┬────────────┬───────────────┬─────────────────┬───────────────────────────┬─────────────────────────────┐
│       │ Page Count │ Indexing Time │ Generation Time │ Mean Page Generation Time │ Median Page Generation Time │
├───────┼────────────┼───────────────┼─────────────────┼───────────────────────────┼─────────────────────────────┤
│  home │     1      │     54ms      │      481ms      │           472ms           │            472ms            │
├───────┼────────────┼───────────────┼─────────────────┼───────────────────────────┼─────────────────────────────┤
│ TOTAL │          1 │      3s 496ms │           520ms │                     472ms │                       472ms │
└───────┴────────────┴───────────────┴─────────────────┴───────────────────────────┴─────────────────────────────┘

Build Complete
Generated 1 page in 4s 18ms


Webserver Running at http://localhost:8080
Hit [CTRL-C] to stop the server and quit Orchid

You will also see the basic site served on localhost:8080, which looks like:

But let's move on to the next step: adding content to the site!

Adding Content

Homepage

The first thing anyone will see when landing on your site is your Homepage. Orchid creates this page based on a homepage.md file in the root of your site's resources, which are located by default in src/orchid/resources. Let's start by creating this file and adding a short description of our project to it.

// docs/src/orchid/resources/homepage.md
# My Blog

This is a short description of this blog.

A common thing to add to your blog homepage is a list of your latest blog posts. But before we add that, we'll need to write some blog posts first.

Blog Posts

Blog posts are Markdown files in your posts/ directory, where each file is a separate blog post. The filename of the post must be in the format of YYYY-MM-DD-[post-title].md, with the publication date and the "slug" of the post which will be its path in its URL.

So let's add a few posts, such as posts/2019-01-01-post-one.md, posts/2019-02-01-post-two.md, and posts/2019-03-01-post-three.md. The contents of each file should start with a Front Matter section, where you can specify the post's title, its tags, and other metadata, and the actual post content after that. Front Matter is a block of YAML between pairs of triple-dashed lines.

# posts/2019-01-01-post-one.md
---
title: Example Post 1
featuredImage: assets/media/pic01.jpg
tags:
    - one
    - two
---

Example Post 1

You'll now have a blog post at http://localhost:8080/2019/1/1/post-one that looks like the following;

Now that we have some blog posts set up, we can go back and add the latest posts to our homepage. We can do by adding a component to the homepage's Front Matter, configured to display the latest posts. Orchid's Components are just a list of "blocks" which are rendered to the page in order. There are many different types of components, and different plugins can add their own. An example is the recentPosts component from the OrchidPosts plugin. We can also add the pageContent component, which adds the Markdown content of the homepage.md. If you don't define any components this one is added automatically, but if you use any additional components you'll have to add it yourself.

# homepage.md
---
components:
  - type: pageContent
  - type: recentPosts
    limit: 4
    noWrapper: true
    template:
      - 'includes/postPreview_large'
---
# My Blog

This is a short description of this blog.

Creating Archives

Post Archive

Now, while it is nice to show the most recent posts on your site's homepage, if you've got more than a couple posts you simply can't show a complete archive on the homepage. Instead, we can use the OrchidTaxonomies plugin to generate proper archives.

Orchid is designed around a concept of "collections" of pages. When we set up the blog posts, Orchid also created a posts collection. We can tell the Taxonomies plugin to generate an archive of any of our collections from any plugin, making it simple to create any archives we may need.

Configuring archives is done through a config.yml file in our site resources. This is the main entry-point to configuring anything in our site. The following snippet will set up a collection archive for all our blog posts.

# docs/src/orchid/resources/config.yml
taxonomies:
  collectionArchives:
    - collectionType: 'posts'
      collectionId: 'blog'

Now, if we visit http://localhost:8080/blog, we will see a listing of all our blog posts. As our blog grows, this archive will automatically become paginated, keeping any single page from growing too large.

You may wish to create archives for other collections as well. If you visit http://localhost:8080/admin while your site is serving locally, you can view Orchid's admin panel where we can see a list of all the collections that have been set up for us.

Tag Archives

But the full listing of posts may not be the only kind of archives we want! Most blogs will also contain listings of posts by tag (remember, we provided a list of tags to our posts earlier!). Orchid did not create a collection for these tagged pages, but that doesn't mean we can't create an archive for them too! The Taxonomies plugin is able to generate any kind of arbitrary archive, based on the metadata attached to each post. These are called taxonomy archives, because you get to create any kind of taxonomy (or labelling) you need.

Configuration of a taxonomy archive is similar to a collection archive, but instead of giving it the values for a collection, we tell it a property to look for in our posts' Front Matter, such as tags:

taxonomies:
  collectionArchives:
    - collectionType: 'posts'
      collectionId: 'blog'
  taxonomies:
    - key: tags
      single: false
      orderBy:
        - entryCount

This will now go through all our posts, find any that have a tags property in its Front Matter, and add it to that archive. And this will actually create two archives for each "taxonomy": one listing all the pages with each tag (a term archive), and another archive simply listing all the tags that it found (a taxonomy archive).

http://localhost:8080/tags

http://localhost:8080/tags/one

Site Info/Theme Configuration

With the skeleton of our site content set up, it's time to make some customizations to the theme and add additional info about your site, such as its name and the author of your posts. These can be added to config.yml, just like how we configured the archives.

# docs/src/orchid/resources/config.yml
site:
  about:
    siteName: My Blog
    siteDescription: This is a short description of this blog.
    avatar: 'http://lorempixel.com/320/320/city/'
theme:
  social:
    github: 'username/project'

But these configuration values didn't just come out of nowhere. Going back to the admin panel, you can find all the options available for customization for your theme, for components, and for just about anything else.

There's a final bit of info that we should need to config.yml before finishing: setting the author for all our posts.

You would normally add the necessary configuration to each post's Front Matter, but it is really difficult, time-consuming, and error-prone to copy this data to each post file. Instead, Orchid has Archetypes which allow you to set that configuration once in config.yml and have it shared amongst a bunch of pages just as if it were added to the Front Matter of each one.

For adding configuration values to all post pages, use posts.postPages in the config.yml. We'll add an author to the blog by adding an item to the posts.authors list, and using the archetype we'll set the author for each page to the one you just set up:

# docs/src/orchid/resources/config.yml
posts:
  authors:
    - name: 'Author One'
      avatar: 'http://lorempixel.com/320/320/animals/'
      email: 'email@domain.tld'
  postPages:
    author: 'Author One'

Deploy On Netlify

Our site is now ready to be deployed! For blogs and personal sites, you really can't go wrong with Netlify as your site host. It offers everything you could want for both small and large sites, such as purchasing custom domains, form handling, and automated site deploys. While Orchid has its own Netlify publisher for advanced use cases, it's far simpler to use Netlify as intended.

All you need to do is create an account at https://www.netlify.com/, add a netlify.toml file to the root of your repo with the following content, and push to GitHub.

[build]
  base    = ""
  publish = "build/docs/orchid"
  command = "./gradlew orchidBuild -Penv=prod"

Now, once you've connected that repo to Netlify, they will take care of the rest! Of course, this is just the minimum needed to deploy, and I'd encourage you to also check out their full documentation for more help building and deploying your Orchid site on Netlify.

Conclusion

And with all that, our blog site is finished! Now it may have seemed like a ton of work getting all that setup, but let's recall all the features included in this site:

A homepage that displays our latest blog posts
A full, paginated archive of all blog posts
A listing of all tags in your blog
An archive for all the pages with each tag
Ability to set the author for each post
Ability to easily change the configurations for all your blog posts from a single location, instead of copying data to each post

And everything outlined in this tutorial is really just a sampling of the full functionality available in Orchid! Orchid has other plugins for different source code documentation, presentations, wikis, and much more. Check out the full list of plugins here, or you can even make your own!

Thanks for following along, happy blogging!

Orchid 0.18.0, The New Face of Orchid

Casey Brooks — Tue, 10 Dec 2019 16:12:46 +0000

It's. Finally. Here. I've been working on and teasing a new major version of Orchid for several months, and it's finally available! This release represents a major step in the maturity of Orchid, coming alongside the move to a new GitHub organization, a completely redesigned website, and a brand new logo!

orchidhq / Orchid

Build and deploy beautiful documentation sites that grow with you

Build and deploy beautiful documentation sites that grow with you

Quick-Start • Documentation • Tutorials • Showcase • Support

Quick-Start

Orchid 0.X.X versions are published to JCenter at artifact coordinates like io.github.javaeden.orchid:OrchidCore:0.21.1 or io.github.javaeden.orchid:OrchidWiki:0.21.1. JCenter is deprecated, and once Orchid 1.0.0 is published, so will all 0.X.X versions.

Starting with version 1.0.0, Orchid will be published to MavenCentral under new artifact coordinates, like io.github.copper-leaf.orchid:orchid-core:1.0.0 or io.github.copper-leaf.orchid:orchid-wiki-feature:1.0.0.

In-development snapshot versions will be available in Sonatype's new (s01) snapshots repository. Snapshots are published after every successful build on the dev branch.

Documentation

Orchid's User Manual will walk you through the main features of Orchid and give you a deeper understanding of each topic and feature.

Documentation

Tutorials

There are several tutorials designed to walk you through building an Orchid site from scratch. The source for all tutorials can also be found in the OrchidTutorials repository.

Tutorials

Showcase

View…

View on GitHub

On Github

As of the time of writing, Orchid is at 278 stars on Github, thank you so much for all the support!

Since the last update, Orchid has had several contributions, especially during Hacktoberfest, so a special thanks goes out to the following individuals for their help improving this project:

spind42 - Fixed an issue running Orchid from Maven
Jean-Michel Fayard - Added a readme badge for CodeTriage
Steve S - Added a new Spotify tag to the OrchidWritersBlocks plugin
Steve Waldman - Wrote a plugin to run Orchid from SBT!

What's New?

The long-awaited version 0.18.0 has finally arrived!

This release includes a major cleanup to Orchid's internal APIs, which will help make better plugins moving forward, but most importantly introduces the new, completely rewritten code documentation system based on Kodiak. The new system improves consistency of generated docs among all languages and enables multi-module documentation. It also paves the way to make it significantly easier to develop integrations for other languages, so let me know which languages you would like to see supported by Orchid!

Be sure to check out the Changelog for the full list of changes, and the Migration Guide for help updating to this new version.

In addition, some of you may have noticed a few changes around the Orchid ecosystem! The Orchid repo has been moved to @orchidhq on Github, and we have a completely redesigned documentation site and new logos. Together with the 0.18.0 release, this marks the biggest change in the development and ecosystem of Orchid to help cement it is as the single-best tool for producing documentation websites.

You can help spread the word about this major milestone by sharing https://orchid.run and tagging @OrchidSSG on Twitter!

Who's Using Orchid?

I periodically search GitHub to find new projects getting set up with Orchid. Here are a couple great examples of projects being documented with Orchid:

For more examples of sites using Orchid, head on over to our new Showcase, and feel free to reach out or submit a PR to add your site to the showcase as well!

Are you interested in getting started with Orchid? There simply is no better way to manage all the documentation for your project, and I'd love to help you get set up!

And as always, let me know if you start using Orchid so I can feature you in the next update!

Orchid Newsletter: Summer Recap

Casey Brooks — Wed, 11 Sep 2019 17:11:21 +0000

Sorry for the absence, it's been a very busy summer for me! Lots of stuff going on both for me and for Orchid, so stick around to see what's coming up!

This is a monthly newsletter around Orchid, the newest and best static site generator for the JVM. There is a growing need to keep the community up-to-date on all the happenings around Orchid, and here I will share Orchid's progress during the previous month! Follow along with this series to stay on top of Orchid's newest features, track adoption on Github, and see who's using Orchid!

orchidhq / Orchid

Build and deploy beautiful documentation sites that grow with you

Build and deploy beautiful documentation sites that grow with you

Quick-Start • Documentation • Tutorials • Showcase • Support

Quick-Start

In-development snapshot versions will be available in Sonatype's new (s01) snapshots repository. Snapshots are published after every successful build on the dev branch.

Documentation

Orchid's User Manual will walk you through the main features of Orchid and give you a deeper understanding of each topic and feature.

Documentation

Tutorials

There are several tutorials designed to walk you through building an Orchid site from scratch. The source for all tutorials can also be found in the OrchidTutorials repository.

Tutorials

Showcase

View…

View on GitHub

On Github

As of the time of writing, Orchid is at 233 stars on Github, thank you so much for all the support! And a special thanks goes to the following individuals who submitted pull requests to Orchid!

I've also been preparing for Hacktoberfest, which is coming up in less than a month. I've curated a bunch of new issues labeled for first-time contributors, how about getting a head-start on Hacktoberfest and helping out with some of these issues? 😎 Feel free to hold off on your PR until Hacktoberfest officially begins, just comment on the issue so others know what you're working on.

What's New?

Orchid is now at version 0.17.4. 0.17.0, which came out at the end of May, was a really big update and included a handful of new "integrations" projects. These integrations make it easy to create wikis from Github and Gitlab wikis, and to publish your site to Gitlab Pages and Bitbucket Cloud (in addition to the already-supported Github and Netlify publishers).

In Progress

Y'all. Some big things are just up the road for Orchid. Really big. Like, Texas-sized big. I'm talking about:

A completely redesigned documentation site (you can preview it here, I'd greatly appreciate any feedback on it!)
Mutli-module code documentation
Completely decoupling code documentation from Orchid with Kodiak, to vastly simplify the process of supporting new languages and ensure consistency of usage across all languages
Some much-needed refactoring of core Orchid functionality
A new framework for automated testing of Orchid plugins and themes
Migrating to GitHub Actions for continuous releases

All this will be coming in the upcoming 0.18.0 release. While I don't want to put a date on this release (I don't want to release it until it's 100% ready-to-go), I can say that I'm nearly code-complete with the changes I wanted to add. From here, it's mostly just adding the finishing touches to the new site, documenting the new functionality, and testing everything thoroughly.

Are you interested in getting started with Orchid? There simply is no better way to manage all the documentation for your project, and I'd love to help you get set up!

And as always, let me know if you start using Orchid so I can feature you in next month's update!

Orchid Newsletter: In Bloom

Casey Brooks — Tue, 07 May 2019 21:08:12 +0000

April has just ended, which means summer is coming! April in Texas means lots of rain, the first hot days of summer, and bluebonnets in bloom along every highway. It's also been a relatively slow month for Orchid, but lots of really cool stuff is just about to bloom here too!

orchidhq / Orchid

Build and deploy beautiful documentation sites that grow with you

Build and deploy beautiful documentation sites that grow with you

Quick-Start • Documentation • Tutorials • Showcase • Support

Quick-Start

In-development snapshot versions will be available in Sonatype's new (s01) snapshots repository. Snapshots are published after every successful build on the dev branch.

Documentation

Orchid's User Manual will walk you through the main features of Orchid and give you a deeper understanding of each topic and feature.

Documentation

Tutorials

There are several tutorials designed to walk you through building an Orchid site from scratch. The source for all tutorials can also be found in the OrchidTutorials repository.

Tutorials

Showcase

View…

View on GitHub

On Github

As of the time of writing, Orchid is at 196 stars on Github. Just 4 more stars until the next major milestone of 200, will you help us get there?

What's New?

Orchid is now at version 0.16.10, with a few minor updates released throughout the month.

Orchid no longer includes any Lombok code, for a more stable codebase and a better roadmap for converting the remaining Java code to Kotlin.
Relative base URLs are now supported
Adds baseUrl and homepageUrl filters to be more tolerant when formatting ad-hoc URLs
Updates to Pebble 3.0.9, which includes the embed tag I contributed to that project. This will go a long way in improving theme development in Orchid
Improved error-handling

In Progress

I've been pretty busy in April and haven't had as much time to dedicate to Orchid development. One of my other hobbies is woodworking, and I've been taking some time in this nice weather to build a new coffee table as a late Christmas present to my wife. I'm pretty proud of my work on it, it's teaching me some skills that are valuable in software development, and you can keep an eye out for a blog post on that! Here's my progress on this build so far:

But despite that, I'm also making some great progress toward the next major release, 0.17.0! This will be a significant refactoring and improvement of the wiki and deployment features in Orchid to allow better integrations with all the major Git hosting platforms and pave the way for easier integration of similar features in the future.

It's a pretty significant change and is taking a lot of work, but I have a goal of finally getting it out this month! Here's the full list of features that you can expect in this release:

Netlify deploys optimized for really large sites, and able to upload serverless Functions
Deploy site to GitHub, Bitbucket, GitLab, or Azure DevOps (currently, only GitHub is supported)
Import wiki content directly from GitHub Wikis

Are you interested in getting started with Orchid? There simply is no better way to manage all the documentation for your project, and I'd love to help you get set up!

If you have an open-source project that needs docs, are building a new portfolio, or are building any other kind of static site, I want to work with you to get you set up with Orchid! Comment on this post, send me a PM here on Dev.to, or contact me here and I will be with you every step of the way.

And as always, let me know if you start using Orchid so I can feature you in next month's update!

Orchid Newsletter: March Madness

Casey Brooks — Wed, 03 Apr 2019 15:56:32 +0000

I love watching basketball, which makes March one of the best months of the year as the NCAA National Championship, March Madness, takes place. My top pick, Michigan State, has already defeated Duke and is well on their way to becoming the National Champions!

It has also been quite a "mad" month for Orchid too, with lots of big changes in progress. From being able to publish your site to Gitlab and Bitbucket, to integration with Github Wikis, and a re-theming of the documentation site all underway, it's safe to say that I've been quite busy!

orchidhq / Orchid

Build and deploy beautiful documentation sites that grow with you

Build and deploy beautiful documentation sites that grow with you

Quick-Start • Documentation • Tutorials • Showcase • Support

Quick-Start

In-development snapshot versions will be available in Sonatype's new (s01) snapshots repository. Snapshots are published after every successful build on the dev branch.

Documentation

Orchid's User Manual will walk you through the main features of Orchid and give you a deeper understanding of each topic and feature.

Documentation

Tutorials

There are several tutorials designed to walk you through building an Orchid site from scratch. The source for all tutorials can also be found in the OrchidTutorials repository.

Tutorials

Showcase

View…

View on GitHub

On Github

As of the time of writing, Orchid is at 175 stars on Github. And this month, in particular, I have been absolutely blown away at the growth on Github. With 4 pull requests by 3 contributors, numerous issues opened and questions asked across Github, Twitter, and Gitter, and more than FOUR TIMES as many downloads on Bintray this month as last month, Orchid is seeing unprecedented growth that I could never have imagined.

Thank you all so much, I certainly could not keep working this hard without your incredible support! But these successes are entirely because of you, and I love to give credit where it is due, so let's drill into this a bit deeper.

Contributions

@alejandrohdezma helped out to fix a bug using the wrong FontAwesome icon (#239)
@ Sumo99 got rid of the last of Lombok, paving the way for a pure-Kotlin future! They also helped remove Google Plus social links now that the service is officially dea. (#243 and #249)
@ dkowis fixed a broken documentation link (#252)

4x Downloads Increase

The 31-day period ending February 28th saw a bit shy of 700 downloads.

The stats show that downloads really started to take off around the end of the month, which is when I published the tutorial on how to use Orchid to document a Kotlin project. I would highly recommend you check it out if you haven't already.

Casey Brooks

Feb 18 '19

How To Document A Kotlin Project

#kotlin #documentation #orchid

14 min read

Meanwhile, The 31-day period ending March 31st saw more than 2600 downloads! And questions from y'all on how to use it have increased to match, and I'm so excited to be able to help solve your problems with Orchid!

All of these statistics are freely available on Bintray, go here to check it out for yourself.

What's New?

Orchid is currently at version 0.16.7. There have been no major changes since last month, mostly just a series of bugfixes on the Copper theme and minor usability improvements.

Coming Soon

New Docs

Orchid's docs are getting a reboot! When I started work on Orchid, Bootstrap was the only CSS framework I knew of. I had no idea there were so many great options out there, and ultimately I have come to really enjoy Bulma for its simplicity and flexibility.

And so, I've been building the "Copper" theme, based on Bulma, to serve as the home for all of Orchid's own documentation, and also of its supplemental libraries. Here's a preview:

Also coming with the new theme will be a major overhaul in the content on the docs site, as I continue to iterate upon the docs and figure out the best way to present the information to you.

More Integrations

From the very beginning, Orchid was created to be infinitely flexible, able to work with a wide variety of different systems and content structures, but until now it has been fairly closely tied to just Netlify and GitHub. I myself regularly use Microsft Azure and BitBucket at work and want to use Orchid in those places, and I can imagine y'all do as well.

So work is currently under way to make it easier to integrate Orchid into those different Git platforms, so you do not need to change your current processes to fully utilize Orchid's power! Soon, you'll be able to use the native Wikis on Github, Bitbucket, Gitlab, and Azure DevOps as a headless CMS, and you'll also be able to deploy directly to their static hosting platforms and create releases!

Get Involved

You don't have to be an expert in Java, Kotlin, Orchid, or anything else to help out the Orchid project. There are a number of ways you can contribute right now:

fixing typos and improving the clarity of documentation articles
converting Java classes to Kotlin

However, I am currently looking for more skilled help with a couple specific areas:

I'm looking for people who currently use the features of the git platforms I'm imtegrating with, to help build their integrations:
- GitLab
  - Wiki adapter
  - GitLab Pages Publisher
- Bitbucket
  - Wiki adapter
  - Bitbucket Cloud Publisher
- Azure DevOps
  - Wiki adapter

I would also love the help of a designer to make a really great home page and a new logo for Orchid.

Please reach out to me if you're interested in contributing to the project for any of these specific issues, I (and the whole community!) would really appreciate it!

Are you interested in getting started with Orchid? There simply is no better way to manage all the documentation for your project, and I'd love to help you get set up!

If you have an open-source project that needs docs, are building a new portfolio, or are building any other kind of static site, I want to work with you to get you set up with Orchid! Comment on this post, send me a PM here on Dev.to, or contact me here and I will be with you every step of the way.

And as always, let me know if you start using Orchid so I can feature you in next month's update!

DEV Community: Casey Brooks

Designing a User Management system with JWTs, Ktor, and Exposed

Identity vs Authentication vs. Authorization

Why You Still Need Your Own User System

Getting a JWT into the Client

Securing server routes with JWTs

The structure of a JWT

Authentication

Authorization

Determining Identity

Database Schema

Matching JWTs to Users

Why sub, not email, is the stable link

Tying it all together

Client-side Flow

Server-side Flow

PS: A note on opaque tokens

Building Vesper on Ballast: One State Model to Rule Them All

What Ballast Is and Why I Built It

The Contract Pattern in Practice

Application-Wide State

The Same Pattern on the Server

Why This Matters for Vesper

Vesper Design Diaries: Building a Production-Grade KMP App on a Bootstrap Budget

A bit of context

Who these posts are for

Kotlin Multiplatform is not optional here

About the source code

The Roadmap

What Is Vesper?

0.21.0 Released

On Github

What's New?

In Progress

New Snippets plugin, 0.20.0 Released

On Github

What's New?

In Progress

0.19.0 Released

On Github

What's New?

In Progress

January 2020 Orchid Newsletter: Gaining Traction

On Github

What's New?

In Progress

Make a Personal Blog with Orchid

orchidhq / OrchidTutorials

A collection of tutorial projects to help you learn how to use Orchid

Orchid Tutorials

Getting Started

Adding Content

Homepage

Blog Posts

Creating Archives

Post Archive

Tag Archives

Site Info/Theme Configuration

Deploy On Netlify

Conclusion

Orchid 0.18.0, The New Face of Orchid

orchidhq / Orchid

Build and deploy beautiful documentation sites that grow with you

Quick-Start

Documentation

Tutorials

Showcase

On Github

What's New?

Who's Using Orchid?

Orchid Newsletter: Summer Recap

orchidhq / Orchid

Build and deploy beautiful documentation sites that grow with you

Quick-Start

Documentation

Tutorials

Showcase

On Github

What's New?

In Progress

Why `sub`, not `email`, is the stable link