Forem: David Njoroge

UNDERSTANDING CLEAN ARCHITECTURE IN SOFTWARE DEVELOPMENT

David Njoroge — Thu, 26 Mar 2026 08:04:20 +0000

A developer walks into a bar and orders a beer. The bartender says, "We only serve drinks via an Interface Adapter." The developer replies, "Fine, as long as the beer doesn't know it’s in a glass."

Stop letting business logic enter a toxic, codependent relationship with a UI or a Database. These are "details" that should be treated as plugins, not as the foundation of the system. If the folder structure communicates "Android Framework" instead of "Healthcare System," the architecture is failing. This exhaustive guide is a complete roadmap for escaping the "Big Ball of Mud." It covers everything from the historical convergence of Hexagonal and Onion patterns to a concrete Kotlin implementation featuring self-validating Value Objects that kill bugs before they reach the core. It is a long, high-density read because professional engineering is not a 280-character thread. For those ready to build software that survives the next framework migration, the full masterclass is available here.

Prepare to dismantle the habits of "framework-first" development and rebuild your entire engineering philosophy from the domain outward.

Origins and Evolution of Clean Architecture

The concept of Clean Architecture was formalized by Robert C. Martin ("Uncle Bob") in 2012. It was not a discovery of new principles, but a synthesis of several existing architectural patterns designed to address the increasing entanglement of business logic with framework-specific code.

1. The Precursor Patterns

Clean Architecture integrates ideas from four primary architectural movements:

Hexagonal Architecture (Ports and Adapters): Developed by Alistair Cockburn around 2005. It introduced the idea that an application should be equally driven by users, programs, automated tests, or batch scripts, and be developed and tested in isolation from its eventual run-time devices and databases.

Above image is extracted from Hexagonal Architecture and Clean Architecture (with examples) by Dyarlen Iber

Onion Architecture: Proposed by Jeffrey Palermo in 2008. This pattern placed the Domain Model at the center and established the rule that all coupling is toward the center. It emphasized that the application core should not depend on the database or any infrastructure concerns.

Above image is extracted from Onion Architecture by Ritesh Kapoor

Screaming Architecture: A concept emphasizing that the folder structure and organization of a project should communicate the intent of the system (e.g., "Healthcare System") rather than the frameworks used (e.g., "Ruby on Rails" or "Spring Boot").
DCI (Data, Context, and Interaction) and BCE (Boundary-Control-Entity): These patterns contributed to the definition of how objects interact within use cases and how boundaries between the system and the external world are managed.

2. The Synthesis (2012)

Robert C. Martin unified these concepts into a single actionable framework called "Clean Architecture." The goal was to provide a standardized approach to building systems that are:

Independent of Frameworks: The architecture does not rely on the existence of some library of feature-laden software. This allows you to use frameworks as tools, rather than cramming your system into their limited constraints.
Testable: The business rules can be tested without the UI, Database, Web Server, or any other external element.
Independent of UI: The UI can change easily, without changing the rest of the system. A Web UI could be replaced with a console UI, for example, without changing the business rules.
Independent of Database: You can swap out SQL Server or Oracle for MongoDB, BigTable, CouchDB, or something else. Your business rules are not bound to the database.

3. The Shift Toward Domain-Driven Design (DDD)

The evolution of Clean Architecture is closely tied to the rise of Domain-Driven Design (DDD). It adopted the DDD emphasis on the "Domain" as the most important part of the software. This led to the structural requirement that the innermost circle—the Entities—contains the most general and high-level rules, while the outer circles contain the mechanisms (UI, DB, etc.). This ensures that the most stable part of the application (the business logic) does not depend on the most volatile parts (the technology stack).

The Core Reasoning

The fundamental objective of Clean Architecture is the isolation of business logic from technical implementation details. This separation ensures that the software remains adaptable, maintainable, and testable throughout its lifecycle.

1. Separation of Concerns and Framework Independence

Software systems often become rigid when business rules are tightly coupled to specific frameworks (e.g., Spring, Express, .NET) or libraries. Clean Architecture treats these as "details." By decoupling the core logic, the organization can upgrade or replace frameworks without rewriting the underlying business rules. This protects the enterprise's intellectual property from the volatility of the technology market.

2. Protection of the Domain (Domain Integrity)

The most critical reasoning behind this architecture is the preservation of the "Domain." The domain contains the rules that define how the business functions.

To ensure the domain remains valid and consistent, Clean Architecture utilizes Value Objects. Unlike Entities, which have a unique identity, Value Objects are defined by their attributes. Their core reasoning includes:

Self-Validation: A Value Object is responsible for its own validity. It cannot be instantiated in an invalid state. For example, an Email value object will validate the format upon creation.
Immediate Error Handling: If the input data fails business constraints, the Value Object throws a domain-specific error (e.g., InvalidEmailException). This prevents "garbage data" from propagating into the deeper layers of the application.
Immutability: Once created, a Value Object cannot be changed. Any modification results in a new instance. This eliminates side effects and makes the system's behavior predictable.

3. Testability Without Side Effects

When business logic is isolated, unit testing does not require a database connection, a web server, or any external infrastructure. Tests run faster and are more reliable because they focus strictly on logic. By using Value Objects that validate themselves, the testing suite can verify that the system correctly rejects invalid data at the boundary of the domain layer, ensuring the "Golden Rule" of the domain is never violated.

4. Dependency Inversion

The reasoning for the Dependency Rule (dependencies point only inward) is to ensure that the high-level policy (Business Rules) does not depend on low-level detail (Data Access, UI).

Stable Abstractions: The inner layers define interfaces (Ports).
Volatile Implementations: The outer layers implement these interfaces (Adapters). This inversion allows developers to defer decisions about databases or external APIs until they are absolutely necessary, or change them later with minimal impact on the core code.

5. Long-term Velocity

While Clean Architecture requires more boilerplate and initial setup (due to the creation of DTOs, Mappers, and Value Objects), the reasoning is to prevent "Software Rot." By maintaining strict boundaries, the cost of adding new features or changing existing ones remains relatively constant over time, rather than increasing exponentially as the codebase grows.

Architectural Layers

The architecture is organized into four concentric layers, each representing a different level of abstraction and isolation.

1. Entities (The Domain Layer)

This is the innermost circle, representing the core business rules of the enterprise. It contains the most general and high-level rules that are least likely to change when external factors shift.

Entities: Objects that have a unique identity and a lifecycle. They encapsulate the fundamental business logic of the system.
Value Objects: These represent descriptive aspects of the domain with no conceptual identity. They are defined by their attributes and are immutable.
- Validation and Error Handling: Value Objects are responsible for enforcing domain invariants. They validate their own state during instantiation.
- Logic Enforcement: If a Password Value Object requires a minimum of eight characters, the constructor must validate this constraint. If the input is invalid, it must immediately throw a domain-specific exception (e.g., WeakPasswordException). This ensures that no invalid data can ever penetrate the domain layer.
- Independence: This layer must have zero dependencies on any external library, framework, or database driver.

Comparison: Entities vs. Value Objects

Feature	Entities	Value Objects
Identity	Defined by a unique identifier (ID) that persists even if other attributes change.	No unique identity; defined entirely by the combination of their attributes.
Equality	Two entities are equal if their IDs match, regardless of differences in other properties.	Two value objects are equal if all their attributes are identical (Structural Equality).
Mutability	Mutable. Attributes can change over the entity's lifecycle while the identity remains the same.	Immutable. Once created, they cannot be changed. Any "change" results in a new instance.
Lifecycle	Has a continuous history and lifecycle (e.g., a User created, updated, and deactivated).	Transient and replaceable. They describe a characteristic rather than an individual.
Validation	Validation often concerns state transitions or relationships between multiple properties.	Self-validating at the point of creation. They cannot exist in an invalid state.
Implementation	Usually represented as a `class` or `data class` with a specific ID field.	In Kotlin, often implemented as `value class` or `data class` without an ID.
Example	`User(id="123", name="John")` — John remains User 123 even if he changes his name.	`Email("john@example.com")` — If the email changes, it is a completely different value.
Persistence	Mapped to their own database tables with a primary key.	Often persisted as columns within the owner's table (Embedded) or as a flat string.

Key Distinction in Clean Architecture

Entities represent the "Who" or "What" in the system (e.g., a specific Order or a specific Account). They orchestrate complex business logic that spans multiple state changes.
Value Objects represent the "How much," "Where," or "What kind" (e.g., a Price, an Address, or a Color). They serve as the "gatekeepers" of the domain by ensuring that only valid data can be used to construct or update Entities. By throwing errors during instantiation (e.g., InvalidEmailException), they prevent the Domain layer from ever handling corrupted or illogical information.

2. Use Cases (The Application Layer)

This layer contains application-specific business rules. it orchestrates the flow of data to and from the entities and directs those entities to use their enterprise-wide business rules to achieve the goals of the use case.

Functionality: It implements all the "features" of the system (e.g., ProcessOrder, RegisterUser, GenerateReport).
Decoupling: Use cases do not know how data is stored or how it is presented to the user. They interact with the outer layers through interfaces (Input and Output Ports).
Boundary Crossing: This layer defines the contracts (interfaces) that the infrastructure layer must implement.

3. Interface Adapters

This layer is a set of adapters that convert data from the format most convenient for the use cases and entities to the format most convenient for some external agency like the Database or the Web.

Controllers: Convert incoming requests (e.g., HTTP requests) into simple data structures that the use cases can understand.
Presenters: Convert the results from a use case back into a format suitable for the UI or API response.
Gateways: Interfaces used by the application layer to communicate with external systems (like a database or an external mail service).
Mappers: This layer contains the logic to map Domain Entities/Value Objects into Data Transfer Objects (DTOs) or Persistence Models, and vice-versa.

4. Frameworks and Drivers (The Infrastructure Layer)

The outermost layer is composed of frameworks and tools such as the Database, the Web Framework, the GUI, and the configuration.

External Mechanisms: This is where the actual implementation of the database (e.g., SQL scripts, MongoDB clients) and the web server (e.g., Express, Spring Boot controllers) resides.
Volatility: This layer is the most volatile. Because it is kept separate from the inner layers, replacing a database or switching from a REST API to a message queue involves changing code only in this layer.
Dependency: This layer depends on the inner layers by implementing the interfaces defined in the Use Case or Domain layers. It is the "plug-in" area of the architecture.

Data Flow and Dependency Inversion

In Clean Architecture, data flow and dependency direction are distinct concepts. While data flows in a circular or bidirectional path (from the user to the database and back), source code dependencies must always point inward toward the Domain.

This image is extracted from How data flows in Clean Architecture by Jelena Cupać

1. The Flow of Control vs. Dependency Direction

Flow of Control: Starts in the Presentation layer (User clicks a button), moves through the Application layer (Use Case), into the Domain (Entities), then out to the Infrastructure (Database), and finally back to the UI.
Dependency Direction: Every layer depends only on the layer immediately inside it. The Infrastructure layer depends on the Domain, but the Domain knows nothing about the Infrastructure.

2. Dependency Inversion Principle (DIP)

To allow the Application layer to communicate with the Database without depending on it, we use Dependency Inversion.

The Problem: A Use Case needs to save a User entity. If the Use Case calls SqlDatabase.save(), the Application layer now depends on a specific database framework.
The Solution: The Application layer defines an interface (an Output Port), such as UserRepository. The Infrastructure layer then implements this interface. At runtime, the implementation is "plugged in," but the source code dependency remains pointing inward to the interface.

3. Input and Output Ports

Ports are the entry and exit points of the application core (Domain + Application layers).

Input Ports (Driving Adapters): Interfaces that allow external agents (UI, CLI, Tests) to tell the application what to do.
- Example: RegisterUserUseCase interface. The ViewModel calls this port to trigger business logic.
Output Ports (Driven Adapters): Interfaces used by the application core to get data from or send data to the outside world.
- Example: UserRepository or EmailService interfaces. The Use Case calls these ports to persist data or send notifications.

4. Data Transfer Objects (DTOs) vs. Domain Models

Crossing architectural boundaries requires translating data between different formats to maintain isolation.

Feature	Data Transfer Object (DTO)	Domain Model (Entity/Value Object)
Location	Presentation or Infrastructure	Domain Layer
Purpose	Data transportation (API/DB)	Business Logic and Rules
Structure	Flat, simple data types (Strings, Ints)	Rich objects (Value Objects)
Validation	Minimal (Format/Null checks)	Strict (Business Invariants)
Stability	Volatile (Changes with API/DB schema)	Stable (Changes with Business Rules)

5. Crossing the Boundary: The Mapping Process

When data moves through the layers, it must be mapped to ensure the Domain remains "clean."

Request Entry: The Presentation layer receives a LoginRequestDto. It extracts the raw strings.
Domain Entry: The Application layer takes those strings and passes them into the Domain. At this point, Value Objects are instantiated.
- val email = Email(dto.email)
- val password = Password(dto.password)
- Validation: If the DTO contains an invalid email, the Email Value Object throws an error immediately. The Use Case never executes with invalid data.
Persistence: The Use Case passes the validated User Entity to the UserRepository (Output Port).
Data Exit: The Infrastructure layer receives the Entity and maps it to a UserDbModel (Persistence DTO) for the database.

This strict mapping prevents "Anemic Domain Models" (objects with only getters and setters) and ensures that the core business logic is never compromised by external data requirements.

File Structure (Layer-Wise)

This structure organizes the project strictly by architectural layers. It separates technical concerns across the entire application, which is suitable for smaller to mid-sized projects where a feature-based split is not yet required.

src/
├── domain/                         # Enterprise-wide business logic and rules
│   ├── entities/                   # Core objects with identity (e.g., User.ts, Order.ts)
│   ├── value-objects/              # Immutable objects with self-validation logic
│   │   ├── Email.ts                # Validates format; throws InvalidEmailError
│   │   ├── Password.ts             # Validates strength; throws WeakPasswordError
│   │   └── Money.ts                # Validates non-negative; throws InvalidAmountError
│   ├── repositories/               # Interfaces/Contracts for data persistence
│   ├── exceptions/                 # Domain-specific error classes
│   └── services/                   # Domain services for logic involving multiple entities
│
├── application/                    # Application-specific business rules (Use Cases)
│   ├── use-cases/                  # Orchestrators (e.g., CreateUser.ts, GetOrder.ts)
│   ├── ports/                      # Interfaces for external services (e.g., IMailer.ts)
│   └── dtos/                       # Data Transfer Objects for Use Case input/output
│
├── infrastructure/                 # External implementations and technical details
│   ├── persistence/                # Database-specific logic
│   │   ├── models/                 # Database schemas or ORM entities
│   │   ├── repositories/           # Concrete implementations of Domain repositories
│   │   └── mappers/                # Maps Persistence Models <-> Domain Entities
│   ├── external-services/          # Concrete implementations of Application ports
│   │   ├── mailer/                 # e.g., SendGrid or SMTP implementation
│   │   └── storage/                # e.g., AWS S3 or LocalStorage implementation
│   └── config/                     # Environment and framework-specific configurations
│
├── presentation/                   # Entry points and delivery mechanisms
│   ├── http/                       # REST/GraphQL API implementation
│   │   ├── controllers/            # Handles requests and invokes Use Cases
│   │   ├── middlewares/            # Auth, validation, and error handling
│   │   └── routes/                 # Endpoint definitions
│   ├── cli/                        # Terminal/Command-line interface logic
│   └── view-models/                # Formatting logic for the final response/UI
│
└── main/                           # Composition Root
    ├── di/                         # Dependency Injection wiring and containers
    ├── factories/                  # Logic for assembling complex object graphs
    └── index.ts                    # Application entry point

Layer-Wise Component Details

Domain Layer: Value Objects and Validation

In this layer-based approach, all Value Objects reside in domain/value-objects/.

Validation Logic: Every Value Object contains a private constructor and a static create method (or logic within the constructor) that performs validation.
Error Handling: If an input violates a business rule (e.g., a ZipCode that is not 5 digits), the Value Object throws a specific exception from domain/exceptions/. This ensures that an invalid object can never exist within the application or infrastructure layers.

Application Layer: Use Case Orchestration

The application/use-cases/ directory contains the logic that bridges the UI and the Domain.

Process: It receives a DTO from the presentation layer, uses the domain/value-objects/ to validate the data, interacts with domain/repositories/ (interfaces), and returns a result.
Isolation: This layer knows "what" needs to happen but has no knowledge of "how" the data is stored or "how" the response is rendered.

Infrastructure Layer: The Implementation Detail

The infrastructure/ directory contains the "low-level" code.

Mappers: Crucial in this structure to prevent database-specific logic from leaking. infrastructure/persistence/mappers/ convert raw database rows into the rich Domain Entities and Value Objects defined in the center.
Adapters: If the application needs to send an email, the concrete implementation (e.g., NodemailerAdapter) stays here, satisfying the interface defined in application/ports/.

Presentation Layer: Data Transformation

This layer is responsible for the "delivery" of the application.

Controllers: In presentation/http/controllers/, the code handles the web-specific details like HTTP status codes and headers. It maps the incoming request body into an Application DTO.
Error Mapping: This layer is also responsible for catching the domain-specific exceptions (thrown by Value Objects) and converting them into user-friendly error messages or appropriate HTTP status codes (e.g., 400 Bad Request).

Native Android (Kotlin) Clean Architecture File Structure

In standard Android development, Clean Architecture is typically organized into three primary layers: Domain (pure Kotlin), Data (Infrastructure), and Presentation (Android UI). These can be implemented as separate Gradle modules or as packages within a single app module.

Below is the package structure for a single-module Android application utilizing modern components like Jetpack Compose, ViewModels, Room, and Retrofit.

app/src/main/java/com/example/app/
├── domain/                             # Pure Kotlin/Java (No Android dependencies)
│   ├── model/                          # Entities and Value Objects
│   │   ├── User.kt                     # Entity with identity
│   │   └── valueobject/
│   │       ├── Email.kt                # Kotlin class/value class with validation
│   │       ├── Password.kt             # Validates rules and throws Domain Exceptions
│   │       └── Money.kt
│   ├── repository/                     # Interface definitions for data operations
│   │   └── UserRepository.kt
│   ├── usecase/                        # Single-purpose business rules
│   │   ├── CreateUserUseCase.kt
│   │   └── GetUserUseCase.kt
│   └── exception/                      # Custom Domain Exceptions
│       └── DomainExceptions.kt         # e.g., InvalidEmailException, WeakPasswordException
│
├── data/                               # Data management and Infrastructure
│   ├── repository/                     # Implementations of Domain repositories
│   │   └── UserRepositoryImpl.kt
│   ├── mapper/                         # Maps Data Entities <-> Domain Models
│   │   └── UserMapper.kt
│   ├── local/                          # Room Database, SQLite, DataStore
│   │   ├── database/ AppDatabase.kt
│   │   ├── dao/ UserDao.kt
│   │   └── entity/ UserEntity.kt       # Room Database Entity
│   └── remote/                         # Retrofit, Ktor, API Clients
│       ├── api/ UserApiService.kt
│       └── dto/ UserResponseDto.kt     # Network response objects
│
├── presentation/                       # Android UI and ViewModels
│   ├── common/                         # Reusable UI components, themes
│   ├── user/                           # Grouped by screen/flow
│   │   ├── UserViewModel.kt            # Orchestrates Use Cases and manages UI state
│   │   ├── UserUiState.kt              # Data class representing the screen state
│   │   └── UserScreen.kt               # Jetpack Compose UI (or Fragment/Activity)
│   └── mapper/                         # UI Mappers (Domain -> UI State)
│
└── di/                                 # Dependency Injection (Hilt, Koin, or Dagger)
    └── AppModule.kt                    # Provides DB, API, and Repository singletons

Domain Layer: Code Samples (Kotlin/Android)

The Domain Layer is pure Kotlin and contains zero dependencies on Android frameworks, databases, or network libraries.

1. Custom Domain Exceptions

Define specific exceptions to represent business rule violations.

sealed class DomainException(message: String) : Exception(message)

class InvalidEmailException(email: String) : 
    DomainException("The provided email '$email' is not a valid format.")

class WeakPasswordException(reason: String) : 
    DomainException("Password does not meet security requirements: $reason")

class NegativeAmountException : 
    DomainException("Monetary amounts cannot be negative.")

2. Value Objects with Validation

Value Objects encapsulate validation logic. They are immutable and ensure that the system never processes "garbage" data.

@JvmInline
value class Email(val value: String) {
    init {
        val emailRegex = "^[A-Za-z0-9+_.-]+@(.+)\$".toRegex()
        if (!value.matches(emailRegex)) {
            throw InvalidEmailException(value)
        }
    }
}

data class Password(val value: String) {
    init {
        if (value.length < 8) {
            throw WeakPasswordException("Must be at least 8 characters.")
        }
        if (!value.any { it.isDigit() }) {
            throw WeakPasswordException("Must contain at least one digit.")
        }
    }
}

3. Entities

Entities have a unique identity (ID) and encapsulate enterprise-wide business rules.

data class User(
    val id: String,         // Unique Identity
    val email: Email,       // Value Object
    val password: Password, // Value Object
    val isActive: Boolean = true
) {
    // Business logic within the entity
    fun deactivate(): User {
        return this.copy(isActive = false)
    }
}

4. Repository Interfaces (Ports)

These interfaces define the contracts for data operations. The implementation resides in the Infrastructure/Data layer.

interface UserRepository {
    suspend fun save(user: User)
    suspend fun findByEmail(email: Email): User?
    suspend fun exists(email: Email): Boolean
}

5. Use Cases (Application-Specific Rules)

Use Cases orchestrate the flow of data. They use the Repository interfaces and Domain Entities to perform a specific task.

class RegisterUserUseCase(
    private val userRepository: UserRepository
) {
    suspend operator fun invoke(emailInput: String, passwordInput: String) {
        // 1. Validation happens automatically during Value Object instantiation
        val email = Email(emailInput)
        val password = Password(passwordInput)

        // 2. Business Rule Check
        if (userRepository.exists(email)) {
            throw DomainException("A user with this email already exists.")
        }

        // 3. Entity Creation
        val newUser = User(
            id = java.util.UUID.randomUUID().toString(),
            email = email,
            password = password
        )

        // 4. Persistence via Interface
        userRepository.save(newUser)
    }
}

Key Implementation Principles in this Layer

Validation at the Gate: The Email and Password objects cannot be created in an invalid state. If the RegisterUserUseCase receives bad strings, the code crashes (with a caught DomainException) before any business logic is executed.
No Frameworks: Notice the absence of Context, Parcelable, JSONObject, or Room annotations (@Entity, @PrimaryKey). This ensures the core logic is 100% unit-testable on a standard JVM without an emulator.
Immutability: Data classes and value classes are used to ensure that once a domain object is validated and created, its state cannot be modified unpredictably.

Data Layer: Code Samples (Kotlin/Android with API)

The Data Layer (Infrastructure) implements the interfaces defined in the Domain Layer. It handles the technical details of communicating with external APIs using libraries like Retrofit and mapping external data formats into Domain Entities and Value Objects.

1. Data Transfer Objects (DTOs)

These classes represent the structure of the JSON data returned by the API. They are annotated with serialization metadata and remain separate from Domain Entities.

import com.google.gson.annotations.SerializedName

data class UserResponseDto(
    @SerializedName("id") val id: String,
    @SerializedName("email_address") val email: String,
    @SerializedName("is_active") val isActive: Boolean,
    @SerializedName("created_at") val createdAt: String
)

data class UserRequestDto(
    @SerializedName("email") val email: String,
    @SerializedName("password_hash") val passwordHash: String
)

2. Retrofit API Service

This interface defines the HTTP endpoints. It uses the DTOs for requests and responses.

import retrofit2.http.Body
import retrofit2.http.GET
import retrofit2.http.POST
import retrofit2.http.Path

interface UserApiService {
    @GET("users/{id}")
    suspend fun getUserById(@Path("id") id: String): UserResponseDto

    @POST("users/register")
    suspend fun registerUser(@Body request: UserRequestDto): UserResponseDto
}

3. Data Mappers

Mappers are responsible for converting DTOs into Domain Entities. During this conversion, strings from the API are passed into Value Objects, which triggers the domain-level validation.

// Extension functions for mapping
fun UserResponseDto.toDomain(): User {
    return User(
        id = this.id,
        // Passing raw API string into the Value Object constructor
        // If the API returns an invalid email, the Value Object throws an exception here
        email = Email(this.email), 
        password = Password("dummy_api_password"), // Passwords typically aren't returned by APIs
        isActive = this.isActive
    )
}

fun User.toRequestDto(): UserRequestDto {
    return UserRequestDto(
        email = this.email.value,
        passwordHash = this.password.value // Simplified for example
    )
}

4. Repository Implementation

This class implements the UserRepository interface from the Domain Layer. It uses the UserApiService to fetch data and the mappers to return domain objects to the application layer.

class UserRepositoryImpl(
    private val apiService: UserApiService
) : UserRepository {

    override suspend fun findByEmail(email: Email): User? {
        return try {
            // Note: In a real scenario, you would have an endpoint to find by email
            val response = apiService.getUserById(email.value)
            response.toDomain()
        } catch (e: Exception) {
            // Log error or handle network-specific exceptions
            null
        }
    }

    override suspend fun save(user: User) {
        val requestDto = user.toRequestDto()
        apiService.registerUser(requestDto)
    }

    override suspend fun exists(email: Email): Boolean {
        return try {
            apiService.getUserById(email.value)
            true
        } catch (e: Exception) {
            false
        }
    }
}

Key Implementation Principles in this Layer

Decoupling: The UserResponseDto can change its field names (e.g., from email_address to contact_email) without affecting the User entity in the Domain Layer. Only the Mapper needs to be updated.
Infrastructure Isolation: Retrofit annotations and JSON logic are confined to this layer. The Domain Layer remains unaware of the networking library being used.
Boundary Validation: When response.toDomain() is called, the Email(this.email) constructor is invoked. If the server sends an invalid email format, the system throws a DomainException at the boundary of the Data Layer, preventing invalid data from entering the application core.
Dependency Inversion: This layer depends on the UserRepository interface (Domain) to know what methods to implement, but the Domain does not depend on this implementation.

Presentation Layer: Code Samples (Kotlin/Android)

The Presentation Layer is responsible for rendering data to the screen and capturing user interactions. In modern Android development, this involves a ViewModel to manage state and a UI Component (Jetpack Compose or Fragments) to display it.

1. UI State Representation

The UI state is a data class or sealed class that represents exactly what the user sees on the screen at any given moment.

sealed class RegistrationUiState {
    object Idle : RegistrationUiState()
    object Loading : RegistrationUiState()
    object Success : RegistrationUiState()
    data class Error(val message: String) : RegistrationUiState()
}

2. ViewModel Implementation

The ViewModel interacts with the Use Cases. It is responsible for catching DomainException thrown by Value Objects or Use Cases and converting them into human-readable error messages for the UI.

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.launch

class RegistrationViewModel(
    private val registerUserUseCase: RegisterUserUseCase
) : ViewModel() {

    private val _uiState = MutableStateFlow<RegistrationUiState>(RegistrationUiState.Idle)
    val uiState: StateFlow<RegistrationUiState> = _uiState

    fun onRegisterClicked(emailInput: String, passwordInput: String) {
        viewModelScope.launch {
            _uiState.value = RegistrationUiState.Loading

            try {
                // The Use Case is called with raw strings.
                // Internally, the Use Case creates Value Objects (Email, Password).
                // If validation fails, a DomainException is thrown immediately.
                registerUserUseCase(emailInput, passwordInput)

                _uiState.value = RegistrationUiState.Success
            } catch (e: DomainException) {
                // Catch specific domain errors and update the UI state
                _uiState.value = RegistrationUiState.Error(e.message ?: "Invalid Input")
            } catch (e: Exception) {
                // Catch unexpected system/network errors
                _uiState.value = RegistrationUiState.Error("An unexpected error occurred")
            }
        }
    }
}

3. UI Component (Jetpack Compose)

The UI observes the uiState from the ViewModel and reacts to changes. It does not contain any business logic or validation logic; it simply passes strings to the ViewModel.

@Composable
fun RegistrationScreen(viewModel: RegistrationViewModel) {
    val state by viewModel.uiState.collectAsState()
    var email by remember { mutableStateOf("") }
    var password by remember { mutableStateOf("") }

    Column {
        TextField(
            value = email,
            onValueChange = { email = it },
            label = { Text("Email") }
        )

        TextField(
            value = password,
            onValueChange = { password = it },
            label = { Text("Password") },
            visualTransformation = PasswordVisualTransformation()
        )

        Button(onClick = { viewModel.onRegisterClicked(email, password) }) {
            Text("Register")
        }

        // Display state-specific UI
        when (state) {
            is RegistrationUiState.Loading -> CircularProgressIndicator()
            is RegistrationUiState.Success -> Text("Account Created Successfully!", color = Color.Green)
            is RegistrationUiState.Error -> Text("Error: ${(state as RegistrationUiState.Error).message}", color = Color.Red)
            else -> {}
        }
    }
}

Key Implementation Principles in this Layer

Logic-Free Views: The RegistrationScreen does not check if the email is valid. It delegates that responsibility to the Domain layer (via the ViewModel and Use Case). This ensures that validation rules are never duplicated in the UI code.
State-Driven UI: The UI is a "dumb" reflection of the RegistrationUiState. This makes the UI highly predictable and easy to test with Compose UI tests.
Exception Translation: The ViewModel acts as a translator. It catches technical or domain-specific exceptions (like WeakPasswordException) and transforms them into a state that the UI can render (an error message string).
Decoupling from Domain: The UI layer depends on the ViewModel, and the ViewModel depends on the Use Case interface. The UI never interacts directly with the UserRepository or the UserApiService.

The Power Saving Paradox (Part 2): WorkManager and CoroutineWorker

David Njoroge — Sat, 24 Jan 2026 12:52:08 +0000

Mastering the WorkManager and CoroutineWorker: Surviving the Android Power State Machine

In the modern Android ecosystem, the days of spawning a long-running Thread or keeping a Service alive indefinitely are over. If you attempt to do so, the system’s Low Memory Killer (LMK) or Power Management Service will terminate your process without warning.

For Kotlin developers, the primary tool for survival is WorkManager. It is not just a library; it is a high-level abstraction layer that sits on top of the OS’s power-saving features, ensuring your code runs reliably while respecting the user's battery.

In my previous post, we dived deeper to the engineering of power saving and the architectural constraints, visit The Power Saving Paradox (Part 1) to learn more.

1. The Architecture: Why CoroutineWorker?

While the base Worker class is available, Kotlin developers should almost always use CoroutineWorker. It allows you to use Structured Concurrency to perform asynchronous tasks.

The Power Advantage: When you use a CoroutineWorker, WorkManager automatically handles the WakeLock for you. It ensures the CPU stays awake exactly as long as your doWork() function is running and releases it the moment you return a Result.

The Implementation

@HiltWorker
class AdvancedDataSyncWorker @AssistedInject constructor(
    @Assisted appContext: Context,
    @Assisted workerParams: WorkerParameters,
    private val api: WeatherApi,
    private val dao: WeatherDao,
    private val ioDispatcher: CoroutineDispatcher = Dispatchers.IO
) : CoroutineWorker(appContext, workerParams) {

    override suspend fun doWork(): Result = withContext(ioDispatcher) {
        val cityName = inputData.getString("KEY_CITY") ?: return@withContext Result.failure()

        try {
            // 1. OS CHECK: Is the system trying to stop us?
            if (isStopped) return@withContext Result.retry()

            // 2. FORGROUND PROMOTION: 
            // If the task is critical, move to Foreground to avoid LMK (Low Memory Killer)
            // This is required for tasks longer than 10 minutes (pre-Android 14)
            // setForeground(createForegroundInfo())

            // 3. CHUNKED EXECUTION:
            // Don't do one massive operation. Break it up.
            val rawData = api.getForecast(cityName)

            // Cooperative Cancellation Check: After heavy network
            if (isStopped) return@withContext Result.retry()

            val domainModels = rawData.map { dto -> 
                // Check in loops!
                // You can save progress point if isStopped is true
                if (isStopped) return@withContext Result.retry()
                dto.toDomain() 
            }

            // 4. TRANSACTIONAL INTEGRITY:
            dao.insertData(domainModels)

            Result.success()

        } catch (e: IOException) {
            // Network failure: Signal to WorkManager to use Exponential Backoff
            if (runAttemptCount < 5) {
                Result.retry()
            } else {
                Result.failure()
            }
        } catch (e: Exception) {
            // Permanent failure (e.g., Parsing error)
            Result.failure()
        }
    } // WakeLock is released here

    private fun createForegroundInfo(): ForegroundInfo {
        // Create notification required for Foreground Services
        val notification = NotificationCompat.Builder(applicationContext, "sync_channel")
            .setContentTitle("Syncing Data...")
            .setSmallIcon(R.drawable.ic_sync)
            .build()
        return ForegroundInfo(101, notification)
    }
}

2. The Power State Dance: WakeLocks & Radio States

To save battery, Android wants to put the Application Processor (AP) and the Cellular Radio to sleep. WorkManager manages this "dance" behind the scenes.

The WakeLock Lifecycle: When your job starts, WorkManager acquires a PartialWakeLock. This keeps the CPU in an "Active" state (C0) but allows the screen to stay off. If your code is inefficient and runs for 10 minutes, you are holding the CPU hostage.
Radio State Optimization: By setting Constraints, you tell WorkManager to wait until the Radio is already active (e.g., when the user is using another app or on Wi-Fi). This prevents your app from being the one that forces the Radio to transition from IDLE to DCH (High Power), which saves the massive energy cost of the "Radio Tail."

3. Constraints: The Negotiator

The most powerful way to avoid being "The Battery Killer" is to use Constraints. By setting constraints, you tell the OS: "I am a good citizen. Don't wake up the phone just for me; wait until these conditions are met." These are the conditions the OS must meet before your code is allowed to wake up the hardware.

fun scheduleSmartWork(context: Context) {
    val constraints = Constraints.Builder()
        .setRequiredNetworkType(NetworkType.UNMETERED)
        .setRequiresBatteryNotLow(true)
        .setRequiresCharging(true)
        .setRequiresDeviceIdle(true) 
        .build()

    val workRequest = PeriodicWorkRequestBuilder<AdvancedDataSyncWorker>(
        repeatInterval = 1, 
        repeatIntervalTimeUnit = TimeUnit.HOURS,
        flexTimeInterval = 15, // Run in the last 15 mins of the hour
        flexTimeIntervalUnit = TimeUnit.MINUTES
    )
    .setConstraints(constraints)
    .setBackoffCriteria(
        BackoffPolicy.EXPONENTIAL, // 30s, 60s, 120s...
        WorkRequest.MIN_BACKOFF_MILLIS,
        TimeUnit.MILLISECONDS
    )
    .addTag("data_sync_tag")
    .build()

    WorkManager.getInstance(context).enqueueUniquePeriodicWork(
        "UniqueSyncName",
        ExistingPeriodicWorkPolicy.KEEP, // Don't restart the cycle if already queued
        workRequest
    )
}

Breaking Down the Negotiator:

setRequiredNetworkType(NetworkType.UNMETERED): Saves the Radio. Waiting for Wi-Fi uses significantly less power than LTE/5G.
setRequiresBatteryNotLow(true): Prevents your app from being the one that kills the last 15% of the user's battery.
setRequiresCharging(true): Prevents your app from running until the user is plugged in.
setRequiresDeviceIdle(true): DeviceIdle means the user hasn't touched the phone in a while. This tells the OS to wait until the device is in Deep Doze and a maintenance window opens. This is the most power-efficient way to sync data. It is the best time for heavy DB maintenance or ML model training.

4. WorkManager vs. AlarmManager: The Great Debate

A common mistake is using AlarmManager for background tasks.

AlarmManager is for Timing. Use it only if something must happen at exactly 7:00 AM (e.g., an Alarm Clock). It is extremely expensive because it forces the AP to wake up regardless of the system state. AlarmManager is the one that says, "Do this exactly at this time".
WorkManager is for Reliability. It guarantees that the task will run eventually, even if the device restarts. It respects Doze and Standby Buckets by "batching" your work with other apps. WorkManager is the one that says, "Do this when you get time from such a time at your own convenience".

5. Guide: Do's and Don'ts for Kotlin Developers

DO:

Check isStopped: Always check for cancellation inside your loops or between long-running tasks. If the system enters Doze, it will stop your worker. If you don't check isStopped, your coroutine continues to run in a "zombie" state, wasting battery.
Use Expedited Jobs: If you have a task that needs to happen immediately (like sending a message), use setExpedited(OutOfQuotaPolicy.RUN_AS_NON_EXPEDITED_WORK_REQUEST). This gives you a high-priority window even in power-saving modes.
Inject Dispatchers: Use Dispatchers.IO for networking/DB work within your worker to ensure you aren't blocking the worker's main thread.

DON'T:

Don't hold infinite loops: A Worker has a execution window (usually 10 minutes). If you exceed this, the OS will hard-kill your process.
Don't use Thread.sleep(): This keeps the CPU core active and burning power. Use Kotlin's delay() which is non-blocking and allows the underlying thread to be used for other tasks or enter a low-power state.
Don't ignore Standby Buckets: Remember that if a user hasn't opened your app in days, your Worker may be delayed by up to 24 hours. Don't design features that rely on "background real-time" updates without a Foreground Service.

If you have more of the dos and don'ts write a comment below we dive deep into it.

6. Surviving OEM Aggression (Samsung/Xiaomi)

Even with perfect Kotlin code, manufacturers like Samsung might kill your Worker. To fight this:

Unique Work: Always use enqueueUniqueWork. This prevents multiple instances of your worker from stacking up and being flagged as "malicious" by OEM battery monitors.
Backoff Policy: Use BackoffPolicy.EXPONENTIAL. If your sync fails because the OEM cut your network, waiting 30s, then 60s, then 120s proves to the OS that your app is "behaving" and trying to save power.

7. Testing Power States (ADB Mastery)

You cannot test battery-saving code by just hitting "Run" in Android Studio. You must simulate a dying battery and a sleeping device.

Force Doze Mode

# Unplug the phone
adb shell dumpsys battery unplug

# Enter Light Doze
adb shell dumpsys deviceidle step light

# Enter Deep Doze (No network, no alarms)
adb shell dumpsys deviceidle force-idle

# Check current status
adb shell dumpsys deviceidle get deep

Force Standby Buckets

# Force your app into the "Rare" bucket
adb shell am set-standby-bucket com.yourapp.package rare

# Check your bucket
adb shell am get-standby-bucket com.yourapp.package

8. Pro-Tips Checklist for the Senior Android Developer

Stop using Thread.sleep(): It keeps the CPU core in C-state of C0 (Active). Use delay() in your CoroutineWorker. It suspends the coroutine, allowing the thread to be reused and the CPU to potentially downclock.
Inject your Dispatchers: Never hardcode Dispatchers.IO. Inject them so you can swap them for StandardTestDispatcher in your unit tests.
The 10-Minute Rule: A Worker has a maximum execution window of 10 minutes. If your task (like a video export) takes longer, you must use setForeground().
Observability: Use WorkManager.getWorkInfoByIdLiveData() to show the user the progress of background tasks. Transparency reduces the chance of the user "Force Stopping" your app.
Chaining Work: Use beginWith(...).then(...).enqueue() to break complex logic into small, power-efficient steps. If the third step fails, the first two don't need to re-run.

The Bottom Line:

In the world of Android, your background code is a guest. If you are loud (high CPU), messy (memory leaks), or stay too long (WakeLocks), the host (OS) will kick you out. By using CoroutineWorker and respecting constraints, you become a "polite guest" that is allowed to return again and again.

The Power Saving Paradox (Part 1): Architectural Constraints and the Engineering of Power Saving

David Njoroge — Thu, 22 Jan 2026 13:15:36 +0000

In the early days of mobile development, the relationship between code and hardware was relatively linear. If you wrote a loop, the CPU executed it. If you opened a socket, the radio stayed active. However, as hardware evolved and user expectations for multi-day battery life grew, Google transformed Android from an open playground into a highly regulated Resource-Constrained Runtime Environment.

To a user, "Power Saving" is a simple toggle. To a developer, it is a sophisticated, multi-layered gauntlet of system-level restrictions that fundamentally change how code behaves once an application leaves the foreground.

1. Defining Power Saving: The System State Machine

At a technical level, power saving is the practice of interrupting the continuity of execution. The Android framework achieves this through three primary pillars: CPU frequency scaling, Radio state management, and Process suspension.

A. The "Doze" State Machine (Deep Power Management)

Introduced in Android 6.0 and refined in every version since, Doze is a kernel-level orchestration that forces the device into a low-power state when the screen is off and the device is stationary.

From a technical perspective, Doze is a state machine with two levels:

Light Doze: Occurs shortly after the screen turns off. The system restricts network access and prevents syncs/jobs from running unless a "Maintenance Window" opens.
Deep Doze: Triggered when the device remains stationary (monitored via the SMD—Significant Motion Detector—sensor). In this state, the system ignores Wakelocks, suppresses Wi-Fi scans, and pushes the "Maintenance Windows" further apart exponentially (e.g., 10 mins, then 1 hour, then 6 hours).

B. App Standby Buckets (Hierarchical Prioritization)

The system uses the UsageStats service to categorize apps into buckets based on their recency of use:

Active: The app is in the foreground or has a running foreground service.
Working Set/Frequent: The app is used often but is currently in the background. Job execution is slightly delayed.
Rare: The app is almost never used. Background jobs are limited to a tiny window (e.g., once per day) and network access is heavily throttled.
Restricted: Added in recent APIs, this bucket effectively kills the app's ability to do anything in the background.

To learn more about power state machine and the four major eras please Eras of Android Power State Machine

2. How Power Saving Relates to the Developer: The "Death of Determinism"

For a developer, the primary challenge of power saving is the loss of deterministic execution. In a desktop environment, if you schedule a task for 2:00 PM, it runs at 2:00 PM. In Android, that task might run at 2:00 PM, 2:15 PM, or 4:00 AM the next day—or not at all.

The Problem of the "Tail State"

Every time your code wakes up the device to perform a network request, it triggers the Radio State Machine.

DCH (Dedicated Channel): High power consumption.
FACH (Forward Access Channel): Lower power.
Idle: Minimal power.

When your app sends even 1KB of data, the radio jumps to DCH. Crucially, the radio stays in DCH for a "tail period" (usually 5–15 seconds) after the transmission ends, waiting for more data. If your app wakes up the radio every 2 minutes for a small sync, the radio never returns to Idle. This is why the system bundles your requests with other apps—a process called Job Coalescing.

The Wakelock Battle

Historically, developers used PowerManager.WakeLock to keep the CPU running. However, modern Android versions treat Wakelocks as "suggestions" rather than commands. If the system detects a "Long-held Wakelock" while in Doze, it will perform a Wakelock Stripping operation, essentially ignoring your code's request to stay awake to prevent "Battery Drainers."

I have discussed more about wakelock here in Android's Physical Layer and the Wakelock Arms Race and how it has evolved over the years visit Android's Radios, Wakelocks, and the Evolution of Android Constraints

3. The Technical Conflict: Foreground vs. Background

The biggest complication for developers is the Foreground Service (FGS) Restriction (intensified in Android 12, 13, and 14). Over the years the handling this services has changed as discussed here

Previously, if you needed to do something important, you started a Foreground Service. Now, Android imposes a "Wait and See" policy:

FGS Start Restrictions: Apps cannot start a foreground service while in the background unless they meet specific, narrow exceptions (e.g., an alarm or a high-priority FCM message).
Type Declaration: In Android 14+, you must declare a foregroundServiceType (e.g., location, dataSync, mediaPlayback). If your code performs an action that doesn't match your declared type, the system will throw a SecurityException.

Why this makes things complicated:

State Management: You must now write complex logic to handle cases where your service is denied start-up.
User Perception: You are forced to show a notification for background work. If the user swipes it away (or the system kills it for power saving), your process dies, often leaving your local database in an inconsistent state.
Testing Fragmentation: Because different manufacturers (OEMs) like Samsung or Xiaomi have "Auto-optimize" features that are more aggressive than AOSP (Android Open Source Project), a developer may find their app works perfectly on a Google Pixel but fails instantly on a Galaxy S24.

4. Hardware Interfacing: The Physical Cost of Code

To truly understand the technical complexity, one must look at the Application Processor (AP).
When the AP is in a "Deep Sleep" C-state (Power State), waking it up requires an Interrupt. Waking the processor takes a significant burst of current. To dive deep into C-state please click here

If a developer writes an inefficient polling loop:

The CPU wakes up (High Current Spike).
The L1/L2 Caches are reloaded (Energy Cost).
The code executes for 5ms.
The CPU attempts to go back to sleep.

If this happens every few seconds, the "Context Switching" of the hardware power state consumes more energy than the actual code execution. This is why Android developers are now forced to use Opportunistic APIs (like WorkManager) rather than Imperative APIs (like Thread.sleep or AlarmManager).

Below is a graphical representation of the relationship between your code, the OS and the hardware specifically during the background processes

Summary of Part 1

Power saving is not just a "mode"; it is a sophisticated Resource Arbiter. It forces developers to move away from "I want to run this now" to "I would like to run this when the system finds it most energy-efficient."

To dive into the Kotlin-specific implementations—WorkManager and Coroutine Scopes visit my The Power Saving Paradox (Part 2)

The Architectural Schism: Foreground vs. Background and the Evolution of Survival

David Njoroge — Thu, 22 Jan 2026 13:11:27 +0000

In modern Android development, the distinction between "Foreground" and "Background" is not just a UI state; it is a fundamental shift in the Linux OOM (Out of Memory) Score, the CPU C-state availability, and the Radio Resource Control (RRC) priority.

To understand why your Kotlin code fails, you must understand the "Economic Theory" of Android: The system assumes all background code is a liability until proven otherwise.

1. The Technical Definition: The "OOM ADJ" Score

Every process in Android has an oom_adj (Out of Memory Adjustment) score ranging from -1000 to 1000.

Foreground Processes (Score 0-100): These are "Persistent" or "Visible." The kernel grants them nearly 100% of requested CPU cycles and immediate radio access.
Background Processes (Score 800-1000): These are "Cached" or "Idle." They are the first to be "reaped" by the Low Memory Killer (LMK) and are subject to extreme CPU throttling.

The Problem for Developers:

When a user switches apps, your process score jumps from 0 to 900 in milliseconds. The system immediately applies "Quotas" to your process. If your Kotlin Coroutine is doing a heavy computation during this transition, the system may simply "freeze" the thread, leading to what looks like a crash but is actually a Kernel-level Suspend.

2. The Version-by-Version Evolution of the "Trap"

How Google progressively narrowed the "Background" window:

Android 6.0 - 7.0 (The Doze Revolution)

The Change: Introduced Deep Doze (Stationary) and Light Doze (Moving).
Technical Impact: Before this, background threads could run as long as they had a WakeLock. After this, the system began stripping network access and ignoring alarms.
The Developer Headache: Apps that relied on constant WebSocket connections (MQTT, etc.) started dying. Developers had to move to FCM (Firebase Cloud Messaging) to "poke" the app from the outside.

Android 8.0 - 9.0 (The Execution Limits)

The Change: Background Service Limits. You could no longer call startService() if the app was in the background.
Technical Impact: This forced the transition to JobScheduler and eventually WorkManager.
Standby Buckets (Android 9): The OS started using a machine-learning model (App Standby) to predict when you'd use an app. If you were in the "Rare" bucket, you were limited to one 10-minute window per day for all background work.

Android 12 - 14 (The Intent Declaration Era)

The Change: Foreground Service (FGS) Restrictions.
Technical Impact: In Android 14, you cannot start a Foreground Service unless you declare a foregroundServiceType.
The "Complication": If you declare type="location", but your Kotlin code tries to access the Camera, the system triggers a SecurityException. The system now audits your code's intent against its actions.

3. The Physical Cost: Radio States (DCH vs. FACH)

Why is the background restricted so heavily? It's about the Baseband Processor (BP), the secondary computer in the phone that handles the radio.

DCH (Dedicated Channel): The radio is "screaming" at the tower. (High Power: 200mA+).
FACH (Forward Access Channel): The radio is "whispering." (Medium Power: 40-60mA).
Idle: The radio is "listening." (Low Power: <2mA).

The "Tail" Complication:
When your background Kotlin worker finishes a 100kb sync, the radio stays in DCH for ~5 seconds "just in case." If you have 20 apps syncing at different times, the radio never goes to Idle. This is why Android 15+ forces Job Coalescing—it holds your job until 5 other apps also have jobs, then fires the radio once to handle all of them, sharing one "Tail" period.

4. The OEM Nightmare: Models and Manufacturers

Standard Android (Pixel) is predictable. But major manufacturers (Samsung, Xiaomi, etc.) have their own "Shadow OS" for power management.

Samsung (One UI) - "The App Killer"

Samsung uses a proprietary service called Device Care.

Technical Deviation: Even if you follow all Google rules and use WorkManager, Samsung may put your app into "Deep Sleep" if it isn't opened for 3 days.
The "Force Stop" Problem: Samsung often treats "swiping away" an app as a force-stop. In Android, a force-stopped app cannot run any code (no alarms, no jobs) until the user manually taps the icon again.

Xiaomi (MIUI/HyperOS) - "The Resource Dictator"

Xiaomi is the most aggressive.

Technical Deviation: They often ignore the IGNORE_BATTERY_OPTIMIZATIONS permission. Even if the user says "Don't Optimize," Xiaomi's Power Genius will kill background processes if they consume more than 2% of CPU for more than 30 seconds.

Google Pixel - "The Standard"

Pixels follow the AOSP (Android Open Source Project) rules strictly. If your app works on a Pixel but fails on a Galaxy, it is an OEM-specific "Power Policy" violation.

5. How Kotlin Developers Navigate the Chaos

If you are writing Kotlin today, you must architect for Interruption.

A. The "WorkManager + Coroutines" Strategy

WorkManager is a wrapper around JobScheduler (API 23+) and AlarmManager. When using Kotlin, always use CoroutineWorker.

class ResilientSyncWorker(appContext: Context, workerParams: WorkerParameters):
    CoroutineWorker(appContext, workerParams) {

    override suspend fun doWork(): Result {
        // 1. The system grants a temporary WakeLock here
        return withContext(Dispatchers.IO) {
            try {
                // 2. Perform network call (Radio moves to DCH)
                val response = repository.doLongSync()

                // 3. Always check if the job was cancelled by the OS
                if (isStopped) {
                    // Clean up and save partial progress
                    return@withContext Result.retry()
                }

                Result.success()
            } catch (e: Exception) {
                // 4. Exponential Backoff: Don't spam the radio
                Result.retry()
            }
        }
    }
}

B. Handling Android 14+ Foreground Transitions

If you must do work immediately while the app moves to the background:

Request POST_NOTIFICATIONS: You cannot run an FGS without a notification.
Declare Types: Use ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC.
Use setExpedited(true): In WorkManager, this attempts to run the job immediately, bypassing some Doze restrictions, but it has a strict time quota (usually 1-2 minutes).

C. The "State Check" Pattern

Since OEMs can kill your process at any time, your Kotlin data layer must be Atomically Persistent.

Never assume a variable in a ViewModel or Singleton will exist when the user returns.
Use Room or DataStore to save "Checkpoint" states during background work. If the OS kills your worker, it can resume from the last saved byte when the next "Maintenance Window" opens.

Final Technical Summary

Power saving has evolved from Manual (Wakelocks) -> Batching (JobScheduler) -> Context-Aware (Doze) -> AI-Predicted (Standby Buckets).

For the developer, the "complication" is that code is no longer continuous. Your Kotlin functions are now fragmented pieces of logic that the OS pauses, resumes, or kills based on the phone's temperature, the battery percentage, and the user's habits. To survive, you must stop writing "Apps" and start writing "State Machines" that can be serialized to disk at a moment's notice.

Silicon-Level Power Management — The Application Processor (AP) and the Hardware Interfacing Gauntlet

David Njoroge — Thu, 22 Jan 2026 12:12:18 +0000

To a Kotlin developer, the "CPU" is an abstract resource that executes code. At the hardware level, however, the Application Processor (AP) is a complex system of power domains that are physically disconnected and reconnected hundreds of times a minute.

1. The Anatomy of the Application Processor (AP)

In a modern System-on-Chip (SoC) like a Snapdragon or Google Tensor, the AP is not a single entity. it is a "Multi-Core Heterogeneous Architecture" consisting of High-Performance cores (Cortex-X/A700 series) and Efficiency cores (Cortex-A500 series).

The C-State Machine (Power States)

The AP operates through various C-states (CPU States), which define the depth of sleep:

C0 (Active): The core is powered on and executing instructions.[1] This is the most expensive state (hundreds of mA).
C1 (Halt): The clock is gated (stopped), but the core remains powered. It can wake up almost instantly.[2]
C3/C6 (Deep Sleep): The core’s voltage is reduced or removed entirely. The L1/L2 caches may be flushed to the L3 cache or RAM.
Deepest Sleep (SoC-wide Suspend): The entire AP is powered down. Only a tiny "Always-On" (AON) domain remains powered to listen for hardware interrupts (IRQs).

The Developer Trap: If your Kotlin code uses a simple while(true) loop or a frequent Handler, you prevent the AP from ever dropping below C1. The hardware remains "warm," and leakage current drains the battery even if the CPU usage percentage looks low in the profiler.

2. The "Wake-up Penalty": The Micro-Economics of Joules

Waking the AP from a deep C-state is not "free." It is a massive physical event called an Inrush Current Spike.

When an interrupt (like a timer or network packet) wakes the AP:

Voltage Regulators (PMIC) must ramp up power (consuming energy).
Clock Generators (PLLs) must stabilize.
The Memory Controller must wake the RAM.
Cache Cold-Start: The CPU caches (L1/L2) are empty. The AP must fetch data from the relatively slow and power-hungry RAM.

Technical Reality: Waking up the AP for 1ms of work often consumes enough energy to have kept the AP in a low-power state for seconds. This is why Android 15 and 16 are so aggressive about Job Coalescing. If 5 apps want to run a 1ms task, the OS forces them to wait and run all 5 during one wake-up cycle, amortizing the "Wake-up Penalty" across all apps.

3. Hierarchical Processing: AP vs. Sensor Hub

One of the greatest hardware shifts in the last decade is the Sensor Hub.

The Problem: High-frequency data (like accelerometer readings at 100Hz for a step counter) would require the high-power AP to stay awake 100% of the time.
The Hardware Solution: A tiny, low-power Microcontroller (MCU)—the Sensor Hub—sits between the sensors and the AP. It consumes <1mA.[3]
The Interfacing: The Sensor Hub collects data in a hardware FIFO (First-In-First-Out) buffer. It only sends an IRQ (Interrupt Request) to the main AP when the buffer is full or a "Significant Motion" is detected.

Kotlin Implication: If you use SensorManager in Kotlin, you must choose your sampling rate wisely. If you request SENSOR_DELAY_FASTEST, you might be forcing the AP to stay in C0, bypassing the Sensor Hub's efficiency and killing the battery in hours.

4. The Radio Interfacing: Baseband Processor (BP)

The AP does not talk to the cell tower; the Baseband Processor (BP) does. These are two separate computers.

The "Baseband-to-AP" Interrupt: When a "Push Notification" arrives, the BP receives the radio packet, realizes it's for an app, and sends a hardware interrupt to the sleeping AP.
The "Wakeup-Broadcast": The Linux kernel receives the IRQ, wakes the AP cores, and triggers the Android BroadcastReceiver.

If your app is poorly optimized, it might cause "Baseband-Induced Wakeups." For example, if your server sends frequent, tiny "keep-alive" packets, the BP must wake the AP every time, even if your Kotlin code does nothing with the data.

5. Navigating Hardware Constraints as a Kotlin Developer

A. The "Race to Sleep" Principle

The most efficient way to run Kotlin code is to Race to Sleep.

Bad: Doing work slowly on a background thread to "save CPU." This keeps the AP in a mid-power state longer.
Good: Bursting the work at high frequency (using Dispatchers.Default on multiple cores) to finish the task in 10ms and let the AP drop back to a deep C-state immediately.

B. Use Batching at the Logic Layer

Don't just rely on the OS to batch. In your Kotlin Repository, use a buffer.

// INEFFECIENT: Wakes the radio and AP for every event
fun logEvent(event: Event) {
    api.send(event)
}

// POWER-EFFICIENT: Wait until we have 10 events, then burst them
private val eventBuffer = mutableListOf<Event>()
fun logEvent(event: Event) {
    eventBuffer.add(event)
    if (eventBuffer.size >= 10) {
        WorkManager.enqueue(SyncWorker(eventBuffer.toList()))
        eventBuffer.clear()
    }
}

C. Respecting the "Maintenance Window"

When Android enters Doze Mode, it physically disables the AP's ability to respond to most non-critical interrupts. Your AlarmManager.set() might be ignored at the hardware level. Using WorkManager ensures that when the system does decide to wake the AP for its own maintenance (e.g., checking for system updates), your Kotlin code "piggybacks" on that existing hardware wake-up.

Summary: The Hardware Reality

The Application Processor is a "beast" that is expensive to wake up. Modern Android development is no longer about managing memory; it is about managing Interrupts.

Every line of Kotlin you write that runs in the background is a "request" to the hardware to spend a specific amount of Joules. By understanding C-states, the Wake-up Penalty, and the Sensor Hub, you can write code that respects the silicon, resulting in an app that stays installed because it doesn't appear at the top of the user's "Battery Usage" list.

Android's Radios, Wakelocks, and the Evolution of Android Constraints

David Njoroge — Thu, 22 Jan 2026 12:06:19 +0000

The Invisible War: Radios, Wakelocks, and the Evolution of Android Constraints

To a Kotlin developer, a network call is a suspend fun. To the hardware, it is a violent transition of state that consumes massive amounts of current. Understanding this is the difference between an app that is "efficient" and one that is "uninstalled."

1. The Physical Layer: The Radio State Machine (RRC)

The cellular radio is the most expensive component to keep active. It operates under the Radio Resource Control (RRC) protocol, which moves through three primary states.

DCH (Dedicated Channel)

The State: The radio is at full power, maintaining a dedicated high-speed link.
The Cost: ~200mA to 400mA.
The Complexity: This is the "high-performance" mode. The system enters this state the moment your code initiates a request.

FACH (Forward Access Channel)

The State: A lower-power intermediate state where the radio can send small control packets but doesn't have a dedicated high-speed pipe.
The Cost: ~40mA to 100mA.
The Trap: The "Tail Effect." When your data transfer finishes, the radio doesn't go to sleep. It stays in DCH for ~5 seconds, then drops to FACH for ~15 seconds. If your Kotlin code "pings" a server every 15 seconds, you effectively keep the radio in a high-power state indefinitely.

IDLE

The State: The radio is functionally off, only listening for "paging" signals.
The Cost: <2mA.
The Goal: This is where we want the device to be 95% of the time.

2. The Wakelock Battle: From King to Peasant

A Wakelock is a software handle that prevents the CPU from entering its deep-sleep C-states.

The Old Way (Android 1.0 - 5.1): Developers used PowerManager.PARTIAL_WAKE_LOCK. You could hold this forever. If your code was buggy, the phone stayed at 1GHz in the user's pocket until it died.
The Turning Point (Android 6.0 Marshmallow): Google introduced Doze Mode. For the first time, the system began stripping wakelocks. Even if your code held a wakelock, if the phone was stationary, the system would ignore you.
The Modern Era (Android 12 - 15): The system now uses Wakelock Quotas. If your app is in the "Rare" or "Restricted" standby bucket, the system provides a very small window (e.g., 10 minutes per day) for background execution. Once that's gone, your wakeLock.acquire() call succeeds in the code, but the kernel ignores it.

3. The Chronological Evolution of Constraints

How did we get here? Each Android version added a new layer of "complication" for developers:

Android Version	Feature	Technical Impact on Developers
4.4 (KitKat)	Alarm Batching	`AlarmManager` no longer fires exactly at the time requested; the system bundles them to save radio "tails."
6.0 (M)	Doze Mode	Introduced the "Stationary State." Network and Wakelocks are cut off entirely during sleep.
8.0 (O)	Background Limits	Killed `background services`. If the app isn't visible, you can't start a service. You must use `JobScheduler`.
9.0 (P)	Standby Buckets	Introduced AI categorization. Your app's ability to run code now depends on how often the user clicks your icon.
12/13 (S/T)	Expedited Jobs	New restriction on `Foreground Services`. You must now "earn" the right to run immediately using WorkManager's `setExpedited(true)`.
14/15 (U/V)	FGS Types	Mandatory declaration of why you are running (e.g., `location`, `health`). If the code doesn't match the type, the OS kills the process.

4. The OEM Factor: The "Wild West" of Hardware

This is the part that frustrates developers the most. Google’s "Pure Android" (AOSP) rules are just the baseline. Major manufacturers (OEMs) add their own aggressive killers.

Samsung (One UI)

Samsung uses a feature called "App Power Management." It tracks apps that haven't been opened in 3 days and puts them into "Deep Sleep." In this state, the app cannot receive notifications, run jobs, or sync data. For a Kotlin developer, your WorkManager tasks simply disappear.

Xiaomi (MIUI / HyperOS)

Xiaomi is notoriously aggressive. Their "Battery Saver" defaults to "Restrict Background Activity" for almost all non-social media apps. They often ignore the Android standard Ignore Battery Optimizations intent, requiring users to manually dig through 5 layers of settings to allow an app to work.

Huawei & OnePlus

Historically, these OEMs used "Re-launch Killers." If a user swiped your app away from the "Recents" screen, the system would issue a force-stop, which clears all scheduled alarms and jobs. Only a manual click by the user could "revive" the app.

5. Navigating with Kotlin: The Modern Solution

As a Kotlin developer, you cannot fight these versions and OEM changes with old tools. You must use a "Declarative" approach.

A. The WorkManager + Coroutine Pattern

Do not use Thread or raw CoroutineScope. Use CoroutineWorker. It is the only API that is "aware" of Doze, Standby Buckets, and OEM restrictions.

class PowerAwareSync(context: Context, params: WorkerParameters) : CoroutineWorker(context, params) {
    override suspend fun doWork(): Result {
        // WorkManager handles the Wakelock and Radio state transitions here.
        // It waits for the "Maintenance Window" automatically.
        return try {
            val result = apiService.sync() 
            Result.success()
        } catch (e: Exception) {
            Result.retry() // Respects the system's "Backoff" power policy
        }
    }
}

B. Use "High Priority" FCM for "Waking Up"

If you need to bypass power saving (e.g., for a VoIP call or an emergency alert), you cannot do it from the device. You must send a High Priority FCM message from your server. This triggers a brief "Unrestricted" window where your Kotlin code is allowed to start a Foreground Service even on Android 14+.

C. Testing for the Real World

To see how your code behaves on different versions, use ADB to force the states:

Force Doze: adb shell dumpsys deviceidle force-idle
Test Standby Buckets: adb shell am set-standby-bucket <package> rare

Summary

The technical complication of power saving is that the OS no longer trusts the developer. Every Android update and every OEM tweak is a new wall. To navigate this, you must stop trying to "force" code to run and start "requesting" the system to run it when the Radio and CPU are already awake.

Android's Physical Layer and the Wakelock Arms Race

David Njoroge — Thu, 22 Jan 2026 12:00:37 +0000

When a Kotlin developer calls repository.syncData(), they see a network call. The Android System, however, sees a series of expensive state transitions in the cellular radio and a request to prevent the CPU from entering a low-power "C-state."

1. The Radio State Machine: DCH, FACH, and the "Tail Effect"

The cellular radio is often the single most power-hungry component in a mobile device. To manage this, the radio operates on a state machine regulated by the Radio Resource Control (RRC) protocol.

Technical States:

DCH (Dedicated Channel): The radio is in full-power mode. It has a dedicated high-speed link to the cell tower.
- Power Cost: ~200mA - 400mA.
- Latency: Low.
FACH (Forward Access Channel): A transitional state. The radio can send small amounts of data but doesn't have a dedicated channel.
- Power Cost: ~40mA - 100mA (roughly 25% of DCH).
- Latency: Higher.
IDLE: The radio is "sleeping," listening only for paging messages (calls/SMS).
- Power Cost: <2mA.

The Developer's Trap: The "Tail"

When your Kotlin code finishes a network request, the radio does not immediately go to IDLE. It stays in DCH for a "tail period" (e.g., 5 seconds) just in case more data comes, then drops to FACH for another tail period (e.g., 15 seconds), and then goes to IDLE.

The "Chirping" Problem:
If your Kotlin app sends a small "heartbeat" packet every 20 seconds, the radio stays in the DCH or FACH "tail" forever. It never reaches IDLE. This is why "polling" is an architectural sin in Android.

Kotlin Navigation:
Instead of polling, use WorkManager with setRequiredNetworkType(NetworkType.CONNECTED). WorkManager doesn't just run your code; it "coalesces" (bundles) your request with requests from other apps. If 10 apps all sync at the same time, the radio powers up to DCH once, shares the tail period, and goes back to IDLE.

2. The Wakelock Battle: Keeping the CPU Awake

While the Radio State Machine handles the "Internet," Wakelocks handle the "Brain" (the CPU).

What is a Wakelock?

By default, when the screen turns off, Android wants to "suspend" the CPU. A WakeLock is a mechanism for an app to say, "I am still doing work; do not let the CPU go to sleep."

// The "Old School" (Dangerous) way
val wakeLock: PowerManager.WakeLock =
    (getSystemService(Context.POWER_SERVICE) as PowerManager).run {
        newWakeLock(PowerManager.PARTIAL_WAKE_LOCK, "MyApp::MyWakelockTag").apply {
            acquire()
        }
    }

The Conflict: Aggressive Stripping

In early Android, if you forgot to call wakeLock.release(), the phone stayed awake until the battery hit 0%. This was a "Leaked Wakelock."

Modern Android (12, 13, 14, 15) has turned this into an arms race:

Wakelock Throttling: If your app is in a "Background" Standby Bucket, the system will ignore your acquire() call entirely.
Quota Management: The system grants each app a "time quota." Once you exceed your background execution time, the system performs a hard-kill on your process, regardless of whether you hold a wakelock.
The "Frozen" State: Even if you have a coroutine running, if the system decides your app is idle, it will "freeze" the process. Your Kotlin code isn't "paused"—the actual OS threads are suspended at the kernel level.

3. Navigating the Battle with Kotlin Coroutines

Kotlin developers must be careful: Coroutines are NOT a substitute for Wakelocks. If you start a CoroutineScope(Dispatchers.IO).launch { ... } and the screen goes off, the CPU may suspend mid-execution, leaving your coroutine in limbo.

The "Correct" Architecture: `CoroutineWorker`

To survive the power-saving gauntlet, you must use WorkManager's integration with Coroutines. CoroutineWorker automatically handles the wakelock for you.

class MySyncWorker(context: Context, params: WorkerParameters) : CoroutineWorker(context, params) {

    override suspend fun doWork(): Result {
        // The system grants a "WorkManager-held" Wakelock here
        return withContext(Dispatchers.IO) {
            try {
                val data = api.fetchData() // High-power DCH radio state triggered
                db.save(data)
                Result.success()
            } catch (e: Exception) {
                Result.retry() // Respects the "Backoff Policy" to save power
            }
        } // Wakelock is automatically released here
    }
}

Why this is better than manual Wakelocks:

System Awareness: If the device enters "Deep Doze," WorkManager will automatically suspend your CoroutineWorker and resume it when a Maintenance Window opens.
Expedited Jobs: In Android 12+, you can mark a job as Expedited. This tells the system, "This is critical (like a message notification); let me bypass some power-saving rules for a few seconds."

4. How Users Experience the Conflict

Users often don't understand these states; they only see the consequences:

The "Delayed Notification" Problem: A user receives a WhatsApp message 15 minutes late. This happens because the device was in Deep Doze, the radio was IDLE, and the system was ignoring all incoming "non-high-priority" FCM (Firebase Cloud Messaging) tickets to save battery.
The "Killed Music" Problem: A user opens a heavy game, and their background music app stops. The OOM (Out of Memory) Killer combined with Power Management decided the background music's "Standby Bucket" was too low to justify the CPU usage.

5. Summary for the Technical Developer

To navigate power saving in Kotlin:

Stop Imperative Programming: Don't say "Run this now." Use WorkManager to say "Run this when the state machine allows it."
Respect the Radio: Batch your network calls. Use Flow to combine data streams before hitting the network so the radio enters DCH only once.
Declare Intent: If you must stay awake, use a Foreground Service with a specific foregroundServiceType. This is the only way to "legitimately" win the wakelock battle in year 2026 and beyond.

Eras of Android Power State Machine

David Njoroge — Thu, 22 Jan 2026 11:44:38 +0000

The Evolution of the Android Power State Machine: From Wild West to Digital Fortress

In the early years, Android was designed for functionality first. Power saving was a secondary "nice-to-have." Today, it is a primary kernel-level constraint. This evolution can be broken into four distinct architectural eras.

1. The Unregulated Era (Android 1.0 – 4.4: KitKat)

State Machine: Binary (Screen On / Screen Off)

In this era, the system state machine was primitive. When the screen was on, the CPU ran at high frequency. When the screen was off, the system attempted to enter a "Sleep" state, but it was easily interrupted.

The Developer Power: Developers had total control. You could use WakeLocks to keep the CPU awake indefinitely. If your app wanted to sync every 30 seconds, the system would dutifully wake the radio and the CPU every 30 seconds.
The Technical Failure: This led to "Battery Bleed." One poorly written app could keep the Application Processor (AP) from ever entering a low-power C-state, draining a full battery in 4 hours while the phone sat in a pocket.
Legacy Tool: AlarmManager (Exact) was the king.

2. The Reactive Era (Android 5.0 – 5.1: Project Volta)

State Machine: The Job Scheduler Core

With Android 5.0, Google introduced Project Volta.[1] This was the first attempt to move away from "Imperative" execution (run this now) to "Declarative" execution (run this when these conditions are met).

The Innovation: The JobScheduler was born. Instead of waking the phone for one app, the system started batching tasks.
The State Machine: The system began tracking "Unmetered Network" and "Charging" as valid states for heavy work. However, background services could still run largely unfettered.

3. The Proactive Era (Android 6.0 – 8.1: Doze & Oreo Limits)

State Machine: The Stationary State Machine (Doze Mode)

This is where things became "complicated" for developers. Android 6.0 Marshmallow introduced Doze Mode, a state machine that monitored the device's physical movement.

Deep Doze (Android 6.0): If the screen is off + on battery + stationary, the system enters a "slumber." Network access is cut, and a "Maintenance Window" (a brief moment where jobs can run) occurs only once every few hours.
Light Doze (Android 7.0): Google realized people move while their phones are in their pockets. Light Doze triggers even if the device is moving, restricting network access but allowing shorter maintenance windows.
Background Execution Limits (Android 8.0): This was the "Death of the Background Service." Apps could no longer start a service in the background.[2] If you weren't visible to the user, you were effectively frozen.

4. The Predictive Era (Android 9.0 – Android 15: AI-Driven)

State Machine: Standby Buckets & The Usage-Pattern Machine

In this era, the state machine stopped looking only at the device and started looking at the user.

App Standby Buckets (Android 9): The system categorizes apps into buckets (Active, Working Set, Frequent, Rare, Restricted).[3] If the AI predicts you won't use an app for the next 4 hours, that app’s state machine is moved to a "Restricted" state where its network and jobs are throttled.
Foreground Service Types (Android 14): The system now demands to know the intent of your code. You must declare a type (e.g., location, mediaPlayback). If your code's behavior doesn't match the state expected for that type, the system kills the process.
Accelerated Doze (Android 15): In the latest stable release, Google re-engineered the Doze state machine to enter "Deep Sleep" 50% faster than Android 14. This means your "Maintenance Windows" for background sync shrink almost immediately after the user puts their phone down.

5. The Future: Android 16 (The "Baklava" Tiered System)

State Machine: Multi-Tiered AI Resource Allocation

Early leaks and developer previews for Android 16 suggest a shift toward Adaptive Resource Management driven by on-device AI.

Multiple Power-Saving Tiers: Unlike the current "On/Off" Battery Saver, Android 16 is expected to introduce "Tiers" of power saving, allowing the user (or the system) to progressively disable high-refresh rates (ARR - Adaptive Refresh Rate), AI processing, and background telemetry based on a "Time-to-Zero" prediction.
Predictive Charging & Throttling: The state machine will integrate with charging habits to throttle the CPU/GPU even while on charger to preserve long-term battery health, further complicating "Performance Mode" for developers.

Why this evolution is a "Nightmare" for Developers

As the system state machine has evolved, it has moved from Deterministic to Opportunistic.

Version 1.0 Developer: "I will run my code at 2:00 PM." (Always works)
Version 6.0 Developer: "I will run my code at 2:00 PM unless the phone is on a table." (Might work)
Version 15/16 Developer: "I will request to run my code, but the AI might decide the user doesn't like my app enough to grant me the CPU cycles, especially since the phone entered Doze 3 minutes ago." (Total uncertainty)

This unpredictability is exactly why libraries like WorkManager and Kotlin Coroutines have become mandatory tools for survival.

Database Backup In Django

David Njoroge — Tue, 08 Apr 2025 21:55:18 +0000

To back up data from your Django project, you typically want to back up the database and possibly media files (if your project handles file uploads). Here are a few methods you can use to automate backups for your Django project:

1. Database Backup (using `pg_dump`, `mysqldump`, or Django's `dumpdata`)

Django doesn’t provide a built-in command for backing up a database, but you can use standard database tools (like mysqldump for MySQL or pg_dump for PostgreSQL) or Django’s built-in dumpdata command to create a backup.

1.1. Database Backup with Django’s `dumpdata` Command

You can use Django's dumpdata command to export the data in JSON format:

Run the following command to back up data (all models, or you can specify specific apps or models):

   python manage.py dumpdata > backup.json

This will generate a JSON file (backup.json) containing all data from the database.

Backup Specific App:

If you want to back up only a specific app, use the app name:

   python manage.py dumpdata your_app_name > backup_your_app.json

1.2. MySQL Database Backup with `mysqldump`

If you're using MySQL, you can use mysqldump to back up your database:

Run mysqldump to create a backup:

   mysqldump -u username -p your_database_name > backup.sql

Replace username with your MySQL username and your_database_name with your actual database name.

Automate the Process: You can set up a cron job to automate this backup process.

1.3. PostgreSQL Database Backup with `pg_dump`

If you're using PostgreSQL, you can use pg_dump to back up your database:

Run pg_dump to create a backup:

   pg_dump -U username your_database_name > backup.sql

Replace username with your PostgreSQL username and your_database_name with your actual database name.

Automate the Process: Again, you can use cron jobs to automate backups.

2. Backup Media Files

If your Django project involves file uploads, you also need to back up the media files (e.g., user-uploaded files, images).

2.1. Simple Backup with `rsync`

You can use rsync to copy the media files to another server or backup location:

Backup the media/ directory:

   rsync -avz /path/to/your/django/project/media/ /path/to/backup/location/media/

Automate the Process: Set up a cron job to automate this process on a regular basis.

3. Automating Database and Media Backup with Cron Jobs

To automate the backup process, you can create a cron job on your server to run the backup commands at specific intervals.

3.1. Set Up a Cron Job for Django Database Backup

Open the crontab file:

   crontab -e

Add a line to run the dumpdata command periodically (for example, every day at midnight):

   0 0 * * * /path/to/your/project/venv/bin/python /path/to/your/project/manage.py dumpdata > /path/to/backup/location/backup_$(date +\%Y\%m\%d).json

This command will back up the database every day at midnight, and the backup file will be named with the current date (e.g., backup_20250408.json).

3.2. Set Up a Cron Job for Media Backup

You can also back up the media files periodically using rsync. Add the following line to the crontab:

0 1 * * * rsync -avz /path/to/your/django/project/media/ /path/to/backup/location/media/

This will back up the media/ directory every day at 1:00 AM.

4. Using Django Packages for Backup

There are also third-party Django packages available for backing up data and media files. Some popular ones are:

4.1. Django Database Backup Package

Django DB Backup is a simple Django app that can back up both the database and media files. It supports different databases and file storage systems.

To use django-db-backup:

Install the package:

   pip install django-db-backup

Add 'django_dbbackup' to your INSTALLED_APPS in settings.py.
Set up the backup location in your settings.py:

   DBBACKUP_STORAGE = 'django.core.files.storage.FileSystemStorage'
   DBBACKUP_STORAGE_OPTIONS = {'location': '/path/to/backup/location'}

You can now run the backup command:

   python manage.py dbbackup

5. Storing Backups Offsite (Cloud Storage)

For added safety, you can store your backups in cloud storage such as AWS S3, Google Cloud Storage, or Dropbox.

5.1. Use `django-storages` for Cloud Storage

You can integrate AWS S3 with Django using the django-storages package:

Install the package:

   pip install django-storages

In your settings.py, configure the storage backend:

   INSTALLED_APPS = [
       ...
       'storages',
       ...
   ]

   AWS_ACCESS_KEY_ID = 'your_access_key_id'
   AWS_SECRET_ACCESS_KEY = 'your_secret_access_key'
   AWS_STORAGE_BUCKET_NAME = 'your_bucket_name'
   AWS_S3_REGION_NAME = 'your_region'

   DEFAULT_FILE_STORAGE = 'storages.backends.s3boto3.S3Boto3Storage'

Once configured, you can upload media files to AWS S3 and back up files directly to the cloud.

6. Restoring Data

To restore a database backup, use loaddata for Django's dumpdata backup:

python manage.py loaddata backup_20250408.json

To restore a MySQL backup, use mysql:

mysql -u username -p your_database_name < backup.sql

For PostgreSQL, use pg_restore:

pg_restore -U username -d your_database_name backup.sql

For media files, you can use rsync to restore from the backup location.

Conclusion

To back up your Django project:

Database backup can be done using Django's dumpdata, mysqldump, or pg_dump.
Media files can be backed up using rsync.
Automate these backups using cron jobs.
Use third-party packages like django-db-backup for added convenience.
For cloud storage, use django-storages with services like AWS S3.

A Deep Dive into VLSI: The Backbone of Modern Electronics

David Njoroge — Thu, 13 Feb 2025 02:35:26 +0000

Lately, I’ve been diving deep into the world of VLSI (Very Large Scale Integration), and it has completely captured my mind. As someone passionate about cutting-edge technology, I find the idea of cramming millions (or even billions) of transistors onto a single silicon chip absolutely fascinating. From powering our smartphones to enabling AI and autonomous vehicles, VLSI is the invisible force driving modern innovation.

This blog explores VLSI in-depth—its evolution, design process, applications, challenges, and the exciting future ahead. If you’re curious about how the smallest circuits make the biggest impact, let’s dive in! 🚀

Introduction to VLSI

Very Large Scale Integration (VLSI) is a revolutionary technology that has transformed the world of electronics. It refers to the process of integrating millions (or even billions) of transistors onto a single silicon chip. This technology is the foundation of modern computing devices, enabling the creation of compact, efficient, and high-performance processors, memory units, and various digital circuits.

VLSI is an integral part of industries such as consumer electronics, telecommunications, healthcare, automotive, and artificial intelligence. In this blog, we’ll explore VLSI in-depth, covering its evolution, design process, applications, and future trends.

The Evolution of VLSI

Early Developments: SSI and MSI

Before VLSI, semiconductor technology underwent several phases:

Small Scale Integration (SSI) (1950s-1960s): This era featured circuits containing a few transistors (up to 100) per chip. Basic logic gates and flip-flops were common.
Medium Scale Integration (MSI) (1960s-1970s): Chips in this phase contained hundreds of transistors, enabling the creation of counters, multiplexers, and adders.
Large Scale Integration (LSI) (1970s-1980s): The number of transistors per chip increased to thousands, leading to the development of microprocessors and memory chips.

VLSI and Beyond

By the 1980s, advancements in semiconductor fabrication and lithography led to the era of Very Large Scale Integration (VLSI), where millions of transistors could be integrated onto a single chip. The subsequent Ultra Large Scale Integration (ULSI) phase enabled billions of transistors, paving the way for powerful processors like Intel’s Core series and AMD’s Ryzen.

The VLSI Design Process

The VLSI design process follows a structured flow that includes multiple steps, from system specification to chip fabrication. It involves both front-end and back-end design methodologies.

1. Specification

This is the first step, where the overall functionality of the chip is defined based on requirements such as processing speed, power consumption, and area constraints.

2. Architectural Design

At this stage, engineers define the data paths, control units, and memory architecture of the chip. Choices made here affect the chip’s efficiency and performance.

3. RTL Design (Register Transfer Level)

Designers use hardware description languages (HDLs) like VHDL or Verilog to describe the chip’s functionality at the logical level. This is a crucial part of front-end design.

4. Functional Verification

Before proceeding to physical design, the RTL code is tested using simulation tools to ensure it meets design specifications. Formal verification and logic synthesis are performed to refine the design.

5. Physical Design (Backend)

The chip layout is created through:

Partitioning: Dividing the design into smaller blocks.
Floorplanning: Determining the placement of major functional units.
Placement & Routing: Connecting different components optimally.
Timing Analysis: Ensuring that signals reach their destinations on time.

6. Fabrication and Testing

Once the physical design is finalized, the mask preparation and photolithography processes are carried out in fabrication plants (fabs). After manufacturing, chips undergo rigorous testing (ATPG, DFT, and BIST) to detect defects before deployment.

Key Technologies in VLSI

1. CMOS (Complementary Metal-Oxide-Semiconductor) Technology

CMOS is the most widely used semiconductor technology in VLSI because of its low power consumption and high efficiency. It forms the foundation of microprocessors, memory units, and digital logic circuits.

2. FinFET and Advanced Transistor Architectures

Traditional planar transistors are being replaced by FinFET and Gate-All-Around (GAAFET) transistors to improve power efficiency and performance in modern processors.

3. EDA (Electronic Design Automation) Tools

VLSI design is powered by tools such as:

Cadence Virtuoso
Synopsys Design Compiler
Mentor Graphics (Siemens EDA) These tools assist in circuit simulation, layout design, and verification.

4. FPGA and ASIC

FPGA (Field-Programmable Gate Arrays): Reconfigurable chips used for prototyping and applications requiring flexibility.
ASIC (Application-Specific Integrated Circuits): Custom-designed chips for dedicated tasks, commonly used in smartphones and AI accelerators.

Applications of VLSI

VLSI is everywhere, enabling advancements in multiple domains:

1. Consumer Electronics

Smartphones, laptops, gaming consoles, and IoT devices rely on VLSI chips for processing power and efficiency.
Example: Apple’s A-series chips (A17 Bionic) are optimized using advanced VLSI techniques.

2. Artificial Intelligence & Machine Learning

AI accelerators such as Google’s TPU (Tensor Processing Unit) and NVIDIA’s GPUs are optimized through VLSI design for high-speed computations.

3. Automotive and IoT

ADAS (Advanced Driver Assistance Systems) and autonomous vehicles rely on VLSI-based processors for real-time decision-making.
IoT devices use low-power VLSI chips for efficient operation.

4. Medical Electronics

Implantable medical devices, such as pacemakers and hearing aids, incorporate power-efficient VLSI technology.
Medical imaging devices like MRI scanners use VLSI-based DSP (Digital Signal Processing) units.

Challenges in VLSI Design

Despite its benefits, VLSI faces several challenges:

Power Consumption: With billions of transistors on a single chip, managing power efficiency is a critical issue.
Fabrication Costs: Advanced nodes (e.g., 3nm, 5nm) require expensive fabrication plants, making chip development costly.
Design Complexity: As circuits become more complex, designing and verifying them require sophisticated algorithms and tools.
Heat Dissipation: High-performance processors generate significant heat, requiring efficient cooling solutions.
Security Risks: As chips become more connected, vulnerabilities like hardware Trojans and side-channel attacks pose serious security threats.

Future of VLSI

The future of VLSI is exciting, with innovations that will redefine technology:

1. Neuromorphic Computing

Inspired by the human brain, neuromorphic chips (e.g., IBM’s TrueNorth) aim to revolutionize AI with ultra-low power consumption.

2. Quantum Computing Integration

Research is ongoing to integrate quantum computing with VLSI, potentially leading to unprecedented computational power.

3. 3D ICs and Chiplets

Instead of traditional 2D layouts, 3D Integrated Circuits (3D ICs) and chiplets offer better performance and power efficiency.
AMD and Intel are adopting chiplet architectures for their latest processors.

4. Beyond Silicon: Graphene and Carbon Nanotubes

Silicon scaling is reaching its limits; graphene transistors and carbon nanotubes may replace silicon for faster and more energy-efficient chips.

Conclusion

VLSI is the foundation of modern electronics, driving advancements in computing, AI, IoT, healthcare, and beyond. As we push towards 3nm and beyond, the field continues to evolve, bringing more powerful, efficient, and compact chips. While challenges like power consumption and fabrication costs persist, innovations in AI, quantum computing, and beyond-silicon materials are set to shape the future of VLSI.

Whether you are an engineer, a student, or a tech enthusiast, understanding VLSI is crucial for navigating the future of technology. 🚀

What’s Next?

Are you interested in VLSI? Would you like to explore FPGA programming or ASIC design? Let’s discuss in the comments!

The Importance of Mentorship in Software Development: Finding and Being a Mentor

David Njoroge — Thu, 24 Oct 2024 21:14:19 +0000

In the fast-paced and constantly evolving world of software development, mentorship plays a critical role in both personal and professional growth. Whether you’re a beginner learning the ropes or a seasoned developer looking to give back, mentorship offers a unique opportunity for learning, career advancement, and community building.

In this blog, we’ll explore why mentorship is vital in the software development industry, the benefits it brings to both mentees and mentors, and how to find or become a mentor in today’s tech landscape.

Why Mentorship Matters in Software Development

Software development is more than just writing code; it’s a field that requires continuous learning, problem-solving, and adaptation. Mentorship provides a structured pathway to navigate these challenges and accelerate your growth.

Bridging the Knowledge Gap: The tech industry moves quickly, with new programming languages, frameworks, and methodologies emerging all the time. For newcomers, this can be overwhelming. A mentor can provide clarity and direction, offering insights that go beyond textbooks and online courses.
Career Guidance: Software development isn’t just about technical skills—career decisions, personal branding, and networking are equally important. A mentor can help guide you through job searches, promotions, and long-term career planning.
Confidence Building: For many developers, especially those just starting, imposter syndrome is real. Having a mentor to validate your skills, offer constructive feedback, and support your development helps build the confidence you need to tackle complex problems and take on larger roles.
Access to Networks: A mentor with industry experience often has an established network. They can introduce you to the right people, provide opportunities for collaboration, and offer guidance on how to grow your own professional circle.
Long-Term Learning: Mentorship is not just about solving immediate issues. It’s about learning how to learn and think critically in the long run. A good mentor doesn’t just provide answers—they encourage curiosity and continuous learning, crucial traits in a field where technology is always advancing.

Benefits of Being a Mentee

As a mentee, you gain access to someone else’s wealth of experience and knowledge, but the benefits go deeper than that:

Skill Acceleration: Learning from a mentor helps you avoid common pitfalls and fast-track your skill acquisition. You can leverage their experience to get unstuck when facing challenges.
Broader Perspective: Mentors can offer a fresh perspective on both coding and non-coding issues, allowing you to see a problem from different angles. This can lead to creative solutions that you might not have considered on your own.
Encouragement and Support: The path of a software developer can be lonely at times. Having someone to share ideas with and get feedback from makes the journey less intimidating and much more rewarding.
Accountability: Regular check-ins with a mentor keep you focused and accountable for your learning. This helps you stay on track with your goals, be they mastering a new framework, completing a project, or preparing for interviews.

Benefits of Being a Mentor

While mentees clearly benefit from guidance, being a mentor offers significant rewards too:

Sharpening Your Skills: Teaching and explaining complex topics forces you to revisit foundational knowledge, enhancing your own understanding. As you help others, you’ll find that your problem-solving and communication skills also improve.
Giving Back: Most successful developers have benefited from some form of guidance early in their careers. Mentoring offers an opportunity to pay it forward, contributing to the growth of the tech community.
Building Leadership Skills: Mentoring others strengthens your leadership abilities. You learn to coach, provide feedback, and manage relationships, all of which are valuable skills if you aim to transition into managerial or leadership roles.
Learning from Mentees: Mentorship is a two-way street. While you’re helping a mentee grow, you often learn from their fresh perspective, enthusiasm, and the unique challenges they face.

How to Find a Mentor in Software Development

Finding the right mentor can significantly shape your career, but it’s essential to approach it strategically.

Through Online Communities: Platforms like GitHub, Stack Overflow, and Reddit have thriving tech communities where experienced developers are often willing to offer advice. LinkedIn is also a valuable platform for networking with professionals in your desired field.
Join Developer Meetups and Conferences: Many cities have local developer meetups, hackathons, and tech events where you can connect with like-minded people. Attending these events can lead to organic mentorship relationships.
Utilize Workplace Resources: If you’re already working in tech, look for mentorship programs within your company or industry. Many organizations have formal programs or can facilitate informal mentor-mentee relationships.
Look for Open Source Opportunities: Contributing to open-source projects is a great way to meet experienced developers. By working together on real-world projects, you’ll naturally form relationships with more seasoned professionals who may become your mentors.
Be Proactive and Reach Out: If there’s someone whose work you admire, don’t hesitate to reach out via email or social media. When contacting potential mentors, be specific about why you’re reaching out and what you hope to gain from the relationship.

How to Become a Mentor

If you’re ready to guide others on their journey, here’s how you can start:

Offer Help in Communities: Actively participate in online developer forums, answer questions on Stack Overflow, or provide feedback in GitHub pull requests. These small acts of guidance can lead to deeper mentorship opportunities.
Speak at Events or Write Blogs: Share your knowledge with the community through speaking at meetups or writing technical blogs. This positions you as a resource and invites those seeking mentorship to approach you.
Join Formal Mentorship Programs: Many organizations, universities, and bootcamps offer structured mentorship programs. Volunteering in these programs allows you to share your expertise while helping to shape the next generation of developers.
Make Yourself Approachable: Whether it’s on social media, at work, or in online forums, make it clear that you’re open to mentoring. Share your experiences and be open about your willingness to help others grow.

Conclusion

Mentorship is a powerful tool in software development that fosters both personal and professional growth. Whether you’re seeking guidance or offering it, mentorship builds stronger communities, accelerates skill development, and creates long-lasting relationships. By finding the right mentor or becoming one yourself, you contribute not only to your own success but to the advancement of the tech industry as a whole. So, take that step—seek out or become a mentor and watch your impact unfold.

Developing an Expense Tracking App: A Case Study of Pocket Planner

David Njoroge — Thu, 24 Oct 2024 20:58:35 +0000

Introduction

Managing personal finances is a crucial skill in today’s fast-paced world, where tracking expenses and income efficiently can lead to better financial decisions. With this goal in mind, I set out to develop Pocket Planner, a user-friendly mobile application that helps individuals keep their personal finances organized. This blog explores the journey of creating Pocket Planner, a feature-rich expense tracking app. We'll discuss the development process, challenges faced, and key takeaways.

You can visit the official website of Pocket Planner to learn more about the app, check out the GitHub repository, or download the app for Android.

Project Overview

Pocket Planner is designed to be more than just a simple expense tracker. It offers a robust and intuitive solution for logging expenses, tracking income, setting monthly budgets, and visualizing financial data. Built with Kotlin Multiplatform, Pocket Planner runs seamlessly on both Android and iOS platforms. The app allows users to maintain complete control over their finances, even offline.

Key Features of Pocket Planner:

Expense and Income Tracking: Record daily expenses and log sources of income effortlessly.
Monthly Budgets: Set up a monthly budget to stay on track.
Interactive Data Visualization: View spending trends and income patterns through engaging charts.
Offline Functionality: Manage finances without an active internet connection.
Cross-Platform Availability: Works on both Android and iOS devices.

App Architecture

Pocket Planner was developed using a modular architecture and followed the Clean Architecture principles to ensure maintainability and scalability. The app implements the Model-View-Intent (MVI) pattern to create a reactive and predictable user interface.

Modular Architecture Breakdown:

Presentation Module: Contains UI-related components such as navigation, screens, and view models.
Navigation Module: Handles app navigation and dependency injection.
Theme Module: Manages colors, shapes, dimensions, and typography to ensure a consistent design across the app.
Core Module: Contains utility functions and network handling.
Data Module: Handles database operations using SQLDelight and provides access to repositories.
Domain Module: Contains business logic, models, and use cases for expenses and income.
Components Module: Houses reusable UI components like buttons, alert dialogs, and charts.
Test Module: Provides comprehensive unit tests for various app components and use cases.

The app's modular architecture not only ensures separation of concerns but also improves maintainability and scalability.

Technologies Used

During development, I utilized several cutting-edge technologies to ensure performance, scalability, and cross-platform compatibility. Here’s a breakdown:

Kotlin Multiplatform: Enabled development for both Android and iOS using a shared codebase.
SQLDelight: Managed database interactions in a type-safe manner, ensuring consistent data access and offline functionality.
Orbit Core (MVI): Used to implement the MVI pattern for reactive UI management.
Koin: A lightweight dependency injection framework.
Kotlinx Coroutines: Handled asynchronous tasks, ensuring smooth operation and user experience.
GitHub Actions: Automated continuous integration (CI), including running unit tests and enforcing coding standards.
Kotlinm-Charts: Provided a variety of charts for visualizing financial data in a user-friendly format.

Development Process

The Pocket Planner app was developed using the Agile software development methodology, which emphasizes iterative development, collaboration, and adaptability. Throughout the project, the team worked in sprints, with each sprint focusing on delivering specific features or improvements.

The Agile process allowed for continuous feedback from stakeholders and users, helping us to prioritize tasks based on real user needs and product goals. This iterative approach ensured that each phase—whether designing UI/UX, implementing new features, or testing functionality—was subject to ongoing review and enhancement.

Sprint Phases in the Agile Process:

Sprint 1: Core functionality and initial UI design. The focus was on setting up the basic project architecture, user authentication, and navigation.
Sprint 2: Budget and expense management, enabling the app to track expenses and log incomes.
Sprint 3: Integration of financial charts and data visualization using Kotlinm-Charts, ensuring the user could view their financial data interactively.
Sprint 4: Offline functionality and performance optimization. Focused on database synchronization using SQLDelight.
Sprint 5: Testing and deployment, refining features based on feedback from testers and preparing the app for production.

At the end of each sprint, we conducted sprint reviews, retrospectives, and adjusted priorities for the next cycle. This iterative process ensured we could adapt to changing requirements, provide incremental value to users, and maintain transparency in the development timeline.

Algorithms and Data Structures Used

During the development of Pocket Planner, I leveraged several key algorithms and data structures to optimize performance and ensure the app could handle large datasets and complex operations efficiently.

Algorithms:

Budget Allocation Algorithm: This algorithm dynamically calculates a user’s remaining budget by subtracting expenses from the total budget. It supports custom budgets per category and alerts users when they exceed their allocated budget. The algorithm optimizes performance by using caching techniques to minimize redundant recalculations.
Sorting Algorithms: Used primarily for sorting expense records, both by date and amount, ensuring users can view transactions in the order that suits them best.
Search Algorithm: Implemented a binary search to allow fast filtering and retrieval of specific financial transactions. The algorithm supports searches by category, date, and amount, ensuring swift access to the data users are most interested in.

Data Structures:

HashMap: Used extensively for storing category-based expense data, allowing for quick lookups and updates of expense records associated with a specific category.
ArrayList: Employed for maintaining ordered lists of expenses and incomes, ensuring smooth iteration and manipulation of financial data.
Graph Data Structure (For Charts): Leveraged to represent the user’s financial data in a graphical format, enabling smooth rendering of charts in the UI.
Queue: Used in asynchronous task management to ensure that background operations like data sync and caching are performed in a first-in, first-out (FIFO) manner.

By choosing the right algorithms and data structures, I was able to optimize the performance of Pocket Planner, allowing the app to handle large amounts of data smoothly and provide real-time updates to users.

Software Development Phases

As a Software Engineer, I approached the development of Pocket Planner not just as a software developer but with a focus on system design, scalability, and maintainability—skills crucial for building complex applications.

1. Requirement Gathering:

This phase involved identifying the key features the app needed to address user pain points. I conducted extensive user research, surveys, and competitor analysis to understand what users expected from a personal finance application. The main requirements included tracking expenses, logging income, setting budgets, and visualizing financial data.

2. System Design & Architecture:

After gathering the requirements, I designed the system architecture using Clean Architecture principles to ensure maintainability and scalability. The app was built with a multi-module structure, each module handling different responsibilities such as data management, UI rendering, and business logic. By implementing a modular architecture, I ensured that features could be easily extended or modified without affecting other parts of the app.

3. UI/UX Design:

Collaborating with a design team, I contributed to creating an intuitive, user-friendly UI that aligns with modern design standards. Using Jetpack Compose, the app’s UI components were designed to be responsive, customizable, and capable of handling diverse screen sizes across Android and iOS devices.

4. Development (Implementation):

The actual development was carried out in multiple sprints using Kotlin Multiplatform for cross-platform compatibility. The app followed the Model-View-Intent (MVI) pattern, ensuring predictable state management across UI and business logic layers. I implemented various features, including:

Expense tracking: Enabled users to record, edit, and categorize their expenses.
Income logging: Allowed users to record multiple sources of income.
Data visualization: Created interactive charts that let users explore their financial data.
Offline functionality: Using SQLDelight, the app stored financial data locally and synchronized it when the user came back online.

5. Testing:

Comprehensive testing was a critical part of the development process. I implemented unit tests for the core business logic and UI tests to verify the integrity of the app’s user interface. We used GitHub Actions for continuous integration, automatically running tests and ensuring code quality in every pull request.

Key testing areas:

Unit Testing: Validated the correctness of algorithms like budget calculation and data retrieval.
UI Testing: Ensured that the app worked seamlessly across different screen sizes and devices.
Performance Testing: Focused on ensuring the app could handle large datasets without lag or delay, especially when rendering charts and financial reports.

Challenges Faced

Developing Pocket Planner came with its own set of challenges:

Cross-Platform Development: Integrating a single codebase for both Android and iOS was complex. I had to account for platform-specific features, which required extensive testing and debugging.
State Management: Managing the app’s state using the MVI pattern posed challenges in synchronizing UI states across various components and ensuring reactive flows.
Database Synchronization: Implementing SQLDelight for offline functionality required careful handling of data consistency and synchronization across platforms.
UI Responsiveness: Ensuring that the charts and visualizations were responsive across various screen sizes and handled large datasets smoothly was a key challenge.

Key Takeaways & Achievements

Despite the challenges, Pocket Planner achieved several significant milestones:

Successful Cross-Platform Integration: Pocket Planner works seamlessly on both Android and iOS, providing a unified experience.
Comprehensive Testing: The use of unit tests, combined with GitHub Actions for continuous integration, ensured that the app remained stable and reliable throughout development.
Offline Functionality: Achieved full offline functionality, enabling users to track expenses and income without needing an internet connection.
Interactive Data Visualization: Developed user-friendly, interactive charts using Kotlinm-Charts, allowing users to visualize their financial data easily.
Scalable and Maintainable Architecture: The use of a modular, Clean Architecture ensures the app can scale in the future, with potential for adding new features or supporting more platforms.

Conclusion

The development of Pocket Planner was a comprehensive process beyond just writing code. As a Software Engineer, I applied best practices in system design, architecture, and performance optimization to create a feature-rich, scalable, and maintainable app. Utilizing Agile principles ensured that user feedback shaped the app iteratively, while a strong focus on testing guaranteed its reliability and performance across platforms.

If you're interested in learning more or exploring the codebase, you can visit the app's dedicated website or check out the GitHub repository.

Download the app here.

To contact me you can visit my website or though linkedln

By sharing my experience in developing Pocket Planner, I hope to inspire other developers to take on similar projects and approach them with a solid architectural foundation and thoughtful technology choices.

Forem: David Njoroge

UNDERSTANDING CLEAN ARCHITECTURE IN SOFTWARE DEVELOPMENT

Origins and Evolution of Clean Architecture

1. The Precursor Patterns

2. The Synthesis (2012)

3. The Shift Toward Domain-Driven Design (DDD)

The Core Reasoning

1. Separation of Concerns and Framework Independence

2. Protection of the Domain (Domain Integrity)

3. Testability Without Side Effects

4. Dependency Inversion

5. Long-term Velocity

Architectural Layers

1. Entities (The Domain Layer)

Comparison: Entities vs. Value Objects

Key Distinction in Clean Architecture

2. Use Cases (The Application Layer)

3. Interface Adapters

4. Frameworks and Drivers (The Infrastructure Layer)

Data Flow and Dependency Inversion

1. The Flow of Control vs. Dependency Direction

2. Dependency Inversion Principle (DIP)

3. Input and Output Ports

4. Data Transfer Objects (DTOs) vs. Domain Models

5. Crossing the Boundary: The Mapping Process

File Structure (Layer-Wise)

Layer-Wise Component Details

Domain Layer: Value Objects and Validation

Application Layer: Use Case Orchestration

Infrastructure Layer: The Implementation Detail

Presentation Layer: Data Transformation

Native Android (Kotlin) Clean Architecture File Structure

Domain Layer: Code Samples (Kotlin/Android)

1. Custom Domain Exceptions

2. Value Objects with Validation

3. Entities

4. Repository Interfaces (Ports)

5. Use Cases (Application-Specific Rules)

Key Implementation Principles in this Layer

Data Layer: Code Samples (Kotlin/Android with API)

1. Data Transfer Objects (DTOs)

2. Retrofit API Service

3. Data Mappers

4. Repository Implementation

Key Implementation Principles in this Layer

Presentation Layer: Code Samples (Kotlin/Android)

1. UI State Representation

2. ViewModel Implementation

3. UI Component (Jetpack Compose)

Key Implementation Principles in this Layer

Read More from the following blogs

The Power Saving Paradox (Part 2): WorkManager and CoroutineWorker

Mastering the WorkManager and CoroutineWorker: Surviving the Android Power State Machine

1. The Architecture: Why CoroutineWorker?

The Implementation

2. The Power State Dance: WakeLocks & Radio States

3. Constraints: The Negotiator

Breaking Down the Negotiator:

4. WorkManager vs. AlarmManager: The Great Debate

5. Guide: Do's and Don'ts for Kotlin Developers

DO:

DON'T:

6. Surviving OEM Aggression (Samsung/Xiaomi)

7. Testing Power States (ADB Mastery)

Force Doze Mode

Force Standby Buckets

8. Pro-Tips Checklist for the Senior Android Developer

The Bottom Line:

The Power Saving Paradox (Part 1): Architectural Constraints and the Engineering of Power Saving

1. Defining Power Saving: The System State Machine

A. The "Doze" State Machine (Deep Power Management)

B. App Standby Buckets (Hierarchical Prioritization)

2. How Power Saving Relates to the Developer: The "Death of Determinism"

The Problem of the "Tail State"

The Wakelock Battle

3. The Technical Conflict: Foreground vs. Background

Why this makes things complicated:

4. Hardware Interfacing: The Physical Cost of Code

Summary of Part 1

The Architectural Schism: Foreground vs. Background and the Evolution of Survival

The "Correct" Architecture: `CoroutineWorker`

1. Database Backup (using `pg_dump`, `mysqldump`, or Django's `dumpdata`)

1.1. Database Backup with Django’s `dumpdata` Command

1.2. MySQL Database Backup with `mysqldump`

1.3. PostgreSQL Database Backup with `pg_dump`