ktor-native-worker-tutorial

Ktor Native Worker Tutorial

Welcome to the Ktor Native Worker Tutorial! This comprehensive guide will teach you how to build a production-ready Kotlin Multiplatform backend using Ktor, targeting both JVM and Native platforms (Linux, macOS, Windows).

What You’ll Build

A backend service that:

Accepts HTTP requests to send push notifications
Uses RabbitMQ for asynchronous message processing
Sends Firebase Cloud Messaging (FCM) notifications
Compiles to native executables (no JVM required in production)
Follows clean code conventions and best practices

Architecture

HTTP Request → Ktor Server → RabbitMQ → Worker → FCM

The application demonstrates:

RESTful API design with Ktor
Asynchronous worker pattern with message queues
Dependency injection with Koin
Multiplatform code with platform-specific implementations
Clean architecture and separation of concerns

Tutorial Parts

Part 1: Gradle Setup

Learn how to configure a Kotlin Multiplatform project with Ktor:

Version catalog setup
JVM and Native target configuration
Dependency management
Platform-specific code with expect/actual
Build and run commands

Topics: Gradle, Kotlin Multiplatform, Project Structure

Part 2: Sending Notifications

Implement Firebase Cloud Messaging notification sending:

Service interface design
FCM integration with Flareon library
Service account configuration
Platform-specific file reading
Clean code patterns

Topics: FCM, Flareon, Service Pattern, Multiplatform APIs

Part 3: AMQP Setup and Calls

Set up RabbitMQ message broker for asynchronous processing:

MessageBroker interface and implementation
RabbitMQ connection with Kourier AMQP client
Exchange, queue, and binding configuration
Message handlers and event processing
JSON serialization with Kotlinx Serialization

Topics: RabbitMQ, AMQP, Message Queues, Worker Pattern

Part 4: Routes

Create type-safe HTTP endpoints with Ktor:

Route definition and payload classes
Content negotiation and JSON handling
Dependency injection for routes
Asynchronous message publishing
Request flow and error handling

Topics: Ktor Routing, HTTP APIs, Type Safety

Part 5: Wire Everything with Koin

Wire all components together using dependency injection:

Koin setup for Kotlin Multiplatform
Module definition and service registration
Environment-based configuration
Dependency graph and lifecycle
Application bootstrap

Topics: Dependency Injection, Koin, Configuration Management

Part 6: Test and Demo

Run, test, and deploy the complete application:

Running on JVM and Native platforms
Building production executables
Testing with curl, HTTPie, and Postman
RabbitMQ monitoring
Performance testing
Deployment strategies and troubleshooting

Topics: Testing, Deployment, Performance, Production

Prerequisites

Before starting this tutorial, you should have:

Basic knowledge of Kotlin
Familiarity with HTTP and REST APIs
Understanding of coroutines (helpful but not required)
Gradle installed (or use the wrapper)
Docker (optional, for running RabbitMQ)

Technologies Used

Technology	Version	Purpose
Kotlin	2.2.21	Programming language
Ktor	3.3.3	HTTP server framework
Koin	4.1.0	Dependency injection
Kourier AMQP	0.4.0	RabbitMQ client
Flareon	0.1.1	FCM messaging
Kotlinx Serialization	-	JSON handling

Quick Start

Clone the repository
Set up RabbitMQ (Docker recommended)
Add Firebase service account JSON
Run the application:
```
./gradlew jvmRun
```

Test with curl:

curl -X POST http://localhost:8080/api/notifications \
  -H "Content-Type: application/json" \
  -d '{"token": "xxx", "title": "Hello", "body": "Test"}'

Learning Path

Recommended order:

Start with Part 1: Gradle Setup to understand the project structure
Continue through parts 2-5 to learn each component
Finish with Part 6: Test and Demo to run the complete system

Alternative paths:

Focus on Multiplatform: Parts 1, 2, then 6
Focus on Messaging: Parts 3, 4, then 6
Focus on Architecture: Parts 2, 3, 5, then 6

Key Concepts

Throughout this tutorial, you’ll learn:

Kotlin Multiplatform: Write code once, compile to multiple platforms
Native Compilation: Create standalone executables without JVM overhead
Async Processing: Use message queues for background tasks
Clean Architecture: Separate concerns with interfaces and DI
Type Safety: Leverage Kotlin’s type system for robust code
12-Factor Apps: Environment-based configuration and best practices

Why Native?

Native compilation with Kotlin offers:

Fast Startup: Milliseconds vs seconds for JVM
Low Memory: 10-50MB vs 100-500MB for JVM
No Dependencies: No need to install Java runtime
Small Binaries: Single executable, easy deployment
Cloud Native: Perfect for containers and serverless

Project Structure

ktor-native-worker-tutorial/
├── build.gradle.kts              # Build configuration
├── settings.gradle.kts           # Project settings
├── gradle.properties             # Gradle properties
├── gradle/
│   └── libs.versions.toml        # Version catalog
├── src/
│   ├── commonMain/kotlin/        # Shared code
│   │   ├── Application.kt        # Main entry point
│   │   ├── config/               # Configuration
│   │   ├── di/                   # Dependency injection
│   │   ├── messaging/            # Message broker
│   │   ├── routes/               # HTTP routes
│   │   └── services/             # Business logic
│   ├── jvmMain/kotlin/           # JVM-specific code
│   └── nativeMain/kotlin/        # Native-specific code
└── docs/                         # This tutorial!

Getting Help

If you encounter issues:

Check the Test and Demo troubleshooting section
Review the relevant tutorial part
Examine the actual code in the src/ directory
Ensure all prerequisites are met (RabbitMQ, Firebase, etc.)

Next Steps

Ready to begin? Start with Part 1: Gradle Setup!

Note: All tutorials are based on the actual project code and follow clean code conventions. No fictional code or examples - everything you see can be found in the repository.