DEV Community: Michael Odhiambo

Building with AI: A Deep Dive Into My Gemini-Powered Projects

Michael Odhiambo — Sun, 07 Dec 2025 21:38:41 +0000

Over the year, I’ve been experimenting with AI APIs, search engines, and creative automation — using Gemini, Hugging Face, GitHub integrations, and Google Programmable Search to build practical apps that solve real problems.
What started as small experiments grew into a collection of fully functional tools: storytelling apps, retrieval-only assistants, virtual try-on platforms, and multi-category AI quiz systems.

This is a breakdown of each project, the problems they solve, and the technologies behind them.

1. StoryLoom

StoryLoom is a storytelling platform designed for kids, teens, and anyone who loves creative narratives. The user chooses a theme, age range, and prompt, and the system generates:

A complete, original story
A matching AI-generated cover image
A comprehension quiz
Vocabulary flashcards
Translations into multiple languages
A read-aloud mode with customizable voices

Tech Behind the App

Frontend: React
Backend: Python Flask
AI Providers:

Primary: Gemini 2.0 Flash
Fallback: Hugging Face (Mixtral-8x7B)
Images: Hugging Face Image API

The core idea is reliability. If Gemini is available, the app uses it. If Gemini fails or isn’t configured, it falls back automatically to Hugging Face — no interruptions, no manual switching.

Why fallback matters:

Works even with free-tier API limits
Eliminates downtime
Avoids single-provider dependency

This project taught me a lot about multi-provider orchestration, structured prompting, and synchronizing text + image pipelines.

2. QuizBaze

QuizBaze was born from exam week pressure, trying to answer Quizlet flashcard questions quickly without flipping through dozens of sets manually.

This app doesn’t “generate” answers.
It only retrieves from Quizlet flashcards, guaranteeing zero hallucination.

How It Works

User enters a flashcard question
The system uses Google Custom Search Engine to find matching Quizlet pages
It scrapes only the answer portion
If no match exists, it returns “Not found.”

What Makes It Unique

🔒 Retrieval-locked (no AI guessing)
⚡ Fast, direct answers
🎯 Exact matches from Quizlet only
🚫 Zero hallucinations

This project highlights how powerful “search + extraction” systems can be even without model training.

3. StyleAI Studio

This is the most ambitious app in the list.
StyleAI Studio reimagines how users interact with fashion — for both individuals and businesses.

For Personal Users

Upload a photo of yourself
Upload clothing items
Generate a realistic try-on image
Manage your digital wardrobe
Auto-save your outfit history to your Google Drive

For Business Users

Upload mannequins + product photos
Add a description
Generate AI-powered product catalog images
Organize all business assets in a dedicated Google Drive folder

Tech Used

Gemini (for generation + transformations)
Google Drive API (personal + business storage)
Node/React (presentation layer)
Python backend (for image workflows)

This project pushed the limits of file handling, secure user asset storage, and realistic image manipulation.

4. QuizMate

QuizMate is a study companion that mixes retrieval, summarization, question generation, and flashcards into a single workflow. It turns any piece of content into structured learning material.

It uses:

Gemini for summarization + quiz generation
Optional search integrations for external material

A more flexible, personalized version of Quizlet + ChatGPT in one app.

5. Quiz Master

Quiz Master is an interactive quiz platform built with React (frontend) and Python FastAPI (backend). It combines traditional trivia APIs with Gemini-generated questions.

Features

Multiple categories: animals, sports, food, geography, trivia, etc.
Two modes:
- Facts Mode: standard Q&A
- Identify Mode: image-based guessing
AI-enhanced questions: Gemini generates variations, difficulty levels, and new questions
Real images: pulled from public APIs (e.g., TheMealDB, country flag APIs, animal APIs)
Scoring, review, and clean UI

Tech Stack

React
FastAPI
Gemini API
Third-party data sources

This app demonstrates how AI + external APIs + structured content can blend into a smooth quiz experience.

Why I Built These Projects

Each app solved a real need:

StoryLoom → creative storytelling and learning tools
QuizBaze → fast retrieval during tight deadlines
StyleAI Studio → a full AI-powered fashion workflow
QuizMate → personalized study automation
Quiz Master → fun but educational quiz generation

They also helped me explore:

Multi-provider AI systems
Retrieval-based AI (RAG without embedding models)
Vision + text generation
Search engine automation
Secure file storage with Google Drive
Python/Flask, FastAPI, React full-stack architectures

🔐 Layered JWT + RBAC Authorization in Ktor: My Scalable Approach

Michael Odhiambo — Sun, 20 Jul 2025 10:31:54 +0000

Tags: #ktor #kotlin #backend #security #authentication #rbac

Modern backend development requires a secure and scalable approach to authentication and authorization. While Ktor provides a built-in way to handle authentication using Principal, I ran into issues getting it to reliably extract claims from JWT headers. So I built my own layered RBAC strategy — and it turned out to be both clean and powerful.

In this post, I’ll walk you through:

✅ Why I used manual role checks (RBAC)
🔐 How I layered JWT + Role access for security
📦 How to make this structure scalable and maintainable

🎯 The Problem

Ktor’s default Principal-based JWT setup is elegant — but if the pipeline is misconfigured (or the JWT structure isn't what it expects), things silently fail.

In my case, the Authorization headers weren’t reliably read, and call.principal() was returning null even when tokens were valid. Debugging was messy.

I needed:

A top-level gate: only valid JWTs allowed.
Fine-grained role checks: only specific roles allowed per route.

🧱 The Architecture: Two-Layer Auth

I decided to split my authorization into two clean layers:

🧭 Layer 1: Global JWT Authentication

This layer ensures only requests with valid tokens reach the routes.

authenticate("jwt") {
    // All secured routes go here
}

This acts like the main gatekeeper — the "watchman" who checks if you're allowed inside the compound.

🔑 Layer 2: Role-Based Access Control (`withRole`)

Once authenticated, I use a helper function to extract the user's role and allow or deny based on the endpoint.

suspend fun withRole(
    call: ApplicationCall,
    jwtService: JwtService,
    vararg allowedRoles: UserRole,
    handler: suspend () -> Unit
) {
    val userRole = extractUserRoleFromToken(call, jwtService)
    if (userRole == null || userRole !in allowedRoles) {
        call.respond(HttpStatusCode.Forbidden, "Access denied")
        return
    }
    handler()
}

This gives me explicit control over who can access what.

🔍 Token Extraction: No Hidden Magic

suspend fun extractUserRoleFromToken(call: ApplicationCall, jwtService: JwtService): UserRole? {
    val header = call.request.headers[HttpHeaders.Authorization]
    val token = header?.removePrefix("Bearer ")?.trim() ?: return null

    return try {
        val jwt = jwtService.jwtVerifier.verify(token)
        val role = jwt.getClaim("role").asString()
        UserRole.valueOf(role)
    } catch (e: Exception) {
        null
    }
}

I also extract the user's email similarly for profile-based actions.

🛠️ Usage Example

Here’s how I use it in my routing logic:

authenticate("jwt") {
    route("/users") {
        get {
            withRole(call, jwtService, UserRole.ADMIN, UserRole.USER) {
                call.respond(userService.getAllUsers())
            }
        }

        get("/me") {
            val email = extractUserEmailFromToken(call, jwtService)
            call.respond(userService.getUserByEmail(email))
        }

        get("/{id}") {
            withRole(call, jwtService, UserRole.ADMIN) {
                val id = call.parameters["id"]?.toIntOrNull()
                call.respond(userService.getUserProfile(id))
            }
        }
    }
}

Simple. Clear. Testable.

📈 Scalable and Maintainable

This setup allowed me to:

✅ Separate authentication from authorization
✅ Apply access control per endpoint or entire route groups
✅ Log and debug every step
✅ Avoid the fragility of the Principal pipeline

Bonus: Group Wrappers

I could easily wrap entire routes:

fun Route.adminOnly(jwtService: JwtService, block: Route.() -> Unit) {
    route("") {
        intercept(ApplicationCallPipeline.Call) {
            val role = extractUserRoleFromToken(call, jwtService)
            if (role != UserRole.ADMIN) {
                call.respond(HttpStatusCode.Forbidden)
                finish()
            }
        }
        block()
    }
}

✅ Final Thoughts

If you're hitting weird issues with Principal, or just want more explicit, testable control over your routes, try this layered approach.

Top layer (authenticate("jwt")) ensures only valid tokens proceed.
Inner layer (withRole) checks fine-grained access.
Bonus wrappers like adminOnly {} make the routing cleaner.

Security doesn’t have to be abstract. Sometimes, simple, readable code wins.

🔗 Got Feedback?

Would love to hear how you're handling auth in Ktor — or improvements I can make to this structure. Drop your thoughts below! 🚀

Breaking Circular Dependencies in Kotlin with the Mediator Pattern

Michael Odhiambo — Sun, 13 Jul 2025 07:08:02 +0000

Have you ever run into a StackOverflowError when starting your application and wondered what went wrong? If you're working with dependency injection in Kotlin, chances are you've encountered the dreaded circular dependency problem. In this post, I'll share how I solved this issue in a real-world application using the Mediator Pattern.

The Problem: When Dependencies Go Round and Round

Picture this scenario: You have two repositories that need each other to function properly.

TokenRepositoryImpl needs UsersRepository to look up user profiles
UsersRepositoryImpl needs TokenRepository to invalidate tokens

This creates a classic chicken-and-egg problem. When your dependency injection framework (in my case, Koin) tries to create these objects, it gets caught in an infinite loop:

To create TokenRepositoryImpl, it needs to create UsersRepository first
To create UsersRepository, it needs to create TokenRepository first
Back to step 1, and... 💥 BOOM! StackOverflowError

Here's what that looks like in the wild:

Exception in thread "main" java.lang.StackOverflowError
    at kotlin.reflect.jvm.internal.KClassImpl.hashCode(KClassImpl.kt:306)
    at java.base/java.util.concurrent.ConcurrentHashMap.get(ConcurrentHashMap.java:936)
    at org.koin.ext.KClassExtKt.getFullName(KClassExt.kt:25)
    ...many more lines of recursive calls...

The Solution: Enter the Mediator Pattern

The mediator pattern is a behavioral design pattern that reduces coupling between components by making them communicate indirectly through a mediator object. It's perfect for breaking circular dependencies!

Let me walk you through how I implemented this pattern in a Kotlin/Koin project:

Step 1: Create a Mediator Interface

First, I defined an interface that declares methods both repositories need from each other:

interface TokenUserMediator {
    /**
     * Invalidates the refresh token for a user.
     */
    fun invalidateUserTokens(username: String): Pair<Boolean, String?>

    /**
     * Retrieves a user profile by username.
     */
    fun getUserByUsername(username: String): Profile?
}

This interface serves as a contract that both repositories can depend on, breaking the direct dependency between them.

Step 2: Implement the Mediator

Next, I created an implementation that delegates calls to the appropriate repositories:

class TokenUserMediatorImpl : TokenUserMediator, KoinComponent {
    // Use Koin's lazy injection
    private val tokenRepository: TokenRepository by inject()
    private val usersRepository: UsersRepository by inject()

    override fun invalidateUserTokens(username: String): Pair<Boolean, String?> {
        return tokenRepository.invalidateUserTokens(username)
    }

    override fun getUserByUsername(username: String): Profile? {
        return usersRepository.getUserByUsername(username)
    }
}

The magic here is using Koin's inject() function which lazily resolves dependencies only when the methods are called, not when the mediator is constructed. This breaks the initialization deadlock!

Step 3: Update Your Repositories

Now, I modified both repositories to depend on the mediator interface instead of directly on each other:

// TokenRepositoryImpl now depends on the mediator
class TokenRepositoryImpl(
    private val mediator: TokenUserMediator
): TokenRepository {
    // ...existing code...

    override fun extractUserFromToken(call: ApplicationCall): Profile? {
        // ...when we need user info...
        return mediator.getUserByUsername(username)
    }
}

// UsersRepositoryImpl also depends on the mediator
class UsersRepositoryImpl(
    private val mediator: TokenUserMediator
) : UsersRepository {
    // ...existing code...

    override fun deleteUser(username: String): Pair<Boolean, String?> {
        // ...when we need to invalidate tokens...
        mediator.invalidateUserTokens(username)
        // ...
    }
}

Step 4: Wire It Up in Your DI Container

Finally, I updated the Koin module to register the mediator first, then the repositories:

val appModule = module {
    // Register the mediator to break circular dependencies
    single<TokenUserMediator> { TokenUserMediatorImpl() }

    // Repositories that use the mediator
    single<TokenRepository> { TokenRepositoryImpl(get()) }
    single<UsersRepository> { UsersRepositoryImpl(get()) }

    // Other components...
}

How It Works: Breaking the Loop

Let's visualize what we've done:

Before (circular dependency):

TokenRepository ──────► UsersRepository
      ▲                      │
      └──────────────────────┘

After (with mediator):

             TokenUserMediator
                 (Interface)
                ▲           ▲
               /             \
              /               \
TokenRepository             UsersRepository
              ▲               ▲
               \             /
                \           /
             TokenUserMediatorImpl

When the application starts:

Koin creates the TokenUserMediator implementation first
Then it creates both repositories, injecting the mediator into them
When repository methods are called, the mediator's methods handle the communication
The mediator lazily resolves the actual repositories only when needed

The Benefits: Why You Should Care

This pattern isn't just about fixing errors - it offers several advantages:

Clean Architecture: Your code becomes more modular and follows the Dependency Inversion Principle.
Easier Testing: You can test components in isolation by mocking the mediator.
Improved Maintainability: Adding new interactions between repositories becomes simpler - just add methods to the mediator.
Scalability: This pattern works well as your codebase grows, keeping dependencies manageable.

Alternative Approaches

While I found the Mediator Pattern to be the most elegant solution, there are other ways to tackle circular dependencies:

Service Locator: Similar to the mediator but more generic, allowing components to look up dependencies.
Extract Interface: Create interfaces for both components and depend on those instead.
Setter Injection: Use constructor injection for one dependency and setter injection for the other.
Refactoring: Sometimes the best solution is to restructure your code to eliminate the circular dependency entirely.

Real-World Implementation

In my project, this solution resolved a nasty StackOverflowError that was preventing the application from starting. The codebase became more maintainable, and I could add new features without worrying about circular dependencies.

Here's what the actual implementation looked like in my Kotlin backend:

// TokenRepositoryImpl
override fun extractUserFromToken(call: ApplicationCall): Profile? {
    return try {
        val authorizationHeader = call.request.headers[HttpHeaders.Authorization]
        if (authorizationHeader.isNullOrBlank() || !authorizationHeader.startsWith("Bearer ")) {
            logMessage("No Authorization header found or invalid format")
            return null
        }

        val accessToken = authorizationHeader.removePrefix("Bearer ").trim()
        val username = getUsernameFromToken(accessToken)
        if (username != null) {
            return mediator.getUserByUsername(username)  // Using the mediator!
        }
        null
    } catch (e: Exception) {
        logMessage("Error extracting user from token: ${e.message}", LogType.ERROR)
        null
    }
}

// UsersRepositoryImpl
override fun completePasswordReset(token: String, newPassword: String): Pair<Boolean, String?> {
    return transaction {
        try {
            // ... validation logic ...

            mediator.invalidateUserTokens(username)  // Using the mediator!

            // ... rest of the implementation ...

            Pair(true, null)
        } catch (e: Exception) {
            Pair(false, "Error completing password reset: ${e.message}")
        }
    }
}

Conclusion

The mediator pattern is a powerful tool for breaking circular dependencies in your Kotlin applications. While it does introduce an extra layer of abstraction, the benefits in terms of cleaner architecture and avoiding runtime errors make it well worth the effort.

Next time you encounter a circular dependency problem, give the mediator pattern a try. Your codebase (and your sanity) will thank you!

Have you faced circular dependency issues in your projects? What solutions have you tried? Let me know in the comments!

Code examples in this post are from a real-world Kotlin backend application using Koin for dependency injection. The pattern can be applied in similar ways to other languages and frameworks.

🤖 API vs Endpoint - What's the Difference? (With Real Full-Stack Code)

Michael Odhiambo — Sat, 12 Jul 2025 18:30:27 +0000

If you're building a full-stack application using frontend frameworks and a backend like Ktor, chances are you're working with APIs and endpoints every day. But what exactly is an API? And how is it different from an endpoint?

Many developers use these terms interchangeably — but there's a meaningful difference. In this blog, we’ll demystify them using real working code from a Kotlin Ktor backend and a TypeScript frontend.

🔍 What is an API?

API stands for Application Programming Interface.

In simple terms, an API is a set of rules that allows different software systems to communicate. In a web app, this usually means a frontend talks to a backend using HTTP requests.

✅ The API is defined in the backend.

✅ The API includes all the routes (endpoints) your backend exposes — like /login, /register, /getUser, etc.

🔗 What is an Endpoint?

An endpoint is a specific route or URL within your API that performs a particular function. Think of your API as a restaurant menu, and each endpoint is one dish you can order.

Example:

/login is one endpoint.
/register is another endpoint.

Every endpoint is part of an API, but the API is the whole collection of those endpoints.

🧠 Quick Comparison

Concept	Defined In	Description	Example
API	Backend	Full set of functions the backend exposes	Auth API
Endpoint	Backend	A specific function (route) within the API	POST `/login`
API Call	Frontend	A function that sends requests to an endpoint	`axios.post(...)`

📦 Real Backend Code (Ktor API Endpoint)

This is how we define the POST /login endpoint in Kotlin using Ktor:

routing {
    post("/login") {
        try {
            val loginRequest = call.receive<LoginRequest>()
            val (loginResponse, errorMessage) = authService.login(loginRequest)

            if (loginResponse != null) {
                logMessage("Login successful for user: ${loginResponse.profile.email}", LogType.INFO)
                call.respond(loginResponse)
            } else {
                logMessage("Login failed for user: ${loginRequest.username}, reason: $errorMessage")
                call.respond(HttpStatusCode.BadRequest, mapOf("errorMessage" to (errorMessage ?: "Invalid login")))
            }
        } catch (e: Exception) {
            logMessage("Error processing login request: ${e.message}")
            call.respond(HttpStatusCode.InternalServerError, mapOf("errorMessage" to "Internal server error"))
        }
    }
}

Here:

We define an API endpoint: POST /login
It's part of the larger Authentication API

🌐 Real Frontend Code (API Call Using Axios)

This is how the frontend consumes the /login endpoint:

export const loginUser = async (
  username: string,
  password: string
): Promise<LoginResponse | LoginErrorResponse> => {
  try {
    const response = await axios.post(`${loginUrl}login`, { username, password });
    const data = response.data;

    // Save tokens securely
    if (data.tokens?.accessToken && data.tokens?.refreshToken) {
      cookiesService.setCookie('accessToken', data.tokens.accessToken);
      cookiesService.setCookie('refreshToken', data.tokens.refreshToken);
    }

    // Save user profile details
    if (data.profile) {
      Object.keys(data.profile).forEach(key => {
        if (key !== 'profileImage' && data.profile[key]) {
          cookiesService.setCookie(key, String(data.profile[key]));
        }
      });

      // Save login session info
      const deviceId = getDeviceId();
      const deviceName = getBrowserInfo();
      const loginTime = Date.now();
      const userId = data.profile.userId;

      try {
        const location = await getLocation();
        await saveLoginSession({
          userId,
          deviceId,
          deviceName,
          deviceLocation: location ? `${location.city}, ${location.country}` : null,
          userAgent: navigator.userAgent,
          loginTime,
        });
      } catch (locationError) {
        console.warn('Failed to get location:', locationError);
        await saveLoginSession({
          userId,
          deviceId,
          deviceName,
          deviceLocation: null,
          userAgent: navigator.userAgent,
          loginTime,
        });
      }
    }

    return data;
  } catch (error) {
    if (axios.isAxiosError(error)) {
      return {
        errorMessage: error.response?.data?.errorMessage || 'Invalid credentials'
      };
    }
    return { errorMessage: 'An unexpected error occurred' };
  }
};

Here:

The function loginUser is calling the API endpoint /login
It is not the API itself — it is a consumer of the API

🚀 Conclusion

✅ The API lives in the backend.
✅ The frontend just calls the API via endpoints.
✅ An endpoint is a specific route in the API like /login or /register.
✅ API calls from the frontend (like using Axios) are clients — not definitions.

Understanding this distinction helps you architect cleaner, more scalable full-stack apps. Keep building! 💻🚀

✍️ Author

Post by a full-stack dev passionate about Kotlin, Ktor, TypeScript, and clean architecture. Follow me for more dev insights!

Implementing Role-Based Access Control (RBAC) in Kotlin with Ktor: A Complete Guide

Michael Odhiambo — Wed, 09 Jul 2025 05:43:55 +0000

Role-Based Access Control (RBAC) is essential for securing modern web applications. In this article, I'll walk through how I implemented RBAC in my Kotlin Ktor application, providing a step-by-step guide that beginners can follow to implement similar security in their projects.

Understanding the RBAC Flow

Before diving into the code, let's understand the complete flow of our RBAC implementation:

Authentication: User logs in and receives a JWT token
Token Validation: On each request, we extract and validate the user's token
User Extraction: We get the user profile from the validated token
Role Checking: We verify if the user's role is permitted for the requested action
Access Control: We either allow or deny access based on the role check

Let's implement each step in detail.

Step 1: Define User Roles

First, we define the possible roles in our system using a Kotlin enum:

// in com.example.routing.rbac.rbac.kt
enum class UserRole {
    ADMIN,
    USER,
    LECTURER,
    STUDENT
}

Using an enum provides type safety and makes role management straightforward.

Step 2: Setting Up JWT Authentication

For our RBAC to work, we need to authenticate users and generate tokens:

// in com.example.backend.plugins.AuthConfig.kt
object AuthConfig {
    const val JWT_SECRET = "your-secret-key" // Use environment variables in production
    const val JWT_ISSUER = "your-application"
    const val JWT_AUDIENCE = "your-audience"
    const val ACCESS_TOKEN_EXPIRATION = 3600000L // 1 hour
    const val REFRESH_TOKEN_EXPIRATION = 2592000000L // 30 days

    fun generateAccessToken(username: String): String {
        return JWT.create()
            .withIssuer(JWT_ISSUER)
            .withAudience(JWT_AUDIENCE)
            .withSubject(username) // We store username in the token
            .withExpiresAt(Date(System.currentTimeMillis() + ACCESS_TOKEN_EXPIRATION))
            .sign(Algorithm.HMAC256(JWT_SECRET))
    }

    // Additional token-related functions...
}

Step 3: Extracting User Information from JWT Tokens

This is the critical step that ties authentication to authorization. We need to:

Extract the token from the request
Validate the token
Get the username from the token
Fetch the user profile with role information

Here's how I implemented this:

// in com.example.backend.schema.auth.ExtractUser.kt
fun extractUserFromToken(call: ApplicationCall): Profile? {
    try {
        // Step 1: Extract token from Authorization header
        val authHeader = call.request.headers[HttpHeaders.Authorization]
        if (authHeader.isNullOrBlank() || !authHeader.startsWith("Bearer ")) {
            logMessage("No Authorization header found or invalid format")
            return null
        }

        // Step 2: Get the token by removing the "Bearer " prefix
        val accessToken = authHeader.removePrefix("Bearer ").trim()

        // Step 3: Extract username from token and validate it
        val username = getUsernameFromToken(accessToken)
        if (username != null) {
            // Step 4: Get the user profile with role information
            return getUserByUsername(username)
        }
        return null
    } catch (e: Exception) {
        logMessage("Error extracting user from token: ${e.message}", LogType.ERROR)
        return null
    }
}

// Helper function to extract username from token
fun getUsernameFromToken(accessToken: String): String? {
    return try {
        val jwt = JWT.require(Algorithm.HMAC256(AuthConfig.JWT_SECRET))
            .withIssuer(AuthConfig.JWT_ISSUER)
            .withAudience(AuthConfig.JWT_AUDIENCE)
            .build()
            .verify(accessToken)
        jwt.subject // This is the username we stored in the token
    } catch (e: Exception) {
        logMessage("Error extracting username from token: ${e.message}", LogType.ERROR)
        null
    }
}

// Database function to get user profile by username
fun getUserByUsername(username: String): Profile? {
    return transaction {
        // First find the user in the Users table
        val user = Users.selectAll()
            .where { Users.userName eq username }
            .singleOrNull() ?: return@transaction null

        // Then get their profile
        val userId = user[Users.userId]
        val profile = Profiles.selectAll()
            .where { Profiles.userId eq userId }
            .singleOrNull() ?: return@transaction null

        // Return a Profile object with the user's role
        Profile(
            userId = userId,
            username = user[Users.userName],
            firstName = profile[Profiles.firstName],
            lastName = profile[Profiles.lastName],
            userRole = user[Users.userRole], // This is the key field for RBAC
            email = profile[Profiles.email],
            // Other profile fields...
        )
    }
}

Step 4: Creating the RBAC Middleware

Now we create a middleware function that will protect our routes based on user roles:

// in com.example.routing.rbac.rbac.kt
suspend fun withRole(
    call: ApplicationCall,
    vararg allowedRoles: UserRole,
    handler: suspend (Profile) -> Unit
) {
    try {
        // Extract user from the token
        val user = extractUserFromToken(call)
        logMessage("Fetched user role: ${user?.userRole ?: "Unknown"} for path: ${call.request.path()}")

        // Check if user exists and has one of the allowed roles
        if (user == null || user.userRole.uppercase() !in allowedRoles.map { it.name }) {
            call.respondText("Access denied", status = HttpStatusCode.Forbidden)
            return
        }

        // If role check passes, execute the handler
        handler(user)
    } catch (e: Exception) {
        logMessage("Error in withRole for path ${call.request.path()}: ${e.message}")
        call.respondText(
            "Internal server error: ${e.message}",
            status = HttpStatusCode.InternalServerError
        )
    }
}

Step 5: Setting Up the Database Schema

Our RBAC system needs to store user roles in the database:

// in com.example.backend.schema.auth.User.kt
object Users : Table() {
    val userId = varchar("user_id", 36).primaryKey()
    val userName = varchar("username", 50).uniqueIndex()
    val passwordHash = varchar("password_hash", 255)
    val userRole = varchar("user_role", 255) // Stores the user's role
    val status = varchar("status", 20)
    val createdAt = long("created_at")
    val updatedAt = long("updated_at")
}

Step 6: Using RBAC in Routes

Now comes the most important part - applying RBAC to protect our routes. Here are real examples from my application:

Example 1: Basic Route Protection

// in com.example.routing.programs.ProgramRouting.kt
fun Route.programRouting() {
    route("/programs") {
        // Only ADMIN and LECTURER roles can access this endpoint
        get {
            withRole(call, UserRole.ADMIN, UserRole.LECTURER) { user ->
                val programs = getAllPrograms()
                call.respond(programs)
            }
        }

        // Only ADMIN role can create new programs
        post {
            withRole(call, UserRole.ADMIN) { user ->
                val program = call.receive<Program>()
                val newProgram = createProgram(program)
                call.respond(HttpStatusCode.Created, newProgram)
            }
        }
    }
}

Example 2: Role-Based Content Filtering

// in com.example.routing.timetable.TimetableRouting.kt
fun Route.timetableRouting() {
    route("/timetables") {
        get("/class/{classId}") {
            withRole(call, UserRole.ADMIN, UserRole.LECTURER, UserRole.STUDENT) { user ->
                val classId = call.parameters["classId"] ?: return@withRole call.respondText(
                    "Missing classId",
                    status = HttpStatusCode.BadRequest
                )

                // Different behavior based on user role
                val timetables = when (user.userRole.uppercase()) {
                    UserRole.ADMIN.name -> getAllTimetables(classId)
                    UserRole.LECTURER.name -> getLecturerTimetables(classId, user.userId)
                    UserRole.STUDENT.name -> getStudentTimetables(classId)
                    else -> {
                        call.respond(HttpStatusCode.BadRequest, "Invalid user role")
                        return@withRole
                    }
                }

                call.respond(timetables)
            }
        }
    }
}

Example 3: Checking Role Directly

Sometimes you might need to check the role inside the handler function for more complex logic:

// in com.example.routing.feedback.FeedbackRouting.kt
fun Route.feedbackRouting() {
    route("/feedback") {
        get {
            val user = extractUserFromToken(call) ?: 
                return@get call.respondText("Unauthorized", status = HttpStatusCode.Unauthorized)

            // Use the user's role for custom logic
            val isAdmin = user.userRole.equals("ADMIN", ignoreCase = true)
            val feedbackItems = if (isAdmin) {
                // Admins can see all feedback
                getAllFeedback()
            } else {
                // Others can only see their own feedback
                getUserFeedback(user.userId)
            }

            call.respond(feedbackItems)
        }
    }
}

Step 7: Role Validation for User Management

When creating or updating users, validate the roles:

fun validateUserRole(role: String): Boolean {
    return try {
        UserRole.valueOf(role.uppercase())
        true
    } catch (e: IllegalArgumentException) {
        false
    }
}

fun createUser(userRequest: UserCreationRequest): Pair<UserResponse?, String?> {
    // Validate the role
    if (!validateUserRole(userRequest.userRole)) {
        return Pair(null, "Invalid user role")
    }

    // Proceed with user creation
    // ...
}

Complete RBAC Flow Example

Let's put it all together to understand the complete flow:

User Authentication:

   // User logs in
   val loginResponse = login(LoginRequest("username", "password"))
   // User receives JWT token
   val token = loginResponse.tokens.accessToken

Making Authenticated Request:

   // Frontend includes the token in the Authorization header
   // Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Server Processes Request:

   // Route protected with RBAC
   get("/admin-only") {
       withRole(call, UserRole.ADMIN) { user ->
           // Only admins reach this point
           call.respond("Admin content")
       }
   }

What Happens Inside withRole:
- Extracts token from the request
- Validates the token and gets the username
- Fetches the user profile with role from the database
- Checks if the user's role is in the allowed roles list
- Executes the handler if authorized, returns 403 Forbidden if not

Best Practices

Role Hierarchy
- Design your roles with a clear hierarchy in mind
- In our system, ADMIN has the highest privileges, followed by LECTURER, then STUDENT
Error Handling
- Always log authentication and authorization failures
- Return appropriate HTTP status codes (401 for authentication failures, 403 for authorization failures)
- Don't expose sensitive error details to clients
JWT Security
- Store only necessary information in JWTs (username, not roles)
- Keep tokens short-lived
- Use refresh tokens for longer sessions
- Store the JWT secret securely using environment variables
Logging
- Log all important RBAC events for auditing and debugging
- Include the user and requested path in logs

Conclusion

Implementing RBAC in a Kotlin Ktor application involves setting up authentication with JWT, creating a middleware for role checking, and consistently applying it to your routes. The approach I've shown here is clean, maintainable, and secure.

By following this guide, you can implement a robust RBAC system in your own applications. Remember that security is an ongoing process, so continue to review and improve your implementation as your application evolves.

Resources

Building an AI Documentation Agent with Cohere

Michael Odhiambo — Wed, 09 Jul 2025 05:30:04 +0000

Have you ever wished your project documentation could answer questions directly? In this article, I'll show you how to create an AI-powered documentation agent that can understand and answer questions about your project using Cohere's powerful language models.

What We'll Build

We'll create a documentation agent that can:

Load and understand your project's documentation
Accept user questions in natural language
Provide context-aware answers based on your documentation
Handle errors gracefully

Prerequisites

Kotlin/JVM project
Cohere API key
Your project's documentation

Implementation

Let's break down the implementation into manageable pieces.

1. Setting Up the Service

First, we'll create a service class that will handle the interaction with Cohere's API. Here's how it looks:

class CohereService(
    private val apiKey: String,
    private val documentationContent: String
) {
    private val logger = LoggerFactory.getLogger(this::class.java)

    data class AIResponse(
        val text: String,
        val source: String,
        val success: Boolean,
        val error: String? = null
    )

    data class ConversationMessage(
        val role: String,
        val content: String
    )
}

2. Building the Question-Answering Logic

The main method handles the Q&A functionality:

fun askQuestion(
    prompt: String,
    conversationHistory: List<ConversationMessage> = emptyList(),
    documentContext: String? = null
): AIResponse {
    val actualDocumentContext = documentContext ?: documentationContent

    // Validate documentation
    if (isInvalidDocumentation(actualDocumentContext)) {
        return createErrorResponse(actualDocumentContext)
    }

    // Create an enhanced prompt
    val enhancedPrompt = buildEnhancedPrompt(prompt, actualDocumentContext)

    // Call Cohere API and return response
    return makeApiCall(enhancedPrompt)
}

3. Error Handling

We implement robust error handling to ensure a good user experience:

private fun isInvalidDocumentation(context: String): Boolean {
    return context.startsWith("Documentation file ") ||
           context.startsWith("Error reading") ||
           context.startsWith("Unexpected error")
}

private fun createErrorResponse(error: String) = AIResponse(
    text = "I'm unable to access the documentation file. Please ensure the file exists and is accessible.",
    source = "cohere",
    success = false,
    error = error
)

Usage Example

Here's how to use the documentation agent in your application:

val documentationContent = // Load your documentation
val cohereService = CohereService(apiKey = "your-api-key", documentationContent)

val response = cohereService.askQuestion(
    prompt = "How do I configure the database connection?"
)

println(response.text)

Best Practices

Documentation Format: Keep your documentation well-structured and in plain text format for better results.
Prompt Engineering: The enhanced prompt format helps the model understand the context:

   "Based on the following documentation, please answer the user's question:\n\n" +
   "Documentation: $actualDocumentContext\n\n" +
   "User Question: $prompt\n\n" +
   "Please provide a helpful answer based on the documentation provided."

Error Handling: Always validate the documentation content and handle API errors gracefully.
Logging: Implement comprehensive logging for debugging and monitoring.

Benefits

Improved Developer Experience: Quick access to documentation answers
Reduced Support Burden: Developers can get instant answers to common questions
Context-Aware Responses: Answers are always based on your actual documentation
Maintainable: Easy to update as your documentation evolves

Conclusion

By implementing this documentation agent, you can provide an interactive way for developers to query your project's documentation. The combination of Cohere's language models and your documentation creates a powerful tool for improving developer productivity.

Remember to keep your documentation up-to-date and well-structured to get the best results from the AI agent.

Resources

Happy coding! 🚀

DEV Community: Michael Odhiambo

Building with AI: A Deep Dive Into My Gemini-Powered Projects

1. StoryLoom

Tech Behind the App

2. QuizBaze

How It Works

What Makes It Unique

3. StyleAI Studio

For Personal Users

For Business Users

Tech Used

4. QuizMate

5. Quiz Master

Features

Tech Stack

Why I Built These Projects

🔐 Layered JWT + RBAC Authorization in Ktor: My Scalable Approach

🎯 The Problem

🧱 The Architecture: Two-Layer Auth

🧭 Layer 1: Global JWT Authentication

🔑 Layer 2: Role-Based Access Control (withRole)

🔍 Token Extraction: No Hidden Magic

🛠️ Usage Example

📈 Scalable and Maintainable

Bonus: Group Wrappers

✅ Final Thoughts

🔗 Got Feedback?

Breaking Circular Dependencies in Kotlin with the Mediator Pattern

The Problem: When Dependencies Go Round and Round

The Solution: Enter the Mediator Pattern

Step 1: Create a Mediator Interface

Step 2: Implement the Mediator

Step 3: Update Your Repositories

Step 4: Wire It Up in Your DI Container

How It Works: Breaking the Loop

The Benefits: Why You Should Care

Alternative Approaches

Real-World Implementation

Conclusion

🤖 API vs Endpoint - What's the Difference? (With Real Full-Stack Code)

🔍 What is an API?

🔗 What is an Endpoint?

🧠 Quick Comparison

📦 Real Backend Code (Ktor API Endpoint)

🌐 Real Frontend Code (API Call Using Axios)

🚀 Conclusion

✍️ Author

Implementing Role-Based Access Control (RBAC) in Kotlin with Ktor: A Complete Guide

Understanding the RBAC Flow

Step 1: Define User Roles

Step 2: Setting Up JWT Authentication

Step 3: Extracting User Information from JWT Tokens

Step 4: Creating the RBAC Middleware

Step 5: Setting Up the Database Schema

Step 6: Using RBAC in Routes

Example 1: Basic Route Protection

Example 2: Role-Based Content Filtering

Example 3: Checking Role Directly

Step 7: Role Validation for User Management

Complete RBAC Flow Example

Best Practices

Conclusion

Resources

Building an AI Documentation Agent with Cohere

What We'll Build

Prerequisites

Implementation

1. Setting Up the Service

2. Building the Question-Answering Logic

3. Error Handling

Usage Example

Best Practices

Benefits

Conclusion

Resources

🔑 Layer 2: Role-Based Access Control (`withRole`)