DEV Community: Saad Alkentar

Fast API, F for Frankenstein

Saad Alkentar — Sat, 18 Apr 2026 17:14:39 +0000

What is so special about Fast API?

It is the level of freedom!

free to choose the project structure, modular, layers, or even use-cases.
free to use SQLModel, SQLAlchemy, SQLObject, Tortoise-ORM, or even Django ORM!
free to use Pydantic, DataClasses, Marshmallow, or even Cerberus.
free to use Alembic, Liquibase, or maybe Jetbase.
free to use sync or async operations.

What sucks about Fast API?

It is the level of freedom!
You might work on more than 10 FastAPI projects, and each is unique in its own way 😁

The Frankenstein I'm building

I believe you saw why I call itFrankenstein, you build your project from a choice of libraries and structures, ending up with either a well-shaped body or an ill-shaped one.
The power also comes from there; you can add as many hands, legs, and heads as you want, it is yours to build as you see fit.

I'll try to build my own Frankenstein with the best choices based on the latest FastAPI documentation and my experience 🤓

Attention Before following those choices, make sure to check the article date. If it is older than 6 months, just look for a newer guide

The choices in this article:

Modular project structure
SQLModel
Alembic
Async operations

I'll use UV Python virtual environment and write some tests.

This article will cover only project initialization; later articles will cover aspects such as authentication and module addition.

Create UV virtual environment

I believe everyone is familiar with traditional

python3 -m venv .venv
source .venv/bin/activate

So feel free to use it if you wish.

For UV, we should start by installing UV based on your operating system.
Then (named the project folder Franky)

cd franky
uv init

Now you should have main.py, readme.md, and pyproject.toml. alongside the git initialization, which you can remove if you want.

installing the libraries

uv add 'fastapi[standard]'
uv add pydantic-settings
uv add python-dotenv
uv add sqlmodel
uv add uvicorn
uv add alembic
uv add httpx
uv add pytest
uv add pytest_asyncio
uv add greenlet

Most of the library's names explain their part, to say a few words

fastapi[standard]: installs all fast api packages, don't ignore the quotations, ''
uvicorn: for deployment
alembic: for database migration
httpx: for async client testing
greenlet: required for sqlmodel

Now you should have a project.toml file similar to mine

franky/project.toml

[project]
name = "franky"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
    "aiosqlite>=0.22.1",
    "alembic>=1.18.4",
    "fastapi[standard]>=0.136.0",
    "greenlet>=3.4.0",
    "httpx>=0.28.1",
    "pydantic-settings>=2.13.1",
    "pytest>=9.0.3",
    "pytest-asyncio>=1.3.0",
    "python-dotenv>=1.2.2",
    "sqlmodel>=0.0.38",
    "uvicorn>=0.44.0",
]

To test our environment, let's steal the core FastAPI script from the docs and update our main.py

franky/main.py

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

and test it by running

uv run fastapi dev

Core Project config, dependencies, and logging

We will create a config file that loads config from the .env file and provide it to the whole application as pydantic_settings

franky/src/core/config.py

import os
from dotenv import load_dotenv
from pydantic_settings import BaseSettings

load_dotenv()


class Config(BaseSettings):
    app_name: str = "Franky"
    debug: bool = True
    db_name: str = os.getenv("DB_NAME")

    @property
    def db_url(self):
        return f"sqlite+aiosqlite:///./{self.db_name}"


config = Config()

and create an .env in the main project folder with the DB_NAME property

franky/.env

DB_NAME=db.sqlite3

Notice that we are using sqlite+aiosqlite driver to use async operations with SQLight; this depends on your database choice.

Now for the database dependency

franky/src/core/dependencies.py

from typing import Annotated

from fastapi import Depends
from src.core.config import config
from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession


engine = create_async_engine(config.db_url, connect_args={"check_same_thread": False})
SessionLocal = async_sessionmaker(
    autocommit=False,
    autoflush=False,
    bind=engine,
    class_=AsyncSession
)

async def get_session() -> AsyncSession:
    async with SessionLocal() as session:
        try:
            yield session
        finally:
            await session.close()

SessionDep = Annotated[AsyncSession, Depends(get_session)]

We are creating an async session to communicate with the database.

to set up logging level and format

franky/src/core/logging.py

import logging

def setup_logging():
    logging.basicConfig(
        level=logging.INFO,
        format="%(asctime)s %(levelname)s [%(name)s] %(message)s"
    )

Updating the main app to use our new configuration

setup_logging()

app = FastAPI(title=config.app_name)
# ...

logging chang

old logging

      INFO   Started reloader process [37345] using WatchFiles
      INFO   Started server process [37348]
      INFO   Waiting for application startup.
      INFO   Application startup complete.

new logging format

      INFO   Started reloader process [37384] using WatchFiles
2026-04-17 22:05:47,964 INFO [uvicorn.error] Started reloader process [37384] using 
WatchFiles
      INFO   Started server process [37388]
2026-04-17 22:05:52,371 INFO [uvicorn.error] Started server process [37388]
      INFO   Waiting for application startup.
2026-04-17 22:05:52,373 INFO [uvicorn.error] Waiting for application startup.
      INFO   Application startup complete.
2026-04-17 22:05:52,374 INFO [uvicorn.error] Application startup complete.

The database dependency will be used later when integrating with the DB.

Exception handlers and unified response schema

The idea is to unify the response schema to something like

{
  "success": true,
  "message": "Operation successful",
  "data": {
    ...
  }
}

and errors to appear like

{
  "success": false,
  "message": "serious error occurred",
  "data": null
}

We will create a middleware to unify responses. Let's begin by creating response schemas

franky/src/core/models.py

from typing import Generic, TypeVar
from pydantic import BaseModel


T = TypeVar("T")

class IResponse(BaseModel, Generic[T]):
    success: bool = True
    message: str = "Operation successful"
    data: T | None = None

IResponse is the generic schema for all responses from the system.
the middleware

franky/src/core/middlewares.py

import json
from fastapi import Request, Response
from starlette.middleware.base import BaseHTTPMiddleware
from starlette.concurrency import iterate_in_threadpool

from src.core.models import IResponse


class UnifiedResponseMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        # 1. Skip wrapping for docs
        if request.url.path in ["/openapi.json", "/docs", "/redoc"]:
            return await call_next(request)

        response = await call_next(request)

        # 2. Only wrap JSON
        content_type = response.headers.get("content-type", "")
        if response.status_code < 400 and "application/json" in content_type:
            body = b"".join([section async for section in response.body_iterator])

            if not body:
                return response

            try:
                data = json.loads(body.decode("utf-8"))

                # Check if already wrapped
                if isinstance(data, dict) and "success" in data:
                    response.body_iterator = iterate_in_threadpool(iter([body]))
                    return response

                # 3. Wrap
                wrapped_data = IResponse(data=data).model_dump_json()

                # 4. Clean Headers
                headers = dict(response.headers)
                headers.pop("Content-Length", None)
                headers.pop("content-length", None)

                return Response(
                    content=wrapped_data,
                    status_code=response.status_code,
                    headers=headers,
                    media_type="application/json"
                )
            except (json.JSONDecodeError, UnicodeDecodeError):
                response.body_iterator = iterate_in_threadpool(iter([body]))
                return response

        return response

Installing a global middleware interrupts all requests and responses in the system, including those from Swagger. That is why we are checking where the request comes from

        if request.url.path in ["/openapi.json", "/docs", "/redoc"]:

One of the common issues when playing with the responses is the content-length header, which is why we are setting it to None.

We need an app-level error handler to wrap all errors in this common response.

franky/src/core/exceptions.py

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError
from starlette.exceptions import HTTPException as StarletteHTTPException


async def common_exception_handler(request: Request, exc: Exception):
    status_code = 400
    message = str(exc)

    # Check if it's a Starlette/FastAPI HTTPException
    if isinstance(exc, StarletteHTTPException):
        status_code = exc.status_code
        message = exc.detail

    return JSONResponse(
        status_code=status_code,
        content={
            "success": False,
            "message": message,
            "data": None
        }
    )

def setup_exception_handlers(app: FastAPI):
    app.add_exception_handler(StarletteHTTPException, common_exception_handler)
    app.add_exception_handler(RequestValidationError, common_exception_handler)
    app.add_exception_handler(Exception, common_exception_handler)

setup_exception_handlers wraps StarletteHTTPException, RequestValidationError, and generic Exception with our generic response.

Updating main.py

Adding the error handler and middleware on the app level

franky/main.py

from fastapi import FastAPI
from src.core.logging import setup_logging
from src.core.config import config

from src.core.exceptions import setup_exception_handlers
from src.core.middlewares import UnifiedResponseMiddleware

setup_logging()

app = FastAPI(title=config.app_name)

setup_exception_handlers(app)
app.add_middleware(UnifiedResponseMiddleware)

@app.get("/")
async def root():
    return {"message": "Hello World"}

@app.get("/error")
async def root():
    raise Exception("serious error occurred")

Test / and /error to see the responses

Simple module structure

I suggest this simple and clear modular app structure

--src

----module1
------__init__.py
------dependencies.py
------models.py
------router.py
------service.py
...

I'll create a simple appointments module as an example.

starting from models

franky/src/appointments/models.py

from datetime import datetime, UTC
from enum import Enum
from typing import Optional

from sqlmodel import SQLModel, Field


class AppointmentStatus(str, Enum):
    scheduled = "scheduled"
    completed = "completed"
    cancelled = "cancelled"


class AppointmentBase(SQLModel):
    title: str = Field(min_length=1, max_length=255)
    description: Optional[str] = Field(default=None, max_length=1000)
    start_time: datetime
    end_time: datetime
    location: Optional[str] = Field(default=None, max_length=500)
    status: AppointmentStatus = AppointmentStatus.scheduled


class Appointment(AppointmentBase, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
    updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))


class AppointmentCreate(AppointmentBase):
    pass


class AppointmentUpdate(SQLModel):
    title: Optional[str] = Field(default=None, min_length=1, max_length=255)
    description: Optional[str] = Field(default=None, max_length=1000)
    start_time: Optional[datetime] = None
    end_time: Optional[datetime] = None
    location: Optional[str] = Field(default=None, max_length=500)
    status: Optional[AppointmentStatus] = None


class AppointmentRead(AppointmentBase):
    id: int
    created_at: datetime
    updated_at: datetime

After the models, it is time for the DB service, which just provides basic CRUD

franky/src/appointments/service.py

from datetime import datetime, UTC
from typing import Optional, Sequence

from sqlalchemy.ext.asyncio import AsyncSession
from sqlmodel import select

from src.appointments.models import Appointment, AppointmentCreate, AppointmentUpdate


class AppointmentService:
    def __init__(self, session: AsyncSession) -> None:
        self.session = session

    async def create(self, data: AppointmentCreate) -> Appointment:
        appointment = Appointment.model_validate(data)
        self.session.add(appointment)
        await self.session.commit()
        await self.session.refresh(appointment)
        return appointment

    async def get(self, appointment_id: int) -> Optional[Appointment]:
        return await self.session.get(Appointment, appointment_id)

    async def list(self, offset: int = 0, limit: int = 20) -> Sequence[Appointment]:
        result = await self.session.execute(
            select(Appointment).offset(offset).limit(limit)
        )
        return result.scalars().all()

    async def update(
        self, appointment_id: int, data: AppointmentUpdate
    ) -> Optional[Appointment]:
        appointment = await self.session.get(Appointment, appointment_id)
        if not appointment:
            return None
        updates = data.model_dump(exclude_unset=True)
        for key, value in updates.items():
            setattr(appointment, key, value)
        appointment.updated_at = datetime.now(UTC)
        self.session.add(appointment)
        await self.session.commit()
        await self.session.refresh(appointment)
        return appointment

    async def delete(self, appointment_id: int) -> bool:
        appointment = await self.session.get(Appointment, appointment_id)
        if not appointment:
            return False
        await self.session.delete(appointment)
        await self.session.commit()
        return True

And the dependency after the service

franky/src/appointments/dependencies.py

from typing import Annotated

from fastapi import Depends

from src.core.dependencies import SessionDep
from src.appointments.service import AppointmentService


def get_appointment_service(session: SessionDep) -> AppointmentService:
    return AppointmentService(session)


AppointmentServiceDep = Annotated[AppointmentService, Depends(get_appointment_service)]

and finally the router.

franky/src/appointments/router.py

from fastapi import APIRouter, HTTPException, Query

from src.appointments.dependencies import AppointmentServiceDep
from src.appointments.models import AppointmentCreate, AppointmentRead, AppointmentUpdate

router = APIRouter(prefix="/appointments", tags=["appointments"])


@router.post("/", response_model=AppointmentRead, status_code=201)
async def create_appointment(data: AppointmentCreate, service: AppointmentServiceDep):
    return await service.create(data)


@router.get("/", response_model=list[AppointmentRead])
async def list_appointments(
    service: AppointmentServiceDep,
    offset: int = Query(0, ge=0),
    limit: int = Query(20, ge=1, le=100),
):
    return await service.list(offset=offset, limit=limit)


@router.get("/{appointment_id}", response_model=AppointmentRead)
async def get_appointment(appointment_id: int, service: AppointmentServiceDep):
    appointment = await service.get(appointment_id)
    if not appointment:
        raise HTTPException(status_code=404, detail="Appointment not found")
    return appointment


@router.patch("/{appointment_id}", response_model=AppointmentRead)
async def update_appointment(
    appointment_id: int,
    data: AppointmentUpdate,
    service: AppointmentServiceDep,
):
    appointment = await service.update(appointment_id, data)
    if not appointment:
        raise HTTPException(status_code=404, detail="Appointment not found")
    return appointment


@router.delete("/{appointment_id}", status_code=204)
async def delete_appointment(appointment_id: int, service: AppointmentServiceDep):
    deleted = await service.delete(appointment_id)
    if not deleted:
        raise HTTPException(status_code=404, detail="Appointment not found")

Great, now we have our module, let's install it in the main app.

franky/main.py

...
from src.appointments.router import router as appointments_router

setup_logging()


@asynccontextmanager
async def lifespan(app: FastAPI):
    async with engine.begin() as conn:
        await conn.run_sync(SQLModel.metadata.create_all)
    yield


app = FastAPI(title=config.app_name, lifespan=lifespan)

setup_exception_handlers(app)
app.add_middleware(UnifiedResponseMiddleware)

app.include_router(appointments_router)
...

We have it set. You should be able to find the appointments endpoints with Swagger.

Notice that we added an async function to create the db if it doesn't already exist, lifespan. This is temporary until we set up our database migration on the next step 😁

Fast API database migration with Alembic

I'll cover Alembic with async db; there might be differences when dealing with sync one.

uv run alembic init -t async migrations

With Alembic initialized, we need to update the schema of generated files to include sqlmodel

fraky/migrations/script.py.mako

"""${message}

Revision ID: ${up_revision}
Revises: ${down_revision | comma,n}
Create Date: ${create_date}

"""
from typing import Sequence, Union

from alembic import op
import sqlalchemy as sa
import sqlmodel             # NEW
${imports if imports else ""}
...

and point out the new models for Alembic to track

franky/migrations/env.py

import asyncio
from logging.config import fileConfig

from sqlalchemy import pool
from sqlalchemy.engine import Connection
from sqlalchemy.ext.asyncio import async_engine_from_config
from sqlmodel import SQLModel   #new

from alembic import context

from src.appointments.models import Appointment   #new

# this is the Alembic Config object, which provides
# access to the values within the .ini file in use.
config = context.config

# Interpret the config file for Python logging.
# This line sets up loggers basically.
if config.config_file_name is not None:
    fileConfig(config.config_file_name)

# add your model's MetaData object here
# for 'autogenerate' support
# from myapp import mymodel
# target_metadata = mymodel.Base.metadata
target_metadata = SQLModel.metadata   #updated
...

The final config part includes updating the ini file to point to the db

...
sqlalchemy.url = sqlite+aiosqlite:///./db.sqlite3   #updated
...

With all configurations ready, we can create a migration using

uv run alembic revision --autogenerate -m "init"

Now we have our first migration 🤩, congrats. You should be able to find it under migrations/versions/randomthing_init.py
You can edit the migration manually if required, but it is good in general.

to apply a migration

uv run alembic upgrade head

Great, now we can remove the SQLModel.metadata.create_all from the main file and use our migration to create it instead

franky/main.py

from src.appointments.router import router as appointments_router

setup_logging()

app = FastAPI(title=config.app_name)

setup_exception_handlers(app)
app.add_middleware(UnifiedResponseMiddleware)

app.include_router(appointments_router)

And make sure to issue uv run alembic upgrade head before using the app.

Fast API Tests

I'll be fast on this. We start by setting up the test config

franky/tests/conftest.py

from __future__ import annotations

import os
import uuid

# Relative path: `sqlite+aiosqlite:///./{name}` in config breaks for absolute paths.
_test_db_file = f".pytest_franky_{uuid.uuid4().hex}.sqlite"
os.environ["DB_NAME"] = _test_db_file

import pytest
from httpx import ASGITransport, AsyncClient
from sqlmodel import SQLModel

from main import app
from src.core.dependencies import engine


def pytest_sessionfinish(session: pytest.Session, exitstatus: int) -> None:
    try:
        os.unlink(_test_db_file)
    except OSError:
        pass


@pytest.fixture(autouse=True)
async def reset_database() -> None:
    async with engine.begin() as conn:
        await conn.run_sync(SQLModel.metadata.drop_all)
        await conn.run_sync(SQLModel.metadata.create_all)
    yield


@pytest.fixture
async def client() -> AsyncClient:
    transport = ASGITransport(app=app)
    async with AsyncClient(transport=transport, base_url="http://test") as ac:
        yield ac

Then, a simple test file for each module

franky/tests/test_appointments.py

from __future__ import annotations

from httpx import AsyncClient


def _sample_create_payload() -> dict:
    return {
        "title": "Annual checkup",
        "description": "Routine visit",
        "start_time": "2026-06-01T10:00:00+00:00",
        "end_time": "2026-06-01T11:00:00+00:00",
        "location": "Main clinic",
        "status": "scheduled",
    }


def _unwrap_success_json(data: dict) -> dict | list:
    assert data.get("success") is True
    assert "data" in data
    return data["data"]


async def test_list_appointments_empty(client: AsyncClient) -> None:
    response = await client.get("/appointments/")
    assert response.status_code == 200
    body = response.json()
    assert _unwrap_success_json(body) == []


async def test_create_and_get_appointment(client: AsyncClient) -> None:
    payload = _sample_create_payload()
    create_res = await client.post("/appointments/", json=payload)
    assert create_res.status_code == 201
    created = _unwrap_success_json(create_res.json())
    assert created["title"] == payload["title"]
    assert created["id"] is not None
    appointment_id = created["id"]

    get_res = await client.get(f"/appointments/{appointment_id}")
    assert get_res.status_code == 200
    fetched = _unwrap_success_json(get_res.json())
    assert fetched["id"] == appointment_id
    assert fetched["title"] == payload["title"]


async def test_get_appointment_not_found(client: AsyncClient) -> None:
    response = await client.get("/appointments/99999")
    assert response.status_code == 404
    body = response.json()
    assert body["success"] is False
    assert body["data"] is None


async def test_list_pagination(client: AsyncClient) -> None:
    for i in range(3):
        await client.post(
            "/appointments/",
            json={
                **_sample_create_payload(),
                "title": f"Appt {i}",
            },
        )

    all_res = await client.get("/appointments/", params={"limit": 100})
    assert len(_unwrap_success_json(all_res.json())) == 3

    page = await client.get("/appointments/", params={"offset": 1, "limit": 2})
    assert len(_unwrap_success_json(page.json())) == 2


async def test_update_appointment(client: AsyncClient) -> None:
    create_res = await client.post("/appointments/", json=_sample_create_payload())
    appointment_id = _unwrap_success_json(create_res.json())["id"]

    patch_res = await client.patch(
        f"/appointments/{appointment_id}",
        json={"title": "Updated title", "status": "completed"},
    )
    assert patch_res.status_code == 200
    updated = _unwrap_success_json(patch_res.json())
    assert updated["title"] == "Updated title"
    assert updated["status"] == "completed"


async def test_update_not_found(client: AsyncClient) -> None:
    response = await client.patch(
        "/appointments/99999",
        json={"title": "Nope"},
    )
    assert response.status_code == 404
    assert response.json()["success"] is False


async def test_delete_appointment(client: AsyncClient) -> None:
    create_res = await client.post("/appointments/", json=_sample_create_payload())
    appointment_id = _unwrap_success_json(create_res.json())["id"]

    delete_res = await client.delete(f"/appointments/{appointment_id}")
    assert delete_res.status_code == 204
    assert delete_res.content == b""

    get_res = await client.get(f"/appointments/{appointment_id}")
    assert get_res.status_code == 404


async def test_delete_not_found(client: AsyncClient) -> None:
    response = await client.delete("/appointments/99999")
    assert response.status_code == 404
    assert response.json()["success"] is False


async def test_create_validation_error(client: AsyncClient) -> None:
    response = await client.post(
        "/appointments/",
        json={"title": ""},
    )
    assert response.status_code == 400
    body = response.json()
    assert body["success"] is False
    assert body["data"] is None

and run them by issuing

uv run pytest .

It was a long one, but we have our project ready. Build a wonderful app on this 😁

I'll build a user management module for the next article. So stay tuned

The final project structure should look like

franky/
├── main.py                 # FastAPI app, lifespan, route registration
├── README.md
├── alembic.ini             # Alembic configuration (DB URL for CLI migrations)
├── pyproject.toml          # Dependencies, pytest options, and project metadata
├── uv.lock                 # Locked dependency versions
├── migrations/             # Alembic migration environment
│   ├── env.py              # Async engine; SQLModel metadata for autogenerate
│   ├── script.py.mako      # Template for new revision files
│   ├── README              # Alembic-generated readme
│   └── versions/           # Revision scripts (e.g. initial schema)
├── tests/                  # Pytest suite (`pythonpath` includes repo root)
│   ├── conftest.py         # Test DB env, schema reset, async HTTP client fixture
│   └── test_appointments.py
└── src/
    ├── core/               # Shared infrastructure
    │   ├── config.py       # Settings (env / `.env`)
    │   ├── dependencies.py # Async SQLAlchemy engine and session
    │   ├── exceptions.py   # Exception handlers
    │   ├── logging.py
    │   ├── middlewares.py  # Unified JSON response wrapper
    │   └── models.py       # `IResponse`, pagination types
    └── appointments/       # Appointments domain
        ├── dependencies.py # Service DI
        ├── models.py       # SQLModel entities and request/response schemas
        ├── router.py       # HTTP routes under `/appointments`
        └── service.py      # Business logic

KMP Native UI Login and Profile screens, DataStore, navigation, and more

Saad Alkentar — Sun, 12 Apr 2026 17:25:28 +0000

We are all set now. Our KMP Native UI app is fully configured with

Koin dependency injection
Ktor networking client
and structured according to Clean architecture

What next? I believe most of you are set and ready to go.

This tutorial will build upon the previous ones. I'll use native navigation for both Android and iOS to build a login screen, pass data between the screens using a shared ViewModel, try to save the token, and improve the product list a little.
A reminder of two important points from the previous tutorial

The final repository can be found here

What are the app features?

For our simple project, we will add two features.

Auth feature: Where we can fill in the login form and navigate to the Home and Profile screens.
Products feature: where we can list products and show their details. (already done the list so I'll work on it anymore)

Where to get it from?

I found a website called dummy json that provides both Auth and Products endpoints. We have already used the Products API in a previous tutorial. The Auth will be covered here.

Auth Clean Architecture shared module

Similar to the product's features, the folder structure would look like

-shared
--commonMein

---auth

----data
-----AuthDataSource.kt
-----AuthRepositoryImpl.kt

----domain
-----models
-----AuthRepository.kt

----ui
-----Login
------LoginActions.kt
------LoginState.kt
------LoginViewModel.kt

-----Profile
------ProfileActions.kt
------ProfileState.kt
------ProfileViewModel.kt

We have two screens using the same repository here.

Auth models

We are following the schemas from Auth and using the JSON To Kotlin Class extension. We need the login request, refresh token request, login response, and get auth user response schemas.

shared/commonMein/auth/domain/models/LoginRequest.kt

@Serializable
data class LoginRequest(
    @SerialName("password")
    val password: String? = null,
    @SerialName("username")
    val username: String? = null,
    @SerialName("expiresInMins")
    val expiresInMins: Int? = null,
)

shared/commonMein/auth/domain/models/LoginResponse.kt

@Serializable
data class LoginResponse(
    @SerialName("accessToken")
    val accessToken: String? = null,
    @SerialName("email")
    val email: String? = null,
    @SerialName("firstName")
    val firstName: String? = null,
    @SerialName("gender")
    val gender: String? = null,
    @SerialName("id")
    val id: Int? = null,
    @SerialName("image")
    val image: String? = null,
    @SerialName("lastName")
    val lastName: String? = null,
    @SerialName("refreshToken")
    val refreshToken: String? = null,
    @SerialName("username")
    val username: String? = null
)

shared/commonMein/auth/domain/models/RefreshRequest.kt

@Serializable
data class RefreshRequest(
    @SerialName("refreshToken")
    val refreshToken: String? = null
)

shared/commonMein/auth/domain/models/UserModel.kt

@Serializable
data class UserModel(
    @SerialName("email")
    val email: String? = null,
    @SerialName("firstName")
    val firstName: String? = null,
    @SerialName("gender")
    val gender: String? = null,
    @SerialName("id")
    val id: Int? = null,
    @SerialName("image")
    val image: String? = null,
    @SerialName("lastName")
    val lastName: String? = null,
    @SerialName("username")
    val username: String? = null
)

If there are too many models, I would further separate them into requests, responses, and entities.

Auth repository

We only have three requests

shared/commonMein/auth/domain/AuthRepository.kt

interface AuthRepository {
    suspend fun login(username: String, password: String) : DataState<LoginResponse, DataError.Remote>
    suspend fun refreshToken(refreshToken: String) : DataState<RefreshResponse, DataError.Remote>
    suspend fun getUser() : DataState<UserModel, DataError.Remote>

}

We are done with the domain layer. Let's fill in the data layer

shared/commonMein/auth/data/AuthDataSource.kt

class AuthDataSource(
    private val httpClient: HttpClient
) {

    suspend fun authLogin(
        request: LoginRequest,
    ): HttpResponse {
        return httpClient.post (
            urlString = "$BASE_URL/auth/login"
        ) {
            setBody(request)
        }
    }

    suspend fun authRefresh(
        request: RefreshRequest,
    ): HttpResponse {
        return httpClient.post (
            urlString = "$BASE_URL/auth/refresh"
        ) {
            setBody(request)
        }
    }

    suspend fun authMe(): HttpResponse {
        return httpClient.get(
            urlString = "$BASE_URL/auth/me"
        )
    }
}

shared/commonMein/auth/data/AuthRepositoryImpl.kt

class AuthRepositoryImpl(
    private val dataSource: AuthDataSource
) : AuthRepository {

    override suspend fun login(
        username: String,
        password: String
    ): DataState<LoginResponse, DataError.Remote> =
        safeCall<LoginResponse> {
            dataSource.authLogin(
                request = LoginRequest(
                    username = username,
                    password = password,
                    expiresInMins = 1,
                )
            )

        }.map { it }

    override suspend fun refreshToken(
        refreshToken: String
    ): DataState<RefreshResponse, DataError.Remote> =
        safeCall<RefreshResponse> {
            dataSource.authRefresh(
                request = RefreshRequest(
                    refreshToken = refreshToken,
                )
            )
        }

    override suspend fun getUser(
    ): DataState<UserModel, DataError.Remote> =
        safeCall<UserModel> {
            dataSource.authMe()
        }

}

We have set expiresInMins = 1 to test the refresh token logic.
After building both the domain and data layers.
We need to pass the access token to the getUser request too. We will do that using the ktor auth plugin later on.
It is time for the presentation layer

But before that, how are we to store the tokens?

Datastore implementation

Data store, shared preferences, and user defaults are all the same, and the most common and simple method to store data chunks like tokens. For an actual application, it is better to encrypt the tokens before storage, but this tutorial is complicated enough as is.

Let's start with updating the toml file

gradle/libs.versions.toml

[versions]
datastore = "1.2.1"

[libraries]
androidx-datastore = { group = "androidx.datastore", name = "datastore", version.ref = "datastore" }
androidx-datastore-preferences = { group = "androidx.datastore", name = "datastore-preferences", version.ref = "datastore" }

updating shared module build.gradle.kts

shared/build.gradle.kts

...
kotlin {

    sourceSets {
        commonMain.dependencies {
            ...
            implementation(libs.androidx.datastore)
            implementation(libs.androidx.datastore.preferences)
        }
        ...
    }
}

We will be using the Datastore only in the shared module data layer. For further details, refer to the docs

Usually, the Datastore can be used in all parts of the application, so it makes more sense to add it to the core module

shared/commonMein/core/data/DataStoreFactory.kt

internal const val PREFERENCES_DATASTORE_FILE_NAME = "app_preferences.preferences_pb"

object AuthPreferencesKeys {
    val ACCESS_TOKEN = stringPreferencesKey("access_token")
    val REFRESH_TOKEN = stringPreferencesKey("refresh_token")
}
fun createPreferencesDataStore(
    producePath: () -> String,
): DataStore<Preferences> =
    PreferenceDataStoreFactory.createWithPath(
        produceFile = { producePath().toPath() },
    )

The const can be moved to the config file and the keys to another file. I'm keeping them here to simplify things.

Now, for platform modules, the Android module

shared/androidMain/kotlin/core/data/DataStoreFactory.android.kt

fun createPreferencesDataStore(context: Context): DataStore<Preferences> =
    createPreferencesDataStore(
        producePath = {
            context.filesDir.resolve(PREFERENCES_DATASTORE_FILE_NAME).absolutePath
        },
    )

and the iOS module

shared/iosMain/core/data/DataStoreFactory.ios.kt

@OptIn(ExperimentalForeignApi::class)
fun createPreferencesDataStore(): DataStore<Preferences> =
    createPreferencesDataStore(
        producePath = {
            val documentDirectory: NSURL? = NSFileManager.defaultManager.URLForDirectory(
                directory = NSDocumentDirectory,
                inDomain = NSUserDomainMask,
                appropriateForURL = null,
                create = false,
                error = null,
            )
            requireNotNull(documentDirectory).path + "/$PREFERENCES_DATASTORE_FILE_NAME"
        },
    )

Datastore DI setup

With the platform's code ready, it is time to provide it to the dependency injection

shared/commonMein/di/data/DataStoreProvider.kt

class DataStoreProvider(
    val preferences: DataStore<Preferences>,
)

shared/commonMein/di/data/KoinModules.kt

val sharedModule = module {
    single { DataStoreProvider(get()) }
    ...
}

Now for platform-related di, for Android

shared/androidMain/kotlin/di/PlatformModule.android.kt

actual val platformModule = module {
    single<HttpClientEngine> { OkHttp.create() }
    single<DataStore<Preferences>> { createPreferencesDataStore(androidContext()) }
}

and iOS

shared/iosMain/kotlin/di/PlatformModule.ios.kt

actual val platformModule = module {
    single<HttpClientEngine> { Darwin.create() }
    single<DataStore<Preferences>> { createPreferencesDataStore() }
}

All done, how to use it now? We will create a DataStorage repository

Datastore repository

Similar to api repository, we start by creating the interface schema

shared/commonMain/kotlin/core/domain/DataStoreRepository.kt

interface DataStoreRepository {

    suspend fun saveAccessToken(accessToken: String)
    suspend fun getAccessToken(): String?

    suspend fun saveRefreshToken(refreshToken: String)
    suspend fun getRefreshToken(): String?
}

the data layer implementation

shared/commonMain/kotlin/core/data/DataStoreRepositoryImpl.kt

class DataStoreRepositoryImpl(
    private val dataStore: DataStoreProvider
) : DataStoreRepository {

    override suspend fun saveAccessToken(accessToken: String) {
        dataStore.preferences.edit { prefs ->
            prefs[AuthPreferencesKeys.ACCESS_TOKEN] = accessToken
        }
    }

    override suspend fun getAccessToken(): String? =
        dataStore.preferences.data.first()[AuthPreferencesKeys.ACCESS_TOKEN]

    override suspend fun saveRefreshToken(refreshToken: String) {
        dataStore.preferences.edit { prefs ->
            prefs[AuthPreferencesKeys.REFRESH_TOKEN] = refreshToken
        }
    }

    override suspend fun getRefreshToken(): String? =
        dataStore.preferences.data.first()[AuthPreferencesKeys.REFRESH_TOKEN]

}

almost ready, just the di now

shared/commonMain/kotlin/di/KoinModules.kt

val sharedModule = module {
    single { DataStoreProvider(get()) }
    singleOf(::DataStoreRepositoryImpl).bind<DataStoreRepository>()
    ...
}

Now we can use the DataStore repository where needed

Login shared module setup

I'll try to follow bloc design pattern for the view models
ui triggers actions, bloc receives them, and updates the state accordingly. So we need actions, state, and bloc (ViewModel)

shared/commonMain/kotlin/auth/ui/login/LoginActions.kt

sealed interface LoginActions {
    class Login : LoginActions
    class RefreshToken : LoginActions

    data class OnUsernameUpdate(val username: String) : LoginActions
    data class OnPasswordUpdate(val password: String) : LoginActions
}

Now for the state

shared/commonMain/kotlin/auth/ui/login/LoginState.kt

data class LoginState(
    val loginResponse: LoginResponse?,
    val userModel: UserModel?,
    val refreshResponse: RefreshResponse?,
    val username: String = "",
    val password: String = "",
    val isLoading: Boolean = false,
    val errorMessage: String? = null,
)

Finally, the bloc logic in the ViewModel

shared/commonMain/kotlin/auth/ui/login/LoginViewModel.kt

class LoginViewModel(
    private val repository: AuthRepository,
    private val dataStoreRepository: DataStoreRepository,
) : ViewModel() {

    private var loginJob: Job? = null
    private var refreshJob: Job? = null

    private val _state = MutableStateFlow(LoginState(
        loginResponse = null,
        userModel = null,
        refreshResponse = null,
        isLoading = false,
        errorMessage = null,
        username = "",
        password = ""
    ))

    @NativeCoroutinesState
    val state: StateFlow<LoginState> = _state
        .stateIn(
            viewModelScope,
            SharingStarted.WhileSubscribed(5000L),
            _state.value
        )


    fun onAction(action: LoginActions) {
        when (action) {
            is LoginActions.Login -> {
                loginJob?.cancel()
                loginJob = login(state.value.username, state.value.password)
            }

            is LoginActions.RefreshToken -> {
                refreshJob?.cancel()
                refreshJob = refreshToken()
            }

            is LoginActions.OnUsernameUpdate -> {
                _state.update {
                    it.copy(
                        username = action.username
                    )
                }
            }

            is LoginActions.OnPasswordUpdate -> {
                _state.update {
                    it.copy(
                        password = action.password
                    )
                }
            }

        }
    }

    fun onCancel() = viewModelScope.launch {
        _state.update {
            it.copy(
                errorMessage = "cancel"
            )
        }
    }

    private fun login(username: String, password: String) = viewModelScope.launch {

        _state.update {
            it.copy(
                isLoading = true
            )
        }
        repository
            .login(
                username = username,
                password = password
            ).onSuccess { response ->
                response.accessToken?.let { dataStoreRepository.saveAccessToken(it) }
                response.refreshToken?.let { dataStoreRepository.saveRefreshToken(it) }
                _state.update {
                    it.copy(
                        isLoading = false,
                        errorMessage = null,
                        loginResponse = response
                    )
                }
            }
            .onError { error, message ->
                _state.update {
                    it.copy(
                        isLoading = false,
                        loginResponse = null,
                        errorMessage = message ?: error.toString()
                    )
                }
            }
    }

    private fun refreshToken() = viewModelScope.launch {

        _state.update {
            it.copy(
                isLoading = true
            )
        }
        repository
            .refreshToken(refreshToken = dataStoreRepository.getRefreshToken().orEmpty())
            .onSuccess { response ->
                _state.update {
                    it.copy(
                        isLoading = false,
                        errorMessage = null,
                        refreshResponse = response
                    )
                }
            }
            .onError { error, message ->
                _state.update {
                    it.copy(
                        isLoading = false,
                        refreshResponse = null,
                        errorMessage = message ?: error.toString()
                    )
                }
            }
    }

}

We are using the AuthRepository to trigger the login action. In a success case, we are saving both access and refresh tokens to the DataStore.

But how to use them? How to refresh the token when needed?

Ktor auth plugin setup

It is a wonderful addition to any web client. make sure that we have the auth plugin in our libs.versions.toml

gradle/libs.versions.toml

[libraries]
ktor-client-auth = { module = "io.ktor:ktor-client-auth", version.ref = "ktor" }
...
[bundles]
ktor = [
    "ktor-client-core",
    "ktor-client-content-negotiation",
    "ktor-client-auth",
    "ktor-client-logging",
    "ktor-serialization-kotlinx-json",
]

Now for the actual ktor client config file

shared/commonMain/kotlin/core/data/HttpClientFactory.kt

object HttpClientFactory {

    fun create(engine: HttpClientEngine, dataStoreRepository: DataStoreRepository): HttpClient {
        return HttpClient(engine) {
            ...
            install(Auth) {
                bearer {
                    loadTokens {
                        val access = dataStoreRepository.getAccessToken()?.takeIf { it.isNotBlank() }
                            ?: return@loadTokens null
                        val refresh = dataStoreRepository.getRefreshToken().orEmpty()
                        BearerTokens(access, refresh)
                    }
                    refreshTokens {
                        val refreshToken = dataStoreRepository.getRefreshToken()
                            ?: return@refreshTokens null

                        val response: RefreshResponse = client.post("$BASE_URL/auth/refresh") {
                            markAsRefreshTokenRequest()
                            contentType(ContentType.Application.Json)
                            setBody(RefreshRequest(refreshToken = refreshToken))
                        }.body()

                        val newAccess = response.accessToken ?: return@refreshTokens null
                        val newRefresh = response.refreshToken ?: refreshToken

                        dataStoreRepository.saveAccessToken(newAccess)
                        dataStoreRepository.saveRefreshToken(newRefresh)

                        BearerTokens(newAccess, newRefresh)
                    }
                    sendWithoutRequest { request ->
                        val path = request.url.encodedPath
                        path != "/auth/login" && path != "/auth/refresh"
                    }
                    cacheTokens = false
                }
            }
            ...
    }
}

We are using the dataStoreRepository to get the accessToken and refreshToken. The refreshTokens function will be triggered if we get 401 from the server.
I tried using the AuthRepository for that, but it depends on HttpClientFactory. So I ended up with a cyclic DI.
To avoid this, I wrote a basic function to refresh the token silently in refreshTokens.

This will include the Authorization header in all client requests except those mentioned in sendWithoutRequest

Profile shared module setup

Similar to login, we will create actions, state, and bloc

shared/commonMain/kotlin/auth/ui/profile/ProfileActions.kt

sealed interface ProfileActions {
    class GetProfile : ProfileActions
}

shared/commonMain/kotlin/auth/ui/profile/ProfileState.kt

data class ProfileState(
    val profileResponse: UserModel?,
    val isLoading: Boolean = false,
    val errorMessage: String? = null,
)

shared/commonMain/kotlin/auth/ui/profile/ProfileViewModel.kt

class ProfileViewModel(
    private val repository: AuthRepository,
) : ViewModel() {
    private var profileJob: Job? = null

    private val _state = MutableStateFlow(ProfileState(
        profileResponse = null,
        isLoading = false,
        errorMessage = null,
    ))

    @NativeCoroutinesState
    val state: StateFlow<ProfileState> = _state
        .stateIn(
            viewModelScope,
            SharingStarted.WhileSubscribed(5000L),
            _state.value
        )

    fun onAction(action: ProfileActions) {
        when (action) {

            is ProfileActions.GetProfile -> {
                profileJob?.cancel()
                profileJob = getProfile()
            }

        }
    }

    private fun getProfile() = viewModelScope.launch {

        _state.update {
            it.copy(
                isLoading = true
            )
        }
        repository
            .getUser().onSuccess { response ->
                _state.update {
                    it.copy(
                        isLoading = false,
                        errorMessage = null,
                        profileResponse = response
                    )
                }
            }
            .onError { error, message ->
                _state.update {
                    it.copy(
                        isLoading = false,
                        profileResponse = null,
                        errorMessage = message ?: error.toString()
                    )
                }
            }
    }

}

If the auth plugin worked as expected, those requests will succeed; if not, we will consider another solution, such as injecting the DataStoreRepository into the ProfileViewModel. Let's keep our fingers crossed.

Since our shared logic is done, we can start with the UI design

But we shouldn't forget to provide them in the DI

shared/commonMain/kotlin/di/KoinModules.kt

val sharedModule = module {
    single { DataStoreProvider(get()) }
    singleOf(::DataStoreRepositoryImpl).bind<DataStoreRepository>()
    single { HttpClientFactory.create(get(), get()) }

    singleOf(::AuthDataSource)
    singleOf(::AuthRepositoryImpl).bind<AuthRepository>()

    viewModelOf(::LoginViewModel)
    viewModelOf(::ProfileViewModel)
    ...
}

and don't forget the helpers for iOS

shared/iosMain/kotlin/di/KoinHelper.kt

class KoinHelper : KoinComponent {
    fun loginViewModel(): LoginViewModel = get()
    fun profileViewModel(): ProfileViewModel = get()
}

Android Navigation Foundation

Let's start by creating dummy Login, Home, and Profile screens. You can follow this as a guide for them

composeApp/kotlin/login/LoginScreen.kt

@Composable
fun HomeScreen(
    modifier: Modifier = Modifier,
    onProfile: () -> Unit = {},
) {

    Box(
        modifier = modifier
            .fillMaxSize(),
        contentAlignment = Alignment.Center
        ) {
        Column {
            Text(text = "Login Screen")
        }

    }
}

And for the navigation routes

composeApp/kotlin/navigation/AppRoutes.kt

object AppRoutes {
    const val Home = "home"
    const val Login = "login"
    const val Profile = "profile"
}

Make sure to add all required routes and identified there
Now for AppNavigation

composeApp/kotlin/navigation/AppNavigation.kt

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun AppNavigation(modifier: Modifier = Modifier) {

    val navController = rememberNavController()
    val navBackStackEntry by navController.currentBackStackEntryAsState()
    val currentDestination = navBackStackEntry?.destination
    val showBackNavigation = currentDestination?.route in listOf(AppRoutes.Profile)

    Scaffold(
        modifier = modifier,
        topBar = {
            TopAppBar(
                title = { Text("Kotlin Native Demo") },
                navigationIcon = {

                    if (showBackNavigation) {
                        IconButton(onClick = { navController.popBackStack() }) {
                            Icon(
                                imageVector = Icons.Default.ArrowBack,
                                contentDescription = "Back"
                            )
                        }
                    }

                }
            )
        },
        bottomBar = {

        }
    ) { innerPadding ->

        NavHost(
            navController = navController,
            startDestination = AppRoutes.Login,
            modifier = Modifier.padding(innerPadding)
        ) {
            composable(AppRoutes.Home) {
                HomeScreen()
            }
            composable(AppRoutes.Login) {
                LoginScreen()
            }
            composable(AppRoutes.Profile) {
                ProfileScreen()
            }

        }
    }
}

Now, we can pass the navigation controller to the screens to allow them to navigate for themselves, but best practices suggest keeping the navigation out.

Android Login and Profile Screen

Let's be direct

composeApp/kotlin/login/LoginScreen.kt

import org.koin.compose.viewmodel.koinViewModel

@Composable
fun LoginScreen(
    modifier: Modifier = Modifier,
    onLoginSuccess: () -> Unit = {},
    viewModel: LoginViewModel = koinViewModel()
) {

    val state by viewModel.state.collectAsState()
    var validate by remember { mutableStateOf(false) }
    val context = LocalContext.current

    LaunchedEffect(state.errorMessage) {
        state.errorMessage?.let { message ->
            Toast.makeText(context, message, Toast.LENGTH_SHORT).show()
        }
    }

    LaunchedEffect(state.loginResponse?.accessToken) {
        if (state.loginResponse?.accessToken != null) {
            onLoginSuccess()
        }
    }


    Box {
        Column(
            verticalArrangement = Arrangement.Center,
            horizontalAlignment = Alignment.CenterHorizontally,
            modifier = modifier
                .fillMaxSize()
        ) {
            Icon(
                imageVector = Icons.Default.Home,
                contentDescription = "Logo",
            )
            Text(text = "Login")
            Spacer(modifier = Modifier.height(20.dp))
            OutlinedTextField(
                value = state.username,
                onValueChange = {
                    viewModel.onAction(LoginActions.OnUsernameUpdate(it))
                },
                label = { Text("Username", color = Color.Gray) },
                isError = validate && state.username.isBlank(),
                supportingText = {
                    if (state.username.isBlank() && validate) Text("Username is required")
                },
                singleLine = true,
            )
            OutlinedTextField(
                value = state.password,
                onValueChange = {
                    viewModel.onAction(LoginActions.OnPasswordUpdate(it))
                },
                label = { Text("Password", color = Color.Gray) },
                visualTransformation = PasswordVisualTransformation(),
                keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password),
                isError = validate && state.password.isBlank(),
                supportingText = {
                    if (state.password.isBlank() && validate) Text("Password is required")
                },

                singleLine = true,
            )
            Spacer(modifier = Modifier.height(20.dp))
            Row() {
                Button(onClick = {
                    viewModel.onCancel()
                }) {
                    Text(text = "Cancel")
                }
                Spacer(modifier=Modifier.width(20.dp))
                Button(onClick = {
                    validate = true
                    if (state.username.isBlank()) {
                        Toast.makeText(context, "Username is required", Toast.LENGTH_SHORT).show()
                        return@Button
                    }
                    if (state.password.isBlank()) {
                        Toast.makeText(context, "Password is required", Toast.LENGTH_SHORT).show()
                        return@Button
                    }
                    viewModel.onAction(LoginActions.Login())
                }) {
                    Text(text = "Login")
                }

            }
        }
        if (state.isLoading) {
            Box(
                modifier = Modifier.fillMaxSize()
                    .background(color = Color.Black.copy(alpha = 0.5f)),
                contentAlignment = Alignment.Center
            ) {
                CircularProgressIndicator(
                    modifier = Modifier.size(80.dp),
                    strokeWidth = 8.dp
                )
            }
        }

    }

}

LaunchedEffect is similar to useEffect in React. When the value it listens to changes, it calls the function.
We are using the username and password statuses directly and update them with OnUsernameUpdate and OnPasswordUpdate actions.
The validate boolean is just to show errors after clicking login once.
When accessToken gets a value, we are calling onLoginSuccess. Let's update AppNavigation to handle home navigation after logging in.

composeApp/kotlin/navigation/AppNavigation.kt

...
            composable(AppRoutes.Login) {
                LoginScreen(
                    onLoginSuccess = {
                        navController.navigate(AppRoutes.Home) {
                            popUpTo(AppRoutes.Login) { inclusive = true }
                        }
                    }
                )
            }
...

The inclusive = true is to clear the stack. When clicking back, the application will close instead of going back to the login screen.

From the home screen, let's just navigate to the profile screen

composeApp/kotlin/home/HomeScreen.kt

@Composable
fun HomeScreen(
    modifier: Modifier = Modifier,
    onProfile: () -> Unit = {},
) {

    Box(
        modifier = modifier
            .fillMaxSize(),
        contentAlignment = Alignment.Center
        ) {
        Column {
            Text(text = "Home Screen")
            Button(onClick = {
                onProfile()
            }) {
                Text("Profile")
            }
        }

    }
}

and updating the navigation again.

composeApp/kotlin/navigation/AppNavigation.kt

...
            composable(AppRoutes.Home) {
                HomeScreen(
                    onProfile = {
                        navController.navigate(AppRoutes.Profile)
                    }
                )
            }
...

Finally, the profile screen.

composeApp/kotlin/profile/ProfileScreen.kt

@Composable
fun ProfileScreen(
    modifier: Modifier = Modifier,
    viewModel: ProfileViewModel = koinViewModel()
) {

    val state by viewModel.state.collectAsState()

    LaunchedEffect(Unit) {
        viewModel.onAction(ProfileActions.GetProfile())
    }

    Box(
        modifier = modifier
            .fillMaxSize(),
        contentAlignment = Alignment.Center
    ) {
        Column {
            Text(text = "Profile Screen")
            Text(text = state.profileResponse?.username ?: "...")
            Text(text = state.profileResponse?.id.toString() ?: "...")
            Text(text = state.profileResponse?.email ?: "...")
            Text(text = state.profileResponse?.firstName ?: "...")
            Text(text = state.profileResponse?.lastName ?: "...")
            Text(text = state.profileResponse?.gender ?: "...")
            Text(text = state.profileResponse?.image ?: "...")

        }
    }
}

iOS Navigation Foundation

We will try to build a similar navigation tree in iOS.

A dummy screen would look like

iosApp/home/HomeView.swift

struct HomeView: View {

    var onProfile: () -> Void = {}

    var body: some View {
        VStack {
            Text("Home Screen")
        }
        .frame(
            maxWidth: .infinity, 
            maxHeight: .infinity, 
            alignment: .top,
        )
        .padding()
    }
}

Create one for home, profile, and login. So, the app routes

iosApp/navigation/AppRoutes.swift

enum AppRoutes: Hashable {
    case home
    case login
    case profile
}

and the app navigator

iosApp/navigation/AppNavigation.swift

struct AppNavigation: View {
    @State private var path = NavigationPath()

    var body: some View {
        NavigationStack(path: $path) {
            LoginView(
                onLoginSuccess: {
                    path.append(AppRoutes.home)
                }
            )
            .navigationTitle("Login")
            .navigationBarTitleDisplayMode(.inline)
            .navigationDestination(for: AppRoutes.self) { route in
                switch route {
                case .home:
                    HomeView(
                        onProfile: {
                            path.append(AppRoutes.profile)
                        }
                    )
                    .navigationTitle("Home")
                    .navigationBarTitleDisplayMode(.inline)
                    .navigationBarBackButtonHidden(true)

                case .login:
                    LoginView(
                        onLoginSuccess: {
                            path.append(AppRoutes.home)
                        }
                    )
                    .navigationTitle("Login")
                    .navigationBarTitleDisplayMode(.inline)
                    .navigationBarBackButtonHidden(true)


                case .profile:
                    ProfileScreen()
                        .navigationTitle("Profile")
                        .navigationBarTitleDisplayMode(.inline)

                }

            }
        }
    }
}

iOS Login and Profile Screens

Great, now for the login view model wrapper

iosApp/login/LoginViewModelWrapper.swift

import Foundation
import Shared
import KMPNativeCoroutinesCombine
import Combine

final class LoginViewModelWrapper: ObservableObject {
    @Published var lastUpdated = Date()

    let viewModel: LoginViewModel = KoinHelper().loginViewModel()
    private var cancellables = Set<AnyCancellable>()

    init() {
        createPublisher(for: viewModel.stateFlow)
            .receive(on: DispatchQueue.main)
            .sink { _ in } receiveValue: { [weak self] _ in
                self?.lastUpdated = Date()
            }
            .store(in: &cancellables)
    }
}

This is a generic view model wrapper that I usually use in iOS

for the login screen

iosApp/login/LoginView.swift

import Shared

struct LoginView: View {
    var onLoginSuccess: () -> Void = {}

    @StateObject private var wrapper = LoginViewModelWrapper()
    @State private var validate = false
    @State private var showErrorAlert = false
    @State private var errorAlertText = ""
    @State private var lastErrorMessage: String?
    @State private var didCompleteLogin = false

    var body: some View {
        let state = wrapper.viewModel.state

        ZStack {
            VStack(spacing: 0) {
                Spacer(minLength: 0)

                Image(systemName: "person.crop.square.fill")
                    .font(.system(size: 72))
                    .foregroundStyle(.blue.gradient)
                    .accessibilityLabel("Logo")

                Text("Login")
                    .font(.title2)
                    .fontWeight(.semibold)
                    .padding(.top, 12)

                Spacer()
                    .frame(height: 20)

                VStack(alignment: .leading, spacing: 8) {
                    TextField("Username", text: Binding(
                        get: { state.username },
                        set: { wrapper.viewModel.onAction(action: LoginActionsOnUsernameUpdate(username: $0)) }
                    ))
                    .textFieldStyle(.roundedBorder)
                    .textInputAutocapitalization(.never)
                    .autocorrectionDisabled()

                    if validate && state.username.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
                        Text("Username is required")
                            .font(.caption)
                            .foregroundStyle(.red)
                    }
                }

                VStack(alignment: .leading, spacing: 8) {
                    SecureField("Password", text: Binding(
                        get: { state.password },
                        set: { wrapper.viewModel.onAction(action: LoginActionsOnPasswordUpdate(password: $0)) }
                    ))
                    .textFieldStyle(.roundedBorder)

                    if validate && state.password.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
                        Text("Password is required")
                            .font(.caption)
                            .foregroundStyle(.red)
                    }
                }
                .padding(.top, 12)

                Spacer()
                    .frame(height: 20)

                HStack(spacing: 20) {
                    Button("Cancel") {
                        wrapper.viewModel.onCancel()
                    }
                    .buttonStyle(.bordered)

                    Button("Login") {
                        validate = true
                        let username = state.username.trimmingCharacters(in: .whitespacesAndNewlines)
                        let password = state.password.trimmingCharacters(in: .whitespacesAndNewlines)
                        if username.isEmpty {
                            errorAlertText = "Username is required"
                            showErrorAlert = true
                            return
                        }
                        if password.isEmpty {
                            errorAlertText = "Password is required"
                            showErrorAlert = true
                            return
                        }
                        lastErrorMessage = nil
                        wrapper.viewModel.onAction(
                            action: LoginActionsLogin()
                        )
                    }
                    .buttonStyle(.borderedProminent)
                }

                Spacer(minLength: 0)
            }
            .frame(maxWidth: .infinity, maxHeight: .infinity)
            .padding(.horizontal, 24)

            if state.isLoading {
                Color.black.opacity(0.5)
                    .ignoresSafeArea()
                ProgressView()
                    .scaleEffect(1.5)
                    .tint(.white)
            }
        }
        .onChange(of: wrapper.lastUpdated) { _, _ in
            let current = wrapper.viewModel.state

            // Success: navigate to home; ViewModel clears errorMessage on success.
            if !didCompleteLogin, current.loginResponse != nil {
                didCompleteLogin = true
                onLoginSuccess()
                return
            }

            // Failure: show server / network message only when there is no success token.
            if current.loginResponse == nil,
               let message = current.errorMessage,
               !message.isEmpty,
               message != lastErrorMessage {
                lastErrorMessage = message
                errorAlertText = message
                showErrorAlert = true
            }
        }
        .alert("Error", isPresented: $showErrorAlert) {
            Button("OK", role: .cancel) {}
        } message: {
            Text(errorAlertText)
        }
    }
}

We are following the same guidelines in Android. Notice that LoginActionsOnUsernameUpdate is the same as LoginActions.OnUsernameUpdate.

for home screen

struct HomeView: View {

    var onProfile: () -> Void = {}
    var onProducts: () -> Void = {}

    var body: some View {
        VStack {

            Text("Home Screen")

            Button("Profile") {
                onProfile()
            }
        }
        .frame(
            maxWidth: .infinity,
            maxHeight: .infinity,
            alignment: .top,
        )
        .padding()
    }
}

And finally, the profile screen view model

iosApp/profile/ProfileViewModelWrapper.swift

import Foundation
import Shared
import KMPNativeCoroutinesCombine
import Combine

final class ProfileViewModelWrapper: ObservableObject {
    @Published var lastUpdated = Date()

    let viewModel: ProfileViewModel = KoinHelper().profileViewModel()
    private var cancellables = Set<AnyCancellable>()

    init() {
        createPublisher(for: viewModel.stateFlow)
        .receive(on: DispatchQueue.main)
        .sink { _ in } receiveValue: { [weak self] _ in
            self?.lastUpdated = Date()
        }
        .store(in: &cancellables)
    }
}

iosApp/profile/ProfileView.swift

struct ProfileScreen: View {

    @StateObject private var wrapper = ProfileViewModelWrapper()
    @State private var showErrorAlert = false
    @State private var errorAlertText = ""
    @State private var lastErrorMessage: String?

    var body: some View {
        let state = wrapper.viewModel.state

        ZStack {
            VStack(alignment: .leading, spacing: 8) {
                Text("Profile Screen")
                Text(state.profileResponse?.username ?? "...")
                Text("\(state.profileResponse?.id ?? 0)")
                Text(state.profileResponse?.email ?? "...")
                Text(state.profileResponse?.firstName ?? "...")
                Text(state.profileResponse?.lastName ?? "...")
                Text(state.profileResponse?.gender ?? "...")
                Text(state.profileResponse?.image ?? "...")
            }

            if state.isLoading {
                Color.black.opacity(0.5)
                    .ignoresSafeArea()
                ProgressView()
                    .scaleEffect(1.4)
                    .tint(.white)
            }
        }
        .frame(maxWidth: .infinity, maxHeight: .infinity)
        .onAppear {
            wrapper.viewModel.onAction(action: ProfileActionsGetProfile())
        }
        .onChange(of: wrapper.lastUpdated) { _, _ in
            let current = wrapper.viewModel.state
            if let message = current.errorMessage,
               !message.isEmpty,
               message != lastErrorMessage {
                lastErrorMessage = message
                errorAlertText = message
                showErrorAlert = true
            }
        }
        .alert("Error", isPresented: $showErrorAlert) {
            Button("OK", role: .cancel) {}
        } message: {
            Text(errorAlertText)
        }
    }
}

And we are done here. I hope everything worked as expected. Write a comment if it didn't.
Believe me when I say it is not easy

KMP Native UI networking with Ktro

Saad Alkentar — Mon, 30 Mar 2026 16:21:35 +0000

We have our dependency injection ready and have tested our dummy view model on both Android and iOS. It is time to get some data...

We need to pay attention to the project structure at this stage. Clean architecture has 3 layers,

data: contains data sources and repository implementation
domain: contains the abstract logic of the application
presentation or UI, contains the view models, actions, states, and screens

In KMP, the screens themselves are in the Native Projects, while the rest of the data, domain, and presentation are in the shared codebase.

The final repository can be found here

What are the app features?

For our simple project, we will add two features.

Products feature: where we can list products and show their details.
Auth feature: Where we can fill in the login form and navigate to the home screen.

Where to get it from?

I found a website called dummy json that provides both Auth and Products endpoints. In this tutorial, we will only use the Products api. The auth will be used in another tutorial.

Setup Ktor client library

Let's start by updating the toml file. According to ktor docs we should add those libs.

[versions]
ktor = "3.4.1"

[libraries]
ktor-client-core = { module = "io.ktor:ktor-client-core", version.ref = "ktor" }
ktor-client-okhttp = { module = "io.ktor:ktor-client-okhttp", version.ref = "ktor" }
ktor-client-darwin = { module = "io.ktor:ktor-client-darwin", version.ref = "ktor" }

# ktor extensions
ktor-client-content-negotiation = { module = "io.ktor:ktor-client-content-negotiation", version.ref = "ktor" }
ktor-client-logging = { module = "io.ktor:ktor-client-logging", version.ref = "ktor" }
ktor-serialization-kotlinx-json = { module = "io.ktor:ktor-serialization-kotlinx-json", version.ref = "ktor" }
ktor-client-auth = { module = "io.ktor:ktor-client-auth", version.ref = "ktor" }

[bundles]
ktor = [
    "ktor-client-core",
    "ktor-client-content-negotiation",
    "ktor-client-auth",
    "ktor-client-logging",
    "ktor-serialization-kotlinx-json",
]

The next step is to update build.gradle

shared/build.gradle.kts


plugins {
    ...
    alias(libs.plugins.kotlinSerialization) // for model class serialization
}

kotlin {
    ...
    sourceSets {
        commonMain.dependencies {
            ...
            implementation(libs.koin.ktor)
            implementation(libs.bundles.ktor)
        }

        androidMain.dependencies {
            implementation(libs.ktor.client.okhttp)
        }

        nativeMain.dependencies {
            implementation(libs.ktor.client.darwin)
        }
        ...
    }
}

Set up Ktor with Koin

Let's start by creating the Ktor client and setting up the Logger, JSON serializer, content type, and timeout.

shared/commonMain/core/data/HttpClientFactory.kts

import io.ktor.client.HttpClient
import io.ktor.client.engine.HttpClientEngine
import io.ktor.client.plugins.HttpTimeout
import io.ktor.client.plugins.contentnegotiation.ContentNegotiation
import io.ktor.client.plugins.defaultRequest
import io.ktor.client.plugins.logging.LogLevel
import io.ktor.client.plugins.logging.Logger
import io.ktor.client.plugins.logging.Logging
import io.ktor.http.ContentType
import io.ktor.http.contentType
import io.ktor.serialization.kotlinx.json.json
import kotlinx.serialization.json.Json

object HttpClientFactory {

    fun create(engine: HttpClientEngine): HttpClient {
        return HttpClient(engine) {
            install(ContentNegotiation) {
                json(
                    json = Json {
                        ignoreUnknownKeys = true
                    }
                )
            }
            install(HttpTimeout) {
                socketTimeoutMillis = 20_000L
                requestTimeoutMillis = 20_000L
            }
            install(Logging) {
                logger = object : Logger {
                    override fun log(message: String) {
                        println(message)
                    }
                }
                level = LogLevel.ALL
            }
            defaultRequest {
                contentType(ContentType.Application.Json)
            }
        }
    }
}

Then, we create the client factory singleton to be used in data sources later

shared/commonMain/di/KoinModules.kt

val sharedModule = module {
    single { HttpClientFactory.create(get()) }
    ...
}

expect val platformModule: Module

Now for the module-level setup

shared/androidMain/di/PlatformModule.android.kt

import io.ktor.client.engine.HttpClientEngine
import io.ktor.client.engine.okhttp.OkHttp
import org.koin.dsl.module

actual val platformModule = module {
    single<HttpClientEngine> { OkHttp.create() }
}

shared/iosMain/di/PlatformModule.ios.kt

import io.ktor.client.engine.HttpClientEngine
import io.ktor.client.engine.darwin.Darwin
import org.koin.dsl.module

actual val platformModule = module {
    single<HttpClientEngine> { Darwin.create() }
}

Products Clean Architecture shared module

Create the product structure in the shared modules

-shared
--commonMein

---product

----data
-----ProductDataSource.kt
-----ProductRepositoryImpl.kt

----domain
-----models
-----ProductRepository.kt

----ui
-----ProductActions.kt
-----ProductState.kt
-----ProductViewModel.kt

JSON objects to Kotlin classes

Where to get the products from? For this tutorial, we can get it from dummy json api.
As always in clean architecture, we start from the domain layer.
We will use JSON To Kotlin Class to convert JSON to Kotlin classes

To parse JSON to Kotlin models, we start by left-clicking the models folder. With one click, we get the Product class (I've renamed every model to have model postfix. Make sure to annotate the classes as @Serializable
I grow not to trust the backend devs (even if it's me!). So I usually edit the advanced setting to make all fields nullable and to annotate them with Kotlin serialization

shared/commonMain/product/domain/models/ProductModel.kt

import kotlinx.serialization.Serializable

@Serializable
data class ProductModel(
    @SerialName("availabilityStatus")
    val availabilityStatus: String? = null,
    @SerialName("brand")
    val brand: String? = null,
    @SerialName("category")
    val category: String? = null,
    @SerialName("description")
    val description: String? = null,
    @SerialName("dimensions")
    val dimensions: DimensionsModel? = null,
    @SerialName("discountPercentage")
    val discountPercentage: Double? = null,
    @SerialName("id")
    val id: Int? = null,
    @SerialName("images")
    val images: List<String>? = null,
    @SerialName("meta")
    val meta: MetaModel? = null,
    @SerialName("minimumOrderQuantity")
    val minimumOrderQuantity: Int? = null,
    @SerialName("price")
    val price: Double? = null,
    @SerialName("rating")
    val rating: Double? = null,
    @SerialName("returnPolicy")
    val returnPolicy: String? = null,
    @SerialName("reviews")
    val reviews: List<ReviewModel>? = null,
    @SerialName("shippingInformation")
    val shippingInformation: String? = null,
    @SerialName("sku")
    val sku: String? = null,
    @SerialName("stock")
    val stock: Int? = null,
    @SerialName("tags")
    val tags: List<String>? = null,
    @SerialName("thumbnail")
    val thumbnail: String? = null,
    @SerialName("title")
    val title: String? = null,
    @SerialName("warrantyInformation")
    val warrantyInformation: String? = null,
    @SerialName("weight")
    val weight: Int? = null
)

Now for the product response model

shared/commonMain/product/domain/models/ProductResponse.kt

import kotlinx.serialization.Serializable

@Serializable
data class ProductResponse(
    @SerialName("limit")
    val limit: Int? = null,
    @SerialName("products")
    val products: List<ProductModel>? = null,
    @SerialName("skip")
    val skip: Int? = null,
    @SerialName("total")
    val total: Int? = null
)

PS. Notice that I'm creating the models in the domain layer. In the clean architecture standard, they suggest creating the API / database models in the data layer and then mapping them to the domain layer models.
Well ... most companies use a clean API designed to suit the UI needs, and this mapping processing makes things more complicated.

From a real-life scenario with the suggested clean architecture:

They changed the API response because they want to add an extra field in the UI.
We need to update the models in the data layer.
Then we need to update the models in the domain layer.
Then, we need to update the models' mapping process between them
Finally, update the UI.

Removing the data layer models will save us at least two steps; I believe it is an improvement for a well-designed API.

Products repository

shared/commonMain/product/domain/ProductRepository.kt

interface ProductRepository {

    suspend fun getProductsList() : List<ProductModel>
    suspend fun getProductsItem(id: Int) : ProductModel

}

Data layer, Products DataSource

It is time to start with the data layer.

shared/commonMain/product/data/ProductDataSource.kt

import io.ktor.client.HttpClient
import io.ktor.client.request.get
import io.ktor.client.request.parameter
import io.ktor.client.statement.HttpResponse

class ProductDataSource(
    private val httpClient: HttpClient
) {
    suspend fun productList(
        limit: Int = 10,
        skip: Int = 0,
        sortBy: String = "title",
        order: String = "asc",
    ): HttpResponse {
        return httpClient.get(
            urlString = "$BASE_URL/products/"
        ) {
            parameter("limit", limit)
            parameter("skip", skip)
            parameter("sortBy", sortBy)
            parameter("order", order)
        }
    }

    suspend fun productGet(
        id: Int,
    ): HttpResponse {
        return httpClient.get(
            urlString = "$BASE_URL/products/$id"
        )
    }
}

It is time to implement the products repository in the data layer

shared/commonMain/product/data/ProductRepositoryImpl.kt

class ProductRepositoryImpl(
    private val dataSource: ProductDataSource
) : ProductRepository {

    override suspend fun getProductsList(): List<ProductModel> {
        TODO("Not yet implemented")
    }

    override suspend fun getProductsItem(id: Int): ProductModel {
        TODO("Not yet implemented")
    }

}

We need a way to map the HttpResponse to the desired response. And how to inform the UI of any possible errors? I found a great solution from Philipp Lackner videos and tweaked it a little here

Let's create a helper model to allow that. I'll call it DataState

shared/commonMain/core/domain/DataState.kt

// the basic class
sealed interface DataState<out D, out E: DataError> {
    data class Success<out D>(val data: D): DataState<D, Nothing>
    data class Error<out E: DataError>(val error: E, val message: String? = null):
        DataState<Nothing, E>
}

// class extension to map response
inline fun <T, E: DataError, R> DataState<T, E>.map(map: (T) -> R): DataState<R, E> {
    return when(this) {
        is DataState.Error -> DataState.Error(error = error, message = message)
        is DataState.Success -> DataState.Success(map(data))
    }
}

// another extension for empty response
fun <T, E: DataError> DataState<T, E>.asEmptyDataResult(): EmptyResult<E> {
    return map {  }
}

// an extension to map success state
inline fun <T, E: DataError> DataState<T, E>.onSuccess(action: (T) -> Unit): DataState<T, E> {
    return when(this) {
        is DataState.Error -> this
        is DataState.Success -> {
            action(data)
            this
        }
    }
}

// an extension to map error state
inline fun <T, E: DataError> DataState<T, E>.onError(action: (E, String?) -> Unit): DataState<T, E> {
    return when(this) {
        is DataState.Error -> {
            action(error, message)
            this
        }
        is DataState.Success -> this
    }
}

typealias EmptyResult<E> = DataState<Unit, E>

shared/commonMain/core/domain/DataError.kt

sealed interface DataError {
    enum class Remote: DataError {
        REQUEST_TIMEOUT,
        TOO_MANY_REQUESTS,
        NO_INTERNET,
        SERVER,
        SERIALIZATION,
        UNKNOWN
    }

}

Let's create a wrapper function to make network calls safer to handle

shared/commonMain/core/data/HttpClientExt.kt

import io.ktor.client.call.NoTransformationFoundException
import io.ktor.client.call.body
import io.ktor.client.network.sockets.SocketTimeoutException
import io.ktor.client.statement.HttpResponse
import io.ktor.client.statement.bodyAsText
import io.ktor.util.network.UnresolvedAddressException
import kotlinx.coroutines.ensureActive
import kotlin.coroutines.coroutineContext
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.contentOrNull
import kotlinx.serialization.json.jsonObject
import kotlinx.serialization.json.jsonPrimitive


suspend inline fun <reified T> safeCall(
    execute: () -> HttpResponse
): DataState<T, DataError.Remote> {
    val response = try {
        execute()
    } catch(e: SocketTimeoutException) {
        return DataState.Error(DataError.Remote.REQUEST_TIMEOUT, e.message)
    } catch(e: UnresolvedAddressException) {
        return DataState.Error(DataError.Remote.NO_INTERNET, e.message)
    } catch (e: Exception) {
        coroutineContext.ensureActive()
        return DataState.Error(DataError.Remote.UNKNOWN, e.message)
    }

    return responseToResult(response)
}

suspend inline fun <reified T> responseToResult(
    response: HttpResponse
): DataState<T, DataError.Remote> {
    return when(response.status.value) {
        in 200..299 -> {
            try {
                DataState.Success(response.body<T>())
            } catch(e: NoTransformationFoundException) {
                DataState.Error(DataError.Remote.SERIALIZATION)
            }
        }
        400 -> DataState.Error(DataError.Remote.SERVER, response.extractErrorMessage())
        401 -> DataState.Error(DataError.Remote.SERVER, response.extractErrorMessage())
        408 -> DataState.Error(DataError.Remote.REQUEST_TIMEOUT, response.extractErrorMessage())
        429 -> DataState.Error(DataError.Remote.TOO_MANY_REQUESTS, response.extractErrorMessage())
        in 500..599 -> DataState.Error(DataError.Remote.SERVER, response.extractErrorMessage())
        else -> DataState.Error(DataError.Remote.UNKNOWN, response.extractErrorMessage())
    }
}


// this function gets the error message from the error response based on the response schema
// a dummyjson error response contains one field `details` which contains the error message
// update this function to match your api error response
suspend fun HttpResponse.extractErrorMessage(): String? {
    return runCatching {
        val rawBody = bodyAsText()
        Json.parseToJsonElement(rawBody)
            .jsonObject["details"]
            ?.jsonPrimitive
            ?.contentOrNull
            ?.takeIf { it.isNotBlank() }
    }.getOrNull()
}

With our new helper model, we must update the repository and the repository implementation

shared/commonMain/product/domain/ProductRepository.kt

interface ProductRepository {

    suspend fun getProductsList() : DataState<List<ProductModel>, DataError.Remote>
    suspend fun getProductsItem(id: Int) : DataState<ProductModel, DataError.Remote>
}

and the implementation should look like

shared/commonMain/product/data/ProductRepositoryImpl.kt

class ProductRepositoryImpl(
    private val dataSource: ProductDataSource
) : ProductRepository {
    override suspend fun getProductsList(): DataState<List<ProductModel>, DataError.Remote> =
        safeCall<ProductResponse> {
            dataSource.productList()
        }.map { it.products ?: emptyList() }

    override suspend fun getProductsItem(id: Int): DataState<ProductModel, DataError.Remote> =
        safeCall<ProductModel> {
            dataSource.productGet(id=id)
        }
}

We used the map extension function in the getProductsList to return the list directly. We can pass the limit, skip, sortBy, order parameters if needed, but we are not passing them to simplify this tutorial.

Presentation layer, Bloc ViewModel

I'm a fan of Bloc library in Flutter, so I'll try to build a similar logic with the View-Model. Best practices suggest one state per screen

There is only one action for this screen: getting data.
You might have a filter action, a search action, and a pagination action for the actual app.

shared/commonMain/product/ui/ProductActions.kt

sealed interface ProductAction {

    class GetProductsList: ProductAction
    data class GetProductsItem(val id: Int): ProductAction
    data class GetProductsPage(val limit: Int, val skip: Int): ProductAction

}

shared/commonMain/product/ui/ProductState.kt

data class ProductState (
    val productsList: List<ProductModel> = emptyList(),
    val isLoading: Boolean = false,
    val errorMessage: String? = null
)

shared/commonMain/product/ui/ProductViewModel.kt

class ProductViewModel(
    private val repository: ProductRepository
) : ViewModel() {

    private var productsJob: Job? = null

    private val _state = MutableStateFlow(
        ProductState(
            productsList = emptyList(),
            isLoading = false,
            errorMessage = null
        )
    )

    @NativeCoroutinesState
    val state: StateFlow<ProductState> = _state
        .stateIn(
            viewModelScope,
            SharingStarted.WhileSubscribed(5000L),
            _state.value
        )


    fun onAction(action: ProductAction) {
        when (action) {
            is ProductAction.GetProductsList -> {
                productsJob?.cancel()
                productsJob = getProductsList()
            }

            is ProductAction.GetProductsItem -> {
                TODO("Not yet implemented")
            }

            is ProductAction.GetProductsPage -> {
                TODO("Not yet implemented")
            }

        }

    }


    private fun getProductsList() = viewModelScope.launch {
        _state.update {
            it.copy(
                isLoading = true
            )
        }

        repository.getProductsList()
            .onSuccess { response ->
                _state.update {
                    it.copy(
                        isLoading = false,
                        errorMessage = null,
                        productsList = response
                    )
                }
            }
            .onError { error, message ->
                _state.update {
                    it.copy(
                        isLoading = false,
                        productsList = emptyList(),
                        errorMessage = message ?: error.toString()
                    )
                }
            }
    }
}

Dependency Injection for Products repository

We should provide the required dependencies for HttpClientFactory, ProductDataSource, and ProductRepositoryImpl

shared/commonMain/di/KoinModules.kt

val sharedModule = module {
    single { HttpClientFactory.create(get()) }
    singleOf(::ProductDataSource)
    singleOf(::ProductRepositoryImpl).bind<ProductRepository>()

    viewModelOf(::ProductViewModel)
    // ...
}

expect val platformModule: Module

We have two options for view models injection, either as a singleton or as a view model. View model injection keeps the model alive with the view context. The view dies, the model dies along with it, but singleton DI keeps it alive the whole time.
We will use viewModelOf, since it is cleaner, but you can use either.

For iOS DI to work, we need to use the iOS helper class

shared/iosMain/di/KoinHelper.kt

class KoinHelper : KoinComponent {
    fun productsViewModel() = get<ProductViewModel>()
    // ...
}

Finally ... it is time for the UI

Products list in Android (Finally)

I'll be short on this; The native code is part of the UI (presentation) layer. It will reflect the same project structure, a folder for every app module (Product). It will include the ProductScreen and its components.

Make sure to implement the Koin view model in the Android module before using it in the screen

composeApp/build.gradle.kts

kotlin {
    ...
    sourceSets {
        ...
        commonMain.dependencies {
            ...
            implementation(libs.koin.compose)
            implementation(libs.koin.compose.viewmodel)
        }
    }
}

Now, for the screen design... I promis to improve it in later tutorials, so accept this basic design for now.

composeApp/kotlin/product/ProductScreen.kt

import org.koin.compose.viewmodel.koinViewModel

@Composable
fun ProductScreen(
    modifier: Modifier = Modifier,
    viewModel: ProductViewModel = koinViewModel()
) {
    val state by viewModel.state.collectAsState()

    LaunchedEffect(Unit) {
        viewModel.onAction(ProductAction.GetProductsList())
    }

    LazyColumn(
        modifier = modifier
            .fillMaxSize()
    ) {
        items(state.productsList.size) { index ->
            val product = state.productsList[index]
            ProductItem(product = product)
        }
    }
}

@Composable
fun ProductItem(product: ProductModel, modifier: Modifier = Modifier) {

    val imageUrl = product.thumbnail ?: product.images?.firstOrNull { it.isNotBlank() }

    Row(
        modifier = modifier
            .padding(vertical = 5.dp, horizontal = 5.dp)
    ) {
        Image(
            modifier = Modifier.padding(end = 5.dp).width(80.dp),
            painter = painterResource(id = R.drawable.ic_launcher_background),
            contentDescription = product.title,
        )

        Column {
            Text(text = product.title ?: "")
            Text(text = product.description ?: "")
        }
    }

}

We are using LaunchedEffect to issue a "get products list" action. We can do it in the init function of the view model too

shared/commonMain/product/ui/ProductViewModel.kt

class ProductViewModel(
    private val repository: ProductRepository
) : ViewModel() {

    private var productsJob: Job? = null

    private val _state = MutableStateFlow(
        ProductState(
            productsList = emptyList(),
            isLoading = false,
            errorMessage = null
        )
    )

    init {
        onAction(ProductAction.GetProductsList()) // new
    }
    //...
}

Then we won't need the LaunchedEffect, but I prefer it with LaunchedEffect

To show the screen ...

composeApp/kotlin/MainActivity.kt

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        initKoin()
        enableEdgeToEdge()
        super.onCreate(savedInstanceState)

        setContent {
            ProductScreen()
        }
    }
}

Products list in iOS (Finally * 2)

We start by creating ProductViewModel wrapper for iOS

iosApp/product/ProductViewModelWrapper.swift

import Foundation
import Shared
import KMPNativeCoroutinesCombine
import Combine

final class ProductViewModelWrapper: ObservableObject {
    @Published var lastUpdated = Date()

    let viewModel: ProductViewModel = KoinHelper().productsViewModel()
    private var cancellables = Set<AnyCancellable>()

    init() {
        createPublisher(for: viewModel.stateFlow)
        .receive(on: DispatchQueue.main)
        .sink { _ in } receiveValue: { [weak self] _ in
            self?.lastUpdated = Date()
        }
        .store(in: &cancellables)
    }
}

and the list screen

iosApp/product/ProductScreen.swift

import SwiftUI
import Shared

struct ProductScreen: View {
    @StateObject private var wrapper = ProductViewModelWrapper()
    @State private var showErrorAlert = false
    @State private var errorAlertText = ""
    @State private var lastErrorMessage: String?

    var body: some View {
        let state = wrapper.viewModel.state

        ZStack {
            List {
                ForEach(Array(state.productsList.enumerated()), id: \.offset) { _, product in
                    ProductItemView(product: product)
                }
            }
            .listStyle(.plain)

            if state.isLoading {
                Color.black.opacity(0.5)
                    .ignoresSafeArea()
                ProgressView()
                    .scaleEffect(1.4)
                    .tint(.white)
            }
        }
        .onAppear {
            wrapper.viewModel.onAction(action: ProductActionGetProductsList())
        }
        .onChange(of: wrapper.lastUpdated) { _, _ in
            let current = wrapper.viewModel.state
            if let message = current.errorMessage,
               !message.isEmpty,
               message != lastErrorMessage {
                lastErrorMessage = message
                errorAlertText = message
                showErrorAlert = true
            }
        }
        .alert("Error", isPresented: $showErrorAlert) {
            Button("OK", role: .cancel) {}
        } message: {
            Text(errorAlertText)
        }
    }
}

private struct ProductItemView: View {
    let product: ProductModel

    var body: some View {
        HStack(alignment: .top, spacing: 8) {
            AsyncImage(url: URL(string: product.thumbnail ?? product.images?.first ?? "")) { phase in
                switch phase {
                case .success(let image):
                    image
                        .resizable()
                        .scaledToFill()
                case .failure(_), .empty:
                    Image(systemName: "photo")
                        .resizable()
                        .scaledToFit()
                        .padding(16)
                        .foregroundStyle(.secondary)
                @unknown default:
                    EmptyView()
                }
            }
            .frame(width: 80, height: 80)
            .background(Color.gray.opacity(0.15))
            .clipShape(RoundedRectangle(cornerRadius: 8))

            VStack(alignment: .leading, spacing: 4) {
                Text(product.title ?? "")
                    .font(.headline)
                    .lineLimit(1)
                Text(product.description_ ?? "")
                    .font(.subheadline)
                    .foregroundStyle(.secondary)
                    .lineLimit(2)
            }
        }
        .padding(.vertical, 4)
    }
}

and to show it

iosApp/iOSApp.swift

@main
struct iOSApp: App {
    init() {
        KoinInitIosKt.doInitKoinIos()
    }
    var body: some Scene {
        WindowGroup {
            ProductScreen()
        }
    }
}

Thanks for reading this very very long article

No such module 'Shared' fixed for KMP Xcode

Saad Alkentar — Tue, 24 Mar 2026 19:09:12 +0000

I believe you have already tried to open Kotlin multi-platform iOS project in Xcode, and voalla, No such module 'Shared'

Let's jump directly to the solution. You can also find the solution here

Start by choosing to edit schemas in Xcode

Then add the script as a pre-build action

cd "$SRCROOT/.."
./gradlew :shared:embedAndSignAppleFrameworkForXcode

and make sure to select to provide the build settings from iosApp

Time to try to build again, success? Good for you, same error? move on ...
Let's debug the script to find the issue

echo "Hello world"
cd "$SRCROOT/.."
./gradlew :shared:embedAndSignAppleFrameworkForXcode

The operation couldn’t be completed. Unable to locate a Java Runtime.
Please visit http://www.java.com for information on installing Java.

So, couldn't find the Java runtime...

I need to set JAVA_HOME. We can do it on the system level, the script level, or on the project level. I'll choose the third.
Select your project, project properties, click the add button, and add a user-defined setting.

and add the JAVA_HOME env var

For my device, the path is

export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"

It should build successfully now

Stay tuned for Networking with KMP

KMP Native UI view model injection for iOS and Android

Saad Alkentar — Mon, 23 Mar 2026 13:06:18 +0000

Cross-platform development significantly reduces overhead for both developers and organizations. While React Native leveraged web expertise and Flutter introduced a unified UI for multi-platform delivery, Kotlin Multiplatform (KMP) represents the next evolution. KMP offers the flexibility of Compose for shared UI, while uniquely allowing developers to implement native interfaces where maximum performance and stability are required—all while maintaining a single shared logic base in Kotlin.

Finding comprehensive resources for Kotlin Multiplatform (KMP) using Native UI can be challenging, so this series aims to bridge that gap.

We will build a production-ready foundation using a modular Clean Architecture—the industry standard for scalable apps. Our roadmap covers the essential pillars of modern development:

Dependency Injection (Koin),
Networking (Ktor),
and Architecture (Clean Architecture).

In this article, we will test the dependency injection setup by injecting a view model for iOS and Android. Be sure to follow the previous article for setting up Koin di.

The final repository can be found here

View model library

let's start by updating the shared module shared/build.gradle.kts

...
kotlin {
    ...
    sourceSets {
        commonMain.dependencies {
            ...
            implementation(libs.androidx.lifecycle.viewmodelCompose)

        }
        ...
    }
}

It should already be in the toml file, if not, you can add it

[versions]
androidx-lifecycle = "2.9.6"

[libraries]
androidx-lifecycle-viewmodelCompose = { module = "org.jetbrains.androidx.lifecycle:lifecycle-viewmodel-compose", version.ref = "androidx-lifecycle" }

Let's create a simple view model to make sure DI works as expected

A simple shared ViewModel

In the shared module, we create a view model.

// shared/kotlin/home/HomeViewModel.kt

import androidx.lifecycle.ViewModel
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow

class HomeViewModel : ViewModel() {
    private val _state = MutableStateFlow("initial state")

    val state: StateFlow<String> = _state.asStateFlow()

    fun updateString(newString: String) {
        _state.value = newString
    }
}

Inject our ViewModel where needed

We need to provide our view model in the shared Koin module in order to use it in other platforms

shared/commonMain/di/KoinModules.kt

import org.koin.core.module.dsl.singleOf
import org.koin.core.module.dsl.viewModelOf
import org.koin.core.module.Module

val sharedModule = module {
    //...
    singleOf(::HomeViewModel)
}

We have multiple injection options, either as a singleton singleOf or as a view model viewModelOf. Singletons will never die (until you close the app), view models are attached to a single screen context and will die with it. I'll use viewModelOf in the coming tutorials, so I'll keep it as a singleton here.

View models usage in Android

We will update the App.kt to test our new view model.

// composeApp/kotlin/App.kt

...
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewmodel.compose.viewModel
import com.irsc.kotlinnativedemo.home.presentation.HomeViewModel
import org.koin.java.KoinJavaComponent.inject

@Composable
@Preview
fun App() {
    val viewModel: HomeViewModel by inject(HomeViewModel::class.java)
    val state by viewModel.state.collectAsStateWithLifecycle()

    MaterialTheme {
        var showContent by remember { mutableStateOf(false) }
        Column(
            modifier = Modifier
                .background(MaterialTheme.colorScheme.primaryContainer)
                .safeContentPadding()
                .fillMaxSize(),
            horizontalAlignment = Alignment.CenterHorizontally,
        ) {
            Button(onClick = {
                showContent = !showContent
                viewModel.updateString("new string")
            }) {
                Text("Click me!")
            }
            Text(state)
            ...
        }
    }
}

PS. If you are injecting the ViewModel as a view model, make sure to use koinViewModel instead of inject; you may need to install the koinViewModel library for the Android platform.

import org.koin.compose.viewmodel.koinViewModel
...
    val viewModel: AccountViewModel = koinViewModel()

Clicking the button should update the state, and the state flow should update the text under the button. Now we are sure the DI works in Android, the easy one, next is the iOS...

View models usage in iOS

Using view models in iOS is more challenging; the Observable class is actually the iOS ViewModel, but it is kinda tricky mapping them, according to this we have two options

KMP-NativeCoroutines: the recommended one for now
SKIE: I think it is better, but it does not support Kotlin 2.3.20; this may have changed by the time you read this article. I should create another article for it by the time.

KMP-NativeCoroutines libraries setup

We start by adding the plugins to the toml file

[versions]
ksp = "2.3.6"
nativecoroutines = "1.0.2"

[plugins]
koin-compiler = { id = "io.insert-koin.compiler.plugin", version.ref = "koin-plugin" }
devtools-ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
kmp-nativecoroutines = { id = "com.rickclephas.kmp.nativecoroutines", version.ref = "nativecoroutines" }

make sure to sync after every toml file update to help the IDE

Next, we update the root project build.gradle.kts

// build.gradle.kts
plugins {
    // this is necessary to avoid the plugins to be loaded multiple times
    // in each subproject's classloader
    ...

    alias(libs.plugins.devtools.ksp) apply false
    alias(libs.plugins.kmp.nativecoroutines) apply false

}

Then, we update the shared module build.gradle.kts

// shared/build.gradle.kts

import org.jetbrains.kotlin.gradle.dsl.JvmTarget

plugins {
    alias(libs.plugins.kotlinMultiplatform)
    alias(libs.plugins.androidLibrary)

    alias(libs.plugins.koin.compiler)
    alias(libs.plugins.devtools.ksp) // new
    alias(libs.plugins.kmp.nativecoroutines) // new
}
...

and finally, the shared module sourceSets

// shared/build.gradle.kts
kotlin {
    // ...
    sourceSets{
        all {
            languageSettings {
                optIn("kotlin.experimental.ExperimentalObjCName")
                optIn("kotlin.time.ExperimentalTime")
            }
        }
        // ...
    }
}

Nice, this should work, let's build the project ...

> Task :shared:compileKotlinIosSimulatorArm64 FAILED
error: org.jetbrains.kotlin.cli.jvm.plugins.PluginCliParser$PluginProcessingError: Plugin com.rickclephas.kmp.nativecoroutines.compiler.KmpNativeCoroutinesCompilerPluginRegistrar is incompatible with the current version of the compiler.
error: org.jetbrains.kotlin.cli.jvm.plugins.PluginCliParser$PluginProcessingError: Plugin com.rickclephas.kmp.nativecoroutines.compiler.KmpNativeCoroutinesCompilerPluginRegistrar is incompatible with the current version of the compiler.

org.jetbrains.kotlin.cli.jvm.plugins.PluginCliParser$PluginProcessingError: Plugin com.rickclephas.kmp.nativecoroutines.compiler.KmpNativeCoroutinesCompilerPluginRegistrar is incompatible with the current version of the compiler.

Caused by: java.lang.AbstractMethodError: Missing implementation of resolved method 'abstract java.lang.String getPluginId()' of abstract class org.jetbrains.kotlin.compiler.plugin.CompilerPluginRegistrar.
Caused by: java.lang.AbstractMethodError: Missing implementation of resolved method 'abstract java.lang.String getPluginId()' of abstract class org.jetbrains.kotlin.compiler.plugin.CompilerPluginRegistrar.

Those errors confused me a lot. Finding error causes in 3 platforms is kinda ugly. In short, the problem is in our stars, the Kotlin version. let's update it.

[versions]
...
kotlin = "2.3.20"
...

Syncing and building again should resolve the error.

KMP-NativeCoroutines shared code update

We should inform the NativeCoroutines of our public state flow, there are multiple options like @NativeCoroutines and @NativeCoroutinesState. Personally, I suggest to always use NativeCoroutinesState. Let's update our view model class

// shared/kotlin/home/HomeViewController.kt

import com.rickclephas.kmp.nativecoroutines.NativeCoroutinesState

class HomeViewModel : ViewModel() {
    private val _state = MutableStateFlow("initial state")

    @NativeCoroutinesState // new
    val state: StateFlow<String> = _state.asStateFlow()

    fun updateString(newString: String) {
        _state.value = newString
    }
}

Great, we need to update the iOS native project next ...

KMP-NativeCoroutines iOS project update

We need to open the iOS project in Xcode, choose to add a package dependency

look for

https://github.com/rickclephas/KMP-NativeCoroutines.git

and install KMPNativeCoroutinesAsync, KMPNativeCoroutinesCombine, and KMPNativeCoroutinesCore and finally click add packages

Nice, now we can use KMP-NativeCoroutines in iOS, let's go back to Android Studio.
PS. I know you tried to build it in Xcode and faced No such module 'Shared', we will solve this in another article

The ViewModel in Swift UI

I wanted to map ViewModel directly to @Observable Swift class, but it is still work in progress, for now we will wrap it with ObservableObject. Before that, we need to create a DI helper class

// shared/src/iosMain/kotlin/di/KoinHelper.kt

import com.irsc.kotlinnativedemo.home.presentation.HomeViewModel
import org.koin.core.component.KoinComponent
import org.koin.core.component.get


class KoinHelper : KoinComponent {
    fun homeViewModel(): HomeViewModel = get()
}

Time to create our own ObservableObject

import Foundation
import Shared
import KMPNativeCoroutinesCombine
import Combine

class HomeViewModelWrapper : ObservableObject {
    @Published var lastUpdated = Date()

    let viewModel: HomeViewModel = KoinHelper().homeViewModel()
    private var cancellables = Set<AnyCancellable>()

    init() {
        // Observe the flow, but we don't need to manually copy every field to Swift anymore
        createPublisher(for: viewModel.stateFlow)
        .receive(on: DispatchQueue.main)
        .sink { _ in } receiveValue: { [weak self] _ in
            // Just trigger a refresh; the View will read from viewModel.state directly
            self?.lastUpdated = Date()
        }
        .store(in: &cancellables)
    }

}

Let's point out a few points here

The lastUpdated field is used to trigger UI reload only.
We read data and called methods directly from the viewModel.
The state field in the view-model is reflected as stateFlow in Swift, because we are using @NativeCoroutinesState; it would be different if we used @NativeCoroutines.
This ObservableObject class blueprint should work for any type of view model
I still think an @observable class would be better, but I couldn't find the best way to deploy it yet.

Finally, let's test it in the ContentView

import SwiftUI
import Shared

struct ContentView: View {
    @State private var showContent = false
    @StateObject private var wrapper = HomeViewModelWrapper()

    var body: some View {
        VStack {
            Button("Click me!") {
                withAnimation {
                    showContent = !showContent
                    wrapper.viewModel.updateString(newString:"new string")
                }
            }
            Text(wrapper.viewModel.state)

            if showContent {
                VStack(spacing: 16) {
                    Image(systemName: "swift")
                        .font(.system(size: 200))
                        .foregroundColor(.accentColor)
                    Text("SwiftUI: \(Greeting().greet())")
                }
                .transition(.move(edge: .top).combined(with: .opacity))
            }
        }
        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .top)
        .padding()
    }
}

That is it, it wasn't too simple for iOS, I know, yet fun and reusable, I hope

We are fixing No such module 'Shared' for Xcode project next time, so
Stay tuned

KMP Native UI Dependency Injection with Koin

Saad Alkentar — Sun, 22 Mar 2026 10:44:15 +0000

Finding comprehensive resources for Kotlin Multiplatform (KMP) using Native UI can be challenging, so this series aims to bridge that gap.

We will build a production-ready foundation using a modular Clean Architecture—the industry standard for scalable apps. Our roadmap covers the essential pillars of modern development:

Dependency Injection (Koin),
Networking (Ktor),
and Architecture (Clean Architecture).

In this first installment, we’ll kick things off by implementing Dependency Injection with Koin.

The final repository can be found here

Creating a new Project

The recommended IDEs are IntelliJ IDEA and Android Studio. I'll use Android Studio

Install the KMP plugin: in the sidebar of Android Studio, select plugins
Look for "Kotlin Multiplatform" and install it
It is time to create a new Project
Complete the wizard process by choosing the project name, and do not share the UI

That is it, simple and easy

Koin Implementation Guide for Native UI

We start with:

Koin Build libs

Basically, it is this article from Koin documentation, in short:

in gradle/libs.versions.toml:

[versions]
koin = "4.2.0"
koin-plugin = "0.4.1"

[libraries]
koin-core = { module = "io.insert-koin:koin-core", version.ref = "koin" }
koin-annotations = { module = "io.insert-koin:koin-annotations", version.ref = "koin" }
koin-compose = { module = "io.insert-koin:koin-compose", version.ref = "koin" }
koin-compose-viewmodel = { module = "io.insert-koin:koin-compose-viewmodel", version.ref = "koin" }
koin-ktor = { module = "io.insert-koin:koin-ktor", version.ref = "koin" }
koin-test = { module = "io.insert-koin:koin-test", version.ref = "koin" }

[plugins]
koin-compiler = { id = "io.insert-koin.compiler.plugin", version.ref = "koin-plugin" }

In the shared module's shared/build.gradle.kts:

plugins {
    alias(libs.plugins.koin.compiler)
}

kotlin {
    ...

    sourceSets {
        commonMain.dependencies {
            implementation(libs.koin.core)
            implementation(libs.koin.annotations)
            implementation(libs.koin.compose.viewmodel)
            implementation(libs.koin.ktor) // for Ktor web client DI
        }


        commonTest.dependencies {
            implementation(libs.koin.test)
        }
    }

}

In the Android module's composeApp/build.gradle.kts

kotlin {
    ...

    sourceSets {
        ...
        commonMain.dependencies {
            ...
            implementation(libs.koin.compose) // contains android
            implementation(libs.koin.compose.viewmodel)
        }
        ...
    }
}

Compose contains the Android Koin dependency; it can be used as a common or Android dependency.

Koin Project setup

After installing all libraries, it is time to set up the code. You can follow this also to set it up

create KoinModules in the shared module

// shared/commonMain/kotlin/di/KoinModules.kt
import org.koin.core.module.Module
import org.koin.dsl.module

val sharedModule = module {

}

expect val platformModule: Module

create the platform modules, Android

// shared/androidMain/kotlin/di/PlatformModule.android.kt
import org.koin.dsl.module

actual val platformModule = module {

}

iOS:

// shared/iosMain/kotlin/di/PlatformModule.ios.kt
import org.koin.dsl.module

actual val platformModule = module {

}

Koin initialization: we start with the shared module

// shared/commonMain/kotlin/di/KoinInit.kt
import org.koin.core.context.startKoin
import org.koin.core.KoinApplication
import org.koin.dsl.KoinAppDeclaration
import org.koin.dsl.includes

fun initKoin(config: KoinAppDeclaration? = null): KoinApplication {
    return startKoin {
        includes(config)
        modules(
            sharedModule,
            platformModule
        )
    }
}

Now, with the Android module, the simplest way is to add initKoin() in the MainActivity

// composeApp/kotlin/MainActivity.kt
...
import com.irsc.kotlinnativedemo.di.initKoin

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        initKoin()
        ...
    }
}

But for the iOS module, we will follow the instructions this time. Let's start by creating KoinInitIos in the shared module.

// shared/src/iosMain/kotlin/di/KoinInitIos.kt
fun initKoinIos() {
    initKoin()
}

Now to call it in the iOS native code

import SwiftUI
import Shared

@main
struct iOSApp: App {

    init() {
        KoinInitIosKt.doInitKoinIos()
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Please notice that we are importing Shared (capital S), the Kotlin file KoinInitIos.kt is used with Kt postfix, and the function is used with do prefix

I have submitted a fix for the documentation code; hopefully, it will be fixed by the time you read this article

That is it, we have added Koin to our project successfully. The next step is to test it with view model injection

Stay tuned for the next article

Your Own Email Verification SaaS Server

Saad Alkentar — Mon, 18 Aug 2025 09:34:46 +0000

With an estimated six billion email addresses in the world, it's a huge challenge to know which ones on your contact list are valid. Many are temporary, fraudulent, or simply abandoned. Email verification is a technology designed to solve this by identifying good and bad email addresses without sending an email. It uses a variety of techniques, from simple syntax checks to more complex methods, to assess the validity of an email.

This is critical for many applications:

Marketing: Increases deliverability and ROI by ensuring your campaigns reach real people.
CRM: Keeps your customer data accurate, leading to better support and engagement.
Fraud Prevention: Helps prevent fake sign-ups and transactions on e-commerce sites.
Data Hygiene: Maintains a high-quality database for more reliable analytics.

Ultimately, email verification protects your reputation, saves you money, and ensures your communication efforts are not wasted.

The Idea

Well, to make sure an email exists, we should check

Check whether the given email address conforms to the general format requirements of valid email addresses.
Check whether the domain part of the given email address (the part behind the "@") is known as a disposable and temporary email address domain. These are often used to register dummy users in order to spam or abuse some services.
Check whether there is a valid list of servers responsible for delivering emails to the given email address.
Check whether the given email address exists by simulating an actual email delivery.

How to do that? Well... luckily, I found a Python library that does that exactly!
It is called py3-validate-email, it covers the 4 points altogether, the only weakness is NOT working with shared hosting servers, so be sure to host your project in a VPS or a dedicated server.

Django project setup

Let's start by creating the Django project and the apps for accounts, admin, and main functionality app

# install Django lib and extensions
pip install Django
pip install django-filter
pip install djangorestframework
pip install djangorestframework_simplejwt
pip install pillow

pip install py3-validate-email

# create the project
django-admin startproject saas
cd saas
python manage.py startapp app_account
python manage.py startapp app_admin
python manage.py startapp app_main

Email verification API

To simplify this step, let's skip using serializers and pass the IP as a GET parameter, in the views file

from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework.exceptions import APIException
from common.utils import *

from validate_email import validate_email

class EmailValidationView(APIView):
    permission_classes = ( )
    renderer_classes = [CustomRenderer, BrowsableAPIRenderer]

    def is_valid_email(self, email):
        is_valid = validate_email(email)
        return is_valid

    def get(self, request, *args, **kwargs):
        email = request.query_params.get('email', None)
        if not email:
            raise APIException("The 'email' query parameter is required.")

        try:
            is_valid = self.is_valid_email(email)
            return Response(is_valid)
        except Exception as e:
            raise APIException(f"Information for email address '{email}' not found.")

app_main/views.py

We are getting the Email from GET parameters, then passing it to py3-validate-email, and responding with its direct response.
Let's assign a URL for the view

from django.urls import path, include
from .views import *

urlpatterns = [
    path('email/', EmailValidationView.as_view()),
]

app_main/urls.py

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('app_main.urls')),
]

saas/urls.py

let's try it now

GET /api/email/?email=saad.zgm@gmail.com

HTTP 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "status": "success",
    "code": 200,
    "data": true,
    "message": null
}

GET /api/email/?email=saad@gmail.com

HTTP 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "status": "success",
    "code": 200,
    "data": false,
    "message": null
}

Bonus, error handling

Most issues come from smtp. Therefore, it can be useful to debug it using smtp_debug=True flag

validate_email("saad@gmail.com", smtp_debug=True)
19:42:10.715698 connect: to ('gmail-smtp-in.l.google.com', 25) None
19:42:10.890421 reply: b'220 mx.google.com ESMTP a640c23a62f3a-af921f507c1si1870667666b.448 - gsmtp\r\n'
19:42:10.890715 reply: retcode (220); Msg: b'mx.google.com ESMTP a640c23a62f3a-af921f507c1si1870667666b.448 - gsmtp'
19:42:10.890749 connect: b'mx.google.com ESMTP a640c23a62f3a-af921f507c1si1870667666b.448 - gsmtp'
19:42:10.890991 send: 'ehlo saads-MacBook-Pro.local\r\n'
19:42:10.955439 reply: b'250-mx.google.com at your service, [2a02:3035:b62:b597:7d95:8114:3e04:4156]\r\n'
19:42:10.955753 reply: b'250-SIZE 157286400\r\n'
19:42:10.955789 reply: b'250-8BITMIME\r\n'
19:42:10.956789 reply: b'250-STARTTLS\r\n'
19:42:10.956828 reply: b'250-ENHANCEDSTATUSCODES\r\n'
19:42:10.956860 reply: b'250-PIPELINING\r\n'
19:42:10.956884 reply: b'250-CHUNKING\r\n'
19:42:10.956908 reply: b'250 SMTPUTF8\r\n'
19:42:10.956957 reply: retcode (250); Msg: b'mx.google.com at your service, [2a02:3035:b62:b597:7d95:8114:3e04:4156]\nSIZE 157286400\n8BITMIME\nSTARTTLS\nENHANCEDSTATUSCODES\nPIPELINING\nCHUNKING\nSMTPUTF8'
19:42:10.958356 send: 'STARTTLS\r\n'
19:42:11.016002 reply: b'220 2.0.0 Ready to start TLS\r\n'
19:42:11.016104 reply: retcode (220); Msg: b'2.0.0 Ready to start TLS'
19:42:11.224310 send: 'ehlo saads-MacBook-Pro.local\r\n'
19:42:11.289252 reply: b'250-mx.google.com at your service, [2a02:3035:b62:b597:7d95:8114:3e04:4156]\r\n'
19:42:11.289533 reply: b'250-SIZE 157286400\r\n'
19:42:11.289568 reply: b'250-8BITMIME\r\n'
19:42:11.289595 reply: b'250-ENHANCEDSTATUSCODES\r\n'
19:42:11.289620 reply: b'250-PIPELINING\r\n'
19:42:11.289642 reply: b'250-CHUNKING\r\n'
19:42:11.289666 reply: b'250 SMTPUTF8\r\n'
19:42:11.289724 reply: retcode (250); Msg: b'mx.google.com at your service, [2a02:3035:b62:b597:7d95:8114:3e04:4156]\nSIZE 157286400\n8BITMIME\nENHANCEDSTATUSCODES\nPIPELINING\nCHUNKING\nSMTPUTF8'
19:42:11.290287 send: 'mail FROM:<saad@gmail.com>\r\n'
19:42:11.355813 reply: b'250 2.1.0 OK a640c23a62f3a-af921f507c1si1870667666b.448 - gsmtp\r\n'
19:42:11.356098 reply: retcode (250); Msg: b'2.1.0 OK a640c23a62f3a-af921f507c1si1870667666b.448 - gsmtp'
19:42:11.356577 send: 'rcpt TO:<saad@gmail.com>\r\n'
19:42:11.412227 reply: b'550-5.1.1 The email account that you tried to reach does not exist. Please try\r\n'
19:42:11.412510 reply: b"550-5.1.1 double-checking the recipient's email address for typos or\r\n"
19:42:11.412545 reply: b'550-5.1.1 unnecessary spaces. For more information, go to\r\n'
19:42:11.412575 reply: b'550 5.1.1  https://support.google.com/mail/?p=NoSuchUser a640c23a62f3a-af921f507c1si1870667666b.448 - gsmtp\r\n'
19:42:11.412633 reply: retcode (550); Msg: b"5.1.1 The email account that you tried to reach does not exist. Please try\n5.1.1 double-checking the recipient's email address for typos or\n5.1.1 unnecessary spaces. For more information, go to\n5.1.1  https://support.google.com/mail/?p=NoSuchUser a640c23a62f3a-af921f507c1si1870667666b.448 - gsmtp"
19:42:11.412835 send: 'quit\r\n'
19:42:11.463657 reply: b'221 2.0.0 closing connection a640c23a62f3a-af921f507c1si1870667666b.448 - gsmtp\r\n'
19:42:11.463919 reply: retcode (221); Msg: b'2.0.0 closing connection a640c23a62f3a-af921f507c1si1870667666b.448 - gsmtp'

validate_email("saad.zgm@gmail.com", smtp_debug=True)
19:43:07.253112 connect: to ('gmail-smtp-in.l.google.com', 25) None
19:43:07.340865 reply: b'220 mx.google.com ESMTP a640c23a62f3a-af91a295112si1970106166b.978 - gsmtp\r\n'
19:43:07.341149 reply: retcode (220); Msg: b'mx.google.com ESMTP a640c23a62f3a-af91a295112si1970106166b.978 - gsmtp'
19:43:07.341181 connect: b'mx.google.com ESMTP a640c23a62f3a-af91a295112si1970106166b.978 - gsmtp'
19:43:07.341309 send: 'ehlo saads-MacBook-Pro.local\r\n'
19:43:07.392175 reply: b'250-mx.google.com at your service, [2a02:3035:b62:b597:7d95:8114:3e04:4156]\r\n'
19:43:07.392454 reply: b'250-SIZE 157286400\r\n'
19:43:07.392475 reply: b'250-8BITMIME\r\n'
19:43:07.392492 reply: b'250-STARTTLS\r\n'
19:43:07.392521 reply: b'250-ENHANCEDSTATUSCODES\r\n'
19:43:07.392536 reply: b'250-PIPELINING\r\n'
19:43:07.392549 reply: b'250-CHUNKING\r\n'
19:43:07.392562 reply: b'250 SMTPUTF8\r\n'
19:43:07.392590 reply: retcode (250); Msg: b'mx.google.com at your service, [2a02:3035:b62:b597:7d95:8114:3e04:4156]\nSIZE 157286400\n8BITMIME\nSTARTTLS\nENHANCEDSTATUSCODES\nPIPELINING\nCHUNKING\nSMTPUTF8'
19:43:07.392728 send: 'STARTTLS\r\n'
19:43:07.463363 reply: b'220 2.0.0 Ready to start TLS\r\n'
19:43:07.463626 reply: retcode (220); Msg: b'2.0.0 Ready to start TLS'
19:43:07.667088 send: 'ehlo saads-MacBook-Pro.local\r\n'
19:43:07.741871 reply: b'250-mx.google.com at your service, [2a02:3035:b62:b597:7d95:8114:3e04:4156]\r\n'
19:43:07.743250 reply: b'250-SIZE 157286400\r\n'
19:43:07.743800 reply: b'250-8BITMIME\r\n'
19:43:07.743848 reply: b'250-ENHANCEDSTATUSCODES\r\n'
19:43:07.743876 reply: b'250-PIPELINING\r\n'
19:43:07.743900 reply: b'250-CHUNKING\r\n'
19:43:07.743924 reply: b'250 SMTPUTF8\r\n'
19:43:07.743972 reply: retcode (250); Msg: b'mx.google.com at your service, [2a02:3035:b62:b597:7d95:8114:3e04:4156]\nSIZE 157286400\n8BITMIME\nENHANCEDSTATUSCODES\nPIPELINING\nCHUNKING\nSMTPUTF8'
19:43:07.744572 send: 'mail FROM:<saad.zgm@gmail.com>\r\n'
19:43:07.785285 reply: b'250 2.1.0 OK a640c23a62f3a-af91a295112si1970106166b.978 - gsmtp\r\n'
19:43:07.785366 reply: retcode (250); Msg: b'2.1.0 OK a640c23a62f3a-af91a295112si1970106166b.978 - gsmtp'
19:43:07.785530 send: 'rcpt TO:<saad.zgm@gmail.com>\r\n'
19:43:07.957576 reply: b'250 2.1.5 OK a640c23a62f3a-af91a295112si1970106166b.978 - gsmtp\r\n'
19:43:07.957956 reply: retcode (250); Msg: b'2.1.5 OK a640c23a62f3a-af91a295112si1970106166b.978 - gsmtp'
19:43:07.958220 send: 'quit\r\n'
19:43:08.011109 reply: b'221 2.0.0 closing connection a640c23a62f3a-af91a295112si1970106166b.978 - gsmtp\r\n'
19:43:08.011380 reply: retcode (221); Msg: b'2.0.0 closing connection a640c23a62f3a-af91a295112si1970106166b.978 - gsmtp'

That is it for this tutorial. We still need to add the SaaS users/ tokens/ stats management, which we will discuss in another tutorial, so

Stay tuned 😎

Your Own GeoIP SaaS Server

Saad Alkentar — Tue, 12 Aug 2025 12:11:57 +0000

In modern web development, there's often a need to determine a user's geographical location without using the browser's Geolocation API, which requires explicit user permission. A common alternative is using GeoIP, which maps a user's IP address to a physical location.

While this is a powerful and reliable method, it's important to be aware of the costs. Many GeoIP service providers charge based on the number of API requests, and for high-traffic applications, these costs can escalate significantly.

Here's a breakdown of some popular GeoIP providers and their approximate monthly costs for a bundle of one million requests:

Provider	1 mil/month cost
https://www.ip2location.com	$27980
https://www.maxmind.com	$4664
https://ipinfo.io	$9324
https://ipgeolocation.io	$7488
https://db-ip.com	$2400
https://ipregistry.co	$1200
https://apiip.net	$312
https://ipdata.co	$1152

The Idea

In this tutorial, we're going to build our own GeoIP server. I'll walk you through setting up the core functionality of a GeoIP SaaS application using Django, the GeoIP2 library, and the DB-IP database. While this tutorial will focus on the main GeoIP feature, a separate tutorial will cover the basic setup of a SaaS server.
Let's dive in!

Django project setup

Let's start by creating the Django project and the apps for accounts, admin, and main functionality app

# install Django lib and extensions
pip install Django
pip install django-filter
pip install djangorestframework
pip install djangorestframework_simplejwt
pip install pillow

pip install geoip2

# create the project
django-admin startproject saas
cd saas
python manage.py startapp app_account
python manage.py startapp app_admin
python manage.py startapp app_main

The next step is to setup GeoIP2 library in the project settings

...
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'corsheaders',
    'rest_framework', # for restful api
    'django_filters',
    'app_account', # the apps
    'app_admin',
    'app_main',
]
...
GEOIP_PATH =os.path.join(BASE_DIR, 'geoip') # the location of ip db

saas/settings.py

Let's create a folder in the main app path with the name 'geoip' to store the IP databases in the next step.

PS. I highly recommend using the account management app from previous tutorials to save time and effort later on.

DP-IP datasets

Now that we have our project ready, we can download IP databases from DP-IP. It has multiple free "IP Geolocation Databases" that update monthly. Let's start by downloading the database we want to use from

https://db-ip.com/db/lite.php

We will use IP to city db, after agreeing with the licensing terms, make sure to download the MMDB version of the database. It was about 60MB at the time of writing this tutorial.

Extract the downloaded MMDB file, rename it to GeoLite2-City.mmdb, and make sure to put it in the geoip folder in the project folder

GeoIP implementation testing

Let's check if it works. Firstly, we need to migrate the dataset and make sure the project works properly

python manage.py makemigrations
python manage.py migrate
python manage.py runserver 0.0.0.0:8555

This should run the project on port 8555. If it works successfully, we can

python manage.py shell

In [1]: from django.contrib.gis.geoip2 import GeoIP2                                     

In [2]: g = GeoIP2()                                                                     

In [3]: g.city("72.14.207.99")                                                           
Out[3]:                                                                                  
{'city': 'Mountain View',
 'continent_code': 'NA',
 'continent_name': 'North America',
 'country_code': 'US',
 'country_name': 'United States',
 'dma_code': None,
 'is_in_european_union': False,
 'latitude': 37.4225,
 'longitude': -122.085,
 'postal_code': None,
 'region': None,
 'time_zone': None}

In [4]:

Great! Now that we know it works, let's create a simple API where users send the IP and we answer with its location.

GeoIP API

To simplify this step, let's skip using serializers and pass the IP as a GET parameter, in the views file

from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework.exceptions import APIException
from common.utils import *

from django.contrib.gis.geoip2 import GeoIP2, GeoIP2Exception

class GeoIPView(APIView):
    permission_classes = ( )
    renderer_classes = [CustomRenderer, BrowsableAPIRenderer]

    def get(self, request, *args, **kwargs):
        ip_address = request.query_params.get('ip', None)
        if not ip_address:
            raise APIException("The 'ip' query parameter is required.")

        try:
            g = GeoIP2()
            # You can use .city(ip), .country(ip), etc. depending on the data you need
            geoip_data = g.city(ip_address)
            return Response(geoip_data)
        except GeoIP2Exception:
            # This exception is raised if the IP address is not in the database.
            raise APIException(f"Information for IP address '{ip_address}' not found.")

app_main/views.py

We are getting the IP from GET parameters, then passing it to GeoIP, and responding with its direct response.
Let's assign a URL for the view

from django.urls import path, include
from .views import *

urlpatterns = [
    path('geoip/', GeoIPView.as_view()),
]

app_main/urls.py

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('app_main.urls')),
]

saas/urls.py

Let's try it out!

great!
Let's do something more entertaining, let's edit the API to respond with the user's IP location if the IP parameter is not provided!

from django.contrib.gis.geoip2 import GeoIP2, GeoIP2Exception

class GeoIPView(APIView):
    permission_classes = ( )
    renderer_classes = [CustomRenderer, BrowsableAPIRenderer]

    def _get_client_ip(self, request):
        """Helper method to get the client's real IP address from the request."""
        # Check for the X-Forwarded-For header, which is used by proxies
        x_forwarded_for = request.META.get('HTTP_X_FORWARDED_FOR')
        if x_forwarded_for:
            # The header can contain a comma-separated list of IPs; the first is the client
            ip = x_forwarded_for.split(',')[0]
        else:
            # If not behind a proxy, use the standard REMOTE_ADDR
            ip = request.META.get('REMOTE_ADDR')
        return ip

    def get(self, request, *args, **kwargs):
        ip_address = request.query_params.get('ip', None)
        if not ip_address:
            ip_address = self._get_client_ip(request)


        try:
            g = GeoIP2()
            # You can use .city(ip), .country(ip), etc. depending on the data you need
            geoip_data = g.city(ip_address)
            return Response(geoip_data)
        except Exception as e:
            # This exception is raised if the IP address is not in the database.
            raise APIException(f"Information for IP address '{ip_address}' not found.")

app_main/views.py

We start by looking for ip parameter in the GET request; if it exists, we look for it; if not, we will try to get the request IP.
_get_client_ip will get the request IP, locally it will get the local IP, if online, it will get the user request IP.

Let's try it online

GET /api/geoip/

HTTP 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "status": "success",
    "code": 200,
    "data": {
        "city": "Remscheid",
        "continent_code": "EU",
        "continent_name": "Europe",
        "country_code": "DE",
        "country_name": "Germany",
        "dma_code": null,
        "is_in_european_union": true,
        "latitude": 51.1798,
        "longitude": 7.1925,
        "postal_code": null,
        "region": null,
        "time_zone": null
    },
    "message": null
}

GET /api/geoip/

HTTP 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "status": "success",
    "code": 200,
    "data": {
        "city": "Nicosia",
        "continent_code": "EU",
        "continent_name": "Europe",
        "country_code": "CY",
        "country_name": "Cyprus",
        "dma_code": null,
        "is_in_european_union": true,
        "latitude": 35.1728,
        "longitude": 33.354,
        "postal_code": null,
        "region": null,
        "time_zone": null
    },
    "message": null
}

Bonus, User IP 🤓

We can add the user IP to the response by adding one line to the view as

...
        try:
            g = GeoIP2()
            # You can use .city(ip), .country(ip), etc. depending on the data you need
            geoip_data = g.city(ip_address)
            geoip_data['ip'] = ip_address
            return Response(geoip_data)
        except Exception as e:
            # This exception is raised if the IP address is not in the database.
            raise APIException(f"Information for IP address '{ip_address}' not found.")

app_main/views.py

the response

GET /api/geoip/

HTTP 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "status": "success",
    "code": 200,
    "data": {
        "city": "Beirut",
        "continent_code": "AS",
        "continent_name": "Asia",
        "country_code": "LB",
        "country_name": "Lebanon",
        "dma_code": null,
        "is_in_european_union": false,
        "latitude": 33.8938,
        "longitude": 35.5018,
        "postal_code": null,
        "region": null,
        "time_zone": null,
        "ip": "185.227.133.12"
    },
    "message": null
}

That is it for this tutorial. We still need to add the SaaS users/ tokens/ stats management, which we will discuss in another tutorial, so

Stay tuned 😎

Setup iOS Account for Production

Saad Alkentar — Thu, 03 Jul 2025 10:13:20 +0000

Have you ever tried to publish an iOS app for yourself / a company/ a client? or maybe you are a DevOps trying to setup an iOS build pipeline for Bitrise, Bitbucket, AWS CloudFormation, or some other DevOps platform?
It simply asks for a certificate and a profile, but how to get them? well, I'm trying to help you obtain the required certificate and profile for publication
Let's dive in

Create a distribution certificate

I'll divide the operation into steps, let's start at the beginning

Create a certificate request from authority

Open Keychain Access: Command + Space -> type keychain
Create a certificate request from the main app menu
Use your email address and choose to save the request to disk

Open the used Apple Developer account https://developer.apple.com/account
Choose the correct account namespace (if it has many)
Choose Certificates
Create a new certificate
Select distribution certificate (Apple or iOS)
Then use the certificate request created before
Memorize the certificate expiration date, since we don’t have control over the certificate name, and download it

Create a profile

From the Apple Developer account, choose profiles and create a new one
Choose the distribution ad-hoc profile
Select the App ID
Select the certificate you created before (make sure using the expiration date)
Select all devices to be tested on
Name the certificate, something like UserName-AppName profile
Download the profile

Setup the project

Select the project, and choose the “Signing & Capabilities” tab
From the provisioning profile, choose “Import profile.”

This should be it. If you have any issues with the new profile, you can enable “Automatically manage signing” and disable it again to allow XCode

We will continue on more tips for iOS in coming tutorials so
Stay tuned 😎

Open Finder folder with IntelliJ IDEA, Sublime Text or VSCode

Saad Alkentar — Sun, 16 Feb 2025 06:17:56 +0000

What to expect from this article?

Finder is absolutely the best file browser for Mac! Don't waste your time looking for a better one (you would do it anyway, in case you are coming from a Linux background like me 🤓). But Finder has a few issues, actually

No option to show hidden files
No clear file/folder path
No option to customize the context menu

First two are actually simple to solve.

command + shift + . shows hidden files 😁
from View menu, choose show path bar 😉
this one is still kinda ugly ⚠️

This is a simple tip for Mac users in order to speed up opening code folders in Finder files explorer.

Where to start?

Start by opening Mac Automator app. command+space, type automator
Choose to create a Quick Action
Choose to show your quick action for folders in Finder, then choose an image (for some reason, it doesn't work for me since I use the path bar, but it might work for you)
Choose the action from Files ... olders, and double-click on Open Finder Items
Choose the app to lunch; if you cannot find it directly, choose Other...
Save the action; just press command + s and choose a name
Test it in the finder!
Either right-click on any folder and choose it from quick actions section

or from right-clicking any folder in the path bar

or from the quick preview section

A special tip: If you have already created too many actions (like me while testing 😅), you might prefer to be able to remove the unused ones.
You can find the created actions at /Users/username/Library/Services folder
Use command + shift + . to show hidden files and folders to find the Library

Stay tuned for more tips and tricks 😎

Flutter app, fading chat logic with bloc and hooks

Saad Alkentar — Mon, 10 Feb 2025 06:22:07 +0000

What can you expect from this article?

We finished the fading transition implementation in the previous article and will use it to finish our home chat page.
It is a specific scenario we are trying to build, so it is a good practice for bloc with hooks usage. Yet, it might be too specific, so feel free to skip this article.
PS. we are working on our already built code base.

The scenario we are trying to build is

The user clicks on the text field
The app closes the keyboard (for the first time)
The app sends a conversation request to the AI
The app fades in the server response
The user clicks on the text field to start writing the response
The app fades out the server response
The user clicks the send button from the keyboard
The app sends the message to the AI
The app fades out the user text and fades in the server response

The app should read the server response, and the user can use STT (speech to text) instead of writing. Please refer to Flutter App, Speech to Text and Text to Speech for detailed implementation of TTS and STT.

API calls and models (optional)

We will try to concentrate on the home screen UI since we have already detailed how to implement any API in our clean architecture project, but it doesn't hurt to repeat. So feel free to skip this part of the article if you are familiar with the process.

Start at the domain layer

We always start by creating the models in the domain layer

class MessageModel {
  MessageModel({
      this.created, 
      this.active, 
      this.text, 
      this.isUser, 
      this.conversation, 
      this.id,});

  MessageModel.fromJson(dynamic json) {
    created = json['created'];
    active = json['active'];
    text = json['text'];
    isUser = json['is_user'];
    conversation = json['conversation'];
    id = json['id'];
  }

  String? created;
  bool? active;
  String? text;
  bool? isUser;
  int? conversation;
  int? id;

  Map<String, dynamic> toJson() {
    final map = <String, dynamic>{};
    map['created'] = created;
    map['active'] = active;
    map['text'] = text;
    map['is_user'] = isUser;
    map['conversation'] = conversation;
    map['id'] = id;
    return map;
  }
}

lib/domain/models/entities/message_model.dart

Next is to update the repository schema in the domain layer

import '../models/entities/message_model.dart';

...
abstract class RemoteRepository {

  ...

  Future<DataState<GenericResponse<MessageModel>>> conversationStart();

  Future<DataState<GenericResponse<MessageModel>>> conversationSend({
    required String? text,
    required int? conversation,
  });
}

lib/domain/repositories/remote_repository.dart

Data layer

The first step in the data layer is to add the requests to the data source

...
  @GET('/conversation/')
  Future<HttpResponse<GenericResponse<MessageModel>>> conversationStart({
    @Header("Authorization") String? token,
    @Header("Accept-Language") String? lang,
  });

  @POST('/conversation/')
  Future<HttpResponse<GenericResponse<MessageModel>>> conversationSend({
    @Body() MessageRequest? request,
    @Header("Authorization") String? token,
    @Header("Accept-Language") String? lang,
  });
...

lib/data/sources/remote_datasource.dart

PS. Don't forget to issue dart run build_runner build to generate the data source code.

Next is to implement the repository schema

...
  @override
  Future<DataState<GenericResponse<MessageModel>>> conversationSend({
    String? text,
    int? conversation
  }) => getStateOf(
    request: () => remoteDatasource.conversationSend(
      request: MessageRequest(
        text: text,
        conversation: conversation
      ),
      lang: "en",
      token: "Bearer ${preferencesRepository.getToken()}",
    ),
  );

  @override
  Future<DataState<GenericResponse<MessageModel>>> conversationStart() => getStateOf(
    request: () => remoteDatasource.conversationStart(
      lang: "en",
      token: "Bearer ${preferencesRepository.getToken()}",
    ),
  );
...

lib/data/repositories/remote_repository_impl.dart

nice and easy, let's begin with the serious work

Chat screen events and states

Back to our home screen, let's start working on the bloc logic, as always, when working with bloc, we start with the events, then the states and finally the bloc logic itself

The events

We already have two events, one for TTS and another for STT, we need two extra events, one for starting a conversation, and another one for sending a text.

part of 'home_bloc.dart';

@immutable
sealed class HomeEvent {
  final String? text;
  const HomeEvent({this.text});
}

class HomeSTTEvent extends HomeEvent {}

class HomeTTSEvent extends HomeEvent {
  const HomeTTSEvent({super.text});
}

class HomeStartEvent extends HomeEvent {}
class HomeSendEvent extends HomeEvent {
  const HomeSendEvent({super.text});
}

lib/presentation/screens/home/home_event.dart

The States

With the events ready, we move to the states, we already have states for listening, reading, and errors. but we also need states for loading and receiving text.

part of 'home_bloc.dart';

@immutable
sealed class HomeState {
  final String? text;
  final String? error;
  const HomeState({
    this.text,
    this.error,
  });
}

final class HomeInitial extends HomeState {}
final class HomeListeningState extends HomeState {}
final class HomeReadingState extends HomeState {}
final class HomeErrorState extends HomeState {
  const HomeErrorState({super.error});
}
final class HomeSTTState extends HomeState {
  const HomeSTTState({super.text});
}

final class HomeLoadingState extends HomeState {}
final class HomeReceiveState extends HomeState {
  const HomeReceiveState({super.text});
}

lib/presentation/screens/home/home_state.dart

With our states and events ready, it is time to connect them in the bloc file

Bloc logic

In order to make the conversation requests, we are going to need access to the remote_repository, so let's add it to the bloc dependencies

...
  final RemoteRepository repository;

  HomeBloc(this.stt, this.tts, this.repository) : super(HomeInitial()) {
...

lib/presentation/screens/home/home_bloc.dart

We need to pass the new dependency from the main app file, just update the current bloc provider to provide it

...
-          BlocProvider(create: (context)=>HomeBloc(locator(), locator())),
+          BlocProvider(create: (context)=>HomeBloc(locator(), locator(), locator())),
...

lib/main.dart

Next step is to handle our newly added events, let's start with HomeStartEvent, when we receive it, we should make a start conversation request

import '../../../utils/data_state.dart';
import '../../../utils/dio_exception_extension.dart';
...
  HomeBloc(this.stt, this.tts, this.repository) : super(HomeInitial()) {
  int? conversationId = 0;
...
  HomeBloc(this.stt, this.tts, this.repository) : super(HomeInitial()) {
    ...
    on<HomeStartEvent>(handleStartEvent);
  }
...
  FutureOr<void> handleStartEvent(
      HomeStartEvent event,
      Emitter<HomeState> emit,
  ) async {
    emit(HomeLoadingState());

    final response = await repository.conversationStart();

    if (response is DataSuccess) {
      conversationId = response.data?.data?.conversation;

      emit(HomeReceiveState(
        text: response.data?.data?.text,
      ));
    } else {
      emit(HomeErrorState(error: response.error?.getErrorMessage(),));
    }
  }

lib/presentation/screens/home/home_bloc.dart

when receiving the event, we are making the start conversation request, the conversation id is saved in the bloc instance, then we emit the response text through HomeReceiveState

now for handling the send event

...
  HomeBloc(this.stt, this.tts, this.repository) : super(HomeInitial()) {
...
    on<HomeSendEvent>(handleSendEvent);
  }
...
  FutureOr<void> handleSendEvent(
      HomeSendEvent event,
      Emitter<HomeState> emit,
  ) async {
    emit(HomeLoadingState());

    recognizedText = "";

    final response = await repository.conversationSend(
      text: event.text ?? "",
      conversation: conversationId ?? 0,
    );

    if (response is DataSuccess) {
      emit(HomeReceiveState(
        text: response.data?.data?.text,
      ));

    } else if (response is DataFailed) {
      emit(HomeErrorState(
        error: response.error?.getErrorMessage(),
      ));
    }

  }

lib/presentation/screens/home/home_bloc.dart

We are cleaning the recognized text (in case of using STT by the user) then making the conversation send request, and passing the response text through HomeReceiveState to the UI
it is time to move the home screen itself

Home screen

We are working on the last version of Home screen after the TTS and STT article and the hooks article. We already have text field, microphone button, and a bloc listener, the full code look like

import 'package:alive_diary_app/config/dependencies.dart';
import 'package:alive_diary_app/config/router/app_router.dart';
import 'package:alive_diary_app/domain/repositories/preferences_repository.dart';
import 'package:alive_diary_app/presentation/widgets/layout_widget.dart';
import 'package:auto_route/auto_route.dart';
import 'package:easy_localization/easy_localization.dart';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:flutter_hooks/flutter_hooks.dart';
import 'package:google_fonts/google_fonts.dart';
import 'home_bloc.dart';


@RoutePage()
class HomeScreen extends HookWidget {
  const HomeScreen({super.key, this.title});

  final String? title;

  @override
  Widget build(BuildContext context) {
    final bloc = BlocProvider.of<HomeBloc>(context);

    final isLoading = useState(false);
    final speechText = useState("");
    final canWrite = useState<bool?>(null);
    final textController = useTextEditingController();

    AnimationController animationController = useAnimationController(
        duration: const Duration(seconds: 4),
        initialValue: 0,
    );

    void showText(String? text) async {
      await Future.delayed(const Duration(milliseconds: 100));
      SystemChannels.textInput.invokeMethod('TextInput.hide');
      animationController.animateBack(0, duration: const Duration(seconds: 1));
      await Future.delayed(const Duration(seconds: 2));
      textController.text = text ?? "";
      animationController.forward();
    }

    void clearText() async {
      animationController.animateBack(0, duration: const Duration(seconds: 1));
      await Future.delayed(const Duration(seconds: 2));
      textController.text = "";
      animationController.forward();
    }

    return BlocListener<HomeBloc, HomeState>(
      listener: (context, state) {
        isLoading.value = state is HomeListeningState;

        if (state is HomeSTTState) {
          speechText.value = state.text ?? "";
        }

      },
      child: LayoutWidget(
        title: 'home'.tr(),
        actions: [
          IconButton(
            icon: const Icon(Icons.logout, color: Colors.black,),
            onPressed: (){
              locator<PreferencesRepository>().logout();
              appRouter.replaceAll([LoginRoute()]);
            },
          )
        ],
        floatingActionButton: FloatingActionButton(
          tooltip: 'Listen',
          child: Icon(
            Icons.keyboard_voice_outlined,
            color: isLoading.value ? Colors.green : Colors.blue,
          ),
          onPressed: () => bloc.add(HomeSTTEvent()),
        ),
        child:Container(
          height: double.infinity,
          padding: const EdgeInsets.symmetric(horizontal: 15),
          decoration: const BoxDecoration(
            image: DecorationImage(
              image: AssetImage("assets/images/paper_bg.jpg"),
              fit: BoxFit.cover,
            ),
          ),
          child: FadeTransition(
            opacity: animationController,
            child: TextField(
              decoration: const InputDecoration(border: InputBorder.none),
              // focusNode: textNode,
              cursorHeight: 35,
              style: GoogleFonts.caveat(
                fontSize: 30,
                color: Colors.black,
              ),
              keyboardType: TextInputType.multiline,
              textInputAction: TextInputAction.send,
              controller: textController,
              maxLines: null,
              onTap: () async {

                if (canWrite.value == null) {
                  showText("How was your day?");
                  canWrite.value = true;
                } else if (canWrite.value == true) {
                  clearText();
                }

              },
              onSubmitted: (text) async {
                showText("Tell me more");
              },
            ),
          ),
        ),
      ),

    );
  }
}

lib/presentation/screens/home/home_screen.dart

when clicking on the text field for the first time, a conversation start request should be made, and when receiving the response, it should be shown using the HomeReceiveState

...
    return BlocListener<HomeBloc, HomeState>(
      listener: (context, state) {

        if (state is HomeReceiveState) {
          showText(state.text);
          canWrite.value = true;
        }

...

          child: FadeTransition(
            opacity: animationController,
            child: TextField(
...
              onTap: () async {

                if (canWrite.value == null) {
                  bloc.add(HomeStartEvent()); // new
                } else if (canWrite.value == true) {
                  clearText();
                }

              },
              onSubmitted: (text) async {
                bloc.add(HomeSendEvent(text: text)); // new
              },
            ),
          ),

lib/presentation/screens/home/home_screen.dart

We should be able to test it now, clicking on the text box should show the server response, clicking on it again should fade away the text and allow user to type the message, hitting keyboard submit should send the message back to the server and show its response

first response	typing message	receiving a response

Now for the reader, it is kinda easy from now, when receiving the server response, all we need to do is to add a TTS event

...
    void showText(String? text) async {
      await Future.delayed(const Duration(milliseconds: 100));
      SystemChannels.textInput.invokeMethod('TextInput.hide');
      animationController.animateBack(0, duration: const Duration(seconds: 1));
      await Future.delayed(const Duration(seconds: 2));
      textController.text = text ?? "";
      animationController.forward();
      bloc.add(HomeTTSEvent(text: text));
    }
...

lib/presentation/screens/home/home_screen.dart

That is it for this article. I know it is too much to handle, and too many details to follow, just treat it as an optional if you didn't follow previous ones.

This app is finished now, we have fully implemented the main feature with this article. I'll start working on apps I want to publish on the store next, so, as always

Stay tuned 😎

Flutter App, Simple animation with Hooks 🪝

Saad Alkentar — Tue, 04 Feb 2025 10:49:48 +0000

What to expect from this tutorial?

This is a simple tutorial to add fading animation for a text field using flutter_hooks

usually, to add animation to any Flutter UI element, it has to be a state-full widget, the animation controller should be created in the state class, initState should be overwritten to populate the animation instance, and we should also override dispose to clean the memory from our animation controller when navigating to another screen!
It has always been a hurdle 😵, so I avoided using it as much as possible, but flutter_hooks has finally simplified the operation a bit, let's start by cleaning the home_screen code (you can start with your own screen of course).

The idea

Well, our diary is kinda similar to "Tom Riddle" diary (in "Harry Potter and the Chamber of Secrets"). And I liked how Harry's writing disappears, and Tom's answer appears in the diary. So, let's add fading animation to the text when sent to the AI and an appearing animation when received back from the AI. We will start by creating a simple fade-in and fade-out animation, then work on building app-specific behavior.

The behavior we wanna build is like this:

The user clicks on the text field
The app closes the keyboard (for the first time)
The app sends a conversation request to the AI
app fade in the server response
The user clicks on the text field to start writing the response
The app fades out the server response
The user clicks the send button from the keyboard
The app sends the message to the AI
the app fades out the user text and fades in the server response

Clean `home_screen` code (optional)

If you are following this tutorial series, you will have some code in home_screen, so let's clean it a bit by using LayoutWidget from the previous article, removing screen contents, changing the action button to a logout button, and showing only the listen floating button

import 'package:alive_diary_app/config/dependencies.dart';
import 'package:alive_diary_app/config/router/app_router.dart';
import 'package:alive_diary_app/domain/repositories/preferences_repository.dart';
import 'package:alive_diary_app/presentation/widgets/layout_widget.dart';
import 'package:auto_route/auto_route.dart';
import 'package:easy_localization/easy_localization.dart';
import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:flutter_hooks/flutter_hooks.dart';
import 'home_bloc.dart';


@RoutePage()
class HomeScreen extends HookWidget {
  const HomeScreen({super.key, this.title});

  final String? title;

  @override
  Widget build(BuildContext context) {
    final bloc = BlocProvider.of<HomeBloc>(context);

    final isLoading = useState(false);
    final speechText = useState("");

    return BlocListener<HomeBloc, HomeState>(
      listener: (context, state) {
        isLoading.value = state is HomeListeningState;

        if (state is HomeSTTState) {
          speechText.value = state.text ?? "";
        }

      },
      child: LayoutWidget(
        title: 'home'.tr(),
        actions: [
          IconButton(
            icon: const Icon(Icons.logout, color: Colors.black,),
            onPressed: (){
              locator<PreferencesRepository>().logout();
              appRouter.replaceAll([LoginRoute()]);
            },
          )
        ],
        floatingActionButton: FloatingActionButton(
          tooltip: 'Listen',
          child: Icon(
            Icons.keyboard_voice_outlined,
            color: isLoading.value ? Colors.green : Colors.blue,
          ),
          onPressed: () => bloc.add(HomeSTTEvent()),
        ),
        child: Container(
          alignment: Alignment.center,
          child: const Text("Empty"),
        ),
      ),

    );
  }
}

lib/presentation/screens/home/home_screen.dart

The fun part 😁, the Animation!

To create animations with flutter_hooks, we start by creating the animation controller hook

    AnimationController animationController = useAnimationController(
        duration: const Duration(seconds: 4),
        initialValue: 1,
    );

then we use it in the Transition component

              FadeTransition(
                opacity: animationController,
                child: Center(
                    child: Text("Hello World")
                ),
              ),

that is it! no initState, no dispose, no headache

For our app, we need to show and hide text, so let's add two buttons to the home screen, one for showing and another one for hiding, it would look somewhat like

import 'package:alive_diary_app/config/dependencies.dart';
import 'package:alive_diary_app/config/router/app_router.dart';
import 'package:alive_diary_app/domain/repositories/preferences_repository.dart';
import 'package:alive_diary_app/presentation/widgets/layout_widget.dart';
import 'package:auto_route/auto_route.dart';
import 'package:easy_localization/easy_localization.dart';
import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:flutter_hooks/flutter_hooks.dart';
import 'package:google_fonts/google_fonts.dart';
import 'home_bloc.dart';


@RoutePage()
class HomeScreen extends HookWidget {
  const HomeScreen({super.key, this.title});

  final String? title;

  @override
  Widget build(BuildContext context) {
    final bloc = BlocProvider.of<HomeBloc>(context);

    final isLoading = useState(false);
    final speechText = useState("");

    AnimationController animationController = useAnimationController(
        duration: const Duration(seconds: 4),
        initialValue: 1,
    );

    return BlocListener<HomeBloc, HomeState>(
      listener: (context, state) {
        isLoading.value = state is HomeListeningState;

        if (state is HomeSTTState) {
          speechText.value = state.text ?? "";
        }

      },
      child: LayoutWidget(
        title: 'home'.tr(),
        actions: [
          IconButton(
            icon: const Icon(Icons.logout, color: Colors.black,),
            onPressed: (){
              locator<PreferencesRepository>().logout();
              appRouter.replaceAll([LoginRoute()]);
            },
          )
        ],
        floatingActionButton: FloatingActionButton(
          tooltip: 'Listen',
          child: Icon(
            Icons.keyboard_voice_outlined,
            color: isLoading.value ? Colors.green : Colors.blue,
          ),
          onPressed: () => bloc.add(HomeSTTEvent()),
        ),
        child:Container(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              FadeTransition(
                opacity: animationController,
                child: Center(
                    child: Text("Hello World",
                      style: GoogleFonts.caveat(
                        fontSize: 30,
                        color: Colors.black,
                      ),
                    )
                ),
              ),
              ElevatedButton(
                child: Text("show".tr()),
                onPressed: () async {
                  animationController.forward();
                },
              ),

              ElevatedButton(
                child: Text("hide".tr()),
                onPressed: (){
                  animationController.animateBack(0,
                      duration: const Duration(seconds: 1),
                  );
                },
              )

            ],
          ),
        ),
      ),

    );
  }
}

lib/presentation/screens/home/home_screen.dart

We are using google_fonts to make the font more human-like 🤓, with google fonts, you are free to choose from a wide range of great fonts, but feel free to ignore it since it doesn't have to do with the animation itself 😅

The home UI should look somewhat like

hidden	shown

The text should be visible in the initial state, clicking hide should fade it away, and clicking show should fade it in. We can change the initial text state to hidden by changing initialValue to 0.

simple and great! no need to run from UI animation anymore 😁, now for the app behavior, let's start working on it

Diary app text field behavior

Let's start by creating a large text field, with a nice paper-like background, and address the onTab and onSubmit actions

...
  Widget build(BuildContext context) {
    final textController = useTextEditingController();

...
      child: LayoutWidget(
        title: 'home'.tr(),
...
        child:Container(
          height: double.infinity,
          padding: const EdgeInsets.symmetric(horizontal: 15),
          decoration: const BoxDecoration(
            image: DecorationImage(
              image: AssetImage("assets/images/paper_bg.jpg"),
              fit: BoxFit.cover,
            ),
          ),
          child: TextField(
            decoration: const InputDecoration(border: InputBorder.none),
            cursorHeight: 35,
            style: GoogleFonts.caveat(
              fontSize: 30,
              color: Colors.black
            ),
            keyboardType: TextInputType.multiline,
            textInputAction: TextInputAction.send,
            controller: textController,
            maxLines: null,
            onTap: () async {

            },
            onSubmitted: (text) async {

            },
          ),
        ),
      ),
...

lib/presentation/screens/home/home_screen.dart

We have added a text field, with a background, multiple lines support, and functions for clicking and submitting (the software keyboard submit button), let's start with how to dismiss the software keyboard?

Dismiss the software keyboard in flutter

How to dismiss the software keyboard? it is kinda tricky, in Android, we start by adding PROCESS_TEXT query in the manifest at the same level as the application section

...
    <queries>
        <intent>
            <action android:name="android.intent.action.PROCESS_TEXT"/>
            <data android:mimeType="text/plain"/>
        </intent>
    </queries>

    <application
        android:label="alive_diary_app"
        android:name="${applicationName}"
        android:icon="@mipmap/launcher_icon">
...

android/app/src/main/AndroidManifest.xml

Now we can test it in the app with the TextInput.hide method as

import 'package:flutter/services.dart';

...
            child: TextField(
              decoration: const InputDecoration(border: InputBorder.none),
              cursorHeight: 35,
              style: GoogleFonts.caveat(
                fontSize: 30,
                color: Colors.black,
              ),
              keyboardType: TextInputType.multiline,
              textInputAction: TextInputAction.send,
              controller: textController,
              maxLines: null,
              onTap: () async {
                await Future.delayed(const Duration(seconds: 2));
                SystemChannels.textInput.invokeMethod('TextInput.hide');

              },
...

lib/presentation/screens/home/home_screen.dart

The keyboard will appear when clicking on the text field, then after two seconds, it will just disappear.

Text field animation

We want to apply the animation on the text field, so it must be wrapped with FadeTransition, and we need two functions

showText function, which hides the keyboard, sets the new value and fades it in
clearText function, which fades out field contents, and sets it to an empty text.

...
  Widget build(BuildContext context) {
    final isLoading = useState(false);
    final speechText = useState("");
    final canWrite = useState<bool?>(null);
    final textController = useTextEditingController();

...
    void showText(String? text) async {
      await Future.delayed(const Duration(milliseconds: 100));
      SystemChannels.textInput.invokeMethod('TextInput.hide');
      animationController.animateBack(0, duration: const Duration(seconds: 1));
      await Future.delayed(const Duration(seconds: 2));
      textController.text = text ?? "";
      animationController.forward();
    }

    void clearText() async {
      animationController.animateBack(0, duration: const Duration(seconds: 1));
      await Future.delayed(const Duration(seconds: 2));
      textController.text = "";
      animationController.forward();
    }
...
            child: TextField(
              decoration: const InputDecoration(border: InputBorder.none),
              cursorHeight: 35,
              style: GoogleFonts.caveat(
                fontSize: 30,
                color: Colors.black,
              ),
              keyboardType: TextInputType.multiline,
              textInputAction: TextInputAction.send,
              controller: textController,
              maxLines: null,
              onTap: () async {

                if (canWrite.value == null) {
                  showText("How was your day?");
                  canWrite.value = true;
                } else if (canWrite.value == true) {
                  clearText();
                }

              },
              onSubmitted: (text) async {
                showText("Tell me more");
              },
            ),
...

lib/presentation/screens/home/home_screen.dart

That is it! well, almost, we are mimicking the server response with a plain text, but whatever, let's concentrate on the behavior for now

we have created the two functions showText and clearText, we have created a new helper state canWrite in order to distinguish the first click,
if this is the first click, we show the server response (static text for now), but if this is not the first time, then we simply clear the text.
when clicking the keyboard submit button, we (should send the text to server and show its response) show the message "Tell me more"

This is the required behavior as described, let's continue building the app together and as always

Stay tuned 😎