🧪 Technical Deep Dive

Engineering Lab

Beyond shipping features — the systems that make teams fast and releases safe.

This section showcases engineering practices from my personal R&D project: a Kotlin Multiplatform library with native iOS and Android consumers, comprehensive CI/CD automation, and quality infrastructure.

1. Architecture (KMP) 2. CI/CD & Automation 3. Quality Gates 4. SDK Distribution 5. Documentation 6. Knowledge Tree
Section 1: Architecture

One Library, Two Platforms

Clean Architecture core implemented in Kotlin Multiplatform (shared/), consumed natively by iOS (Swift / SwiftUI) and Android (Jetpack Compose).

📦 shared/ (Kotlin Multiplatform Core) commonMain / androidMain / iosMain
Domain
UseCases · Models · Konform Validation
Data
Repositories · Ktor HTTP · Settings Storage
Presentation
ViewModels · StateFlow · SKIE Bridge
↓ Maven (GitHub Packages)
↓ XCFramework (SPM)
🤖 Android App (androidApp)
Jetpack Compose · Material 3 · Gradle KTS
🍎 iOS App (iosApp)
Swift / SwiftUI · XcodeGen Modular Targets

Clean Architecture Layers:

  • Domain: Use cases, business models, validation (Konform). Pure Kotlin with zero platform or framework dependencies.
  • Data: Repositories, DTOs, API services (Ktor), local storage (Multiplatform Settings).
  • Presentation: ViewModels exposing reactive state models to native UI consumers.

Key Design Decisions:

  • Business logic lives in shared/ — written once, tested once, consumed by both platforms.
  • SKIE enhances Swift interop (Kotlin coroutines become native Swift async/await, sealed classes become Swift enum with associated values).
  • Koin for dependency injection with KSP annotation processing.
  • iOS consumes via XCFramework (SPM), Android via Maven (GitHub Packages).

Module Structure (iOS side):

Generated deterministically via XcodeGen from YAML configuration — no merge conflicts or noisy .xcodeproj in version control:

iosApp/
├── NurKit/       → Core business logic, DI, services
├── NurUIKit/     → UI components & design system
├── NurCommsKit/ → Network & API layer
└── App/         → Main application target root
Section 2: Automation

40+ Workflows, One Command to Rule Them

Automated end-to-end pull request verification and release pipelines orchestrated by GitHub Actions and self-hosted runner fleets.

Developer pushes Pull Request
↓
PR Orchestrator
Detects changed paths & routes to appropriate matrix
↓
[KMP] Quality Gate
Detekt · JVM Tests · ABI Validation
[iOS] Quality Gate
SwiftLint · Simulator Tests · SPM Build
[Android] Quality Gate
Gradle Check · Compose Lint · AAR
↓
Results → Automated PR Comment + Slack Notification

3-Tier Makefile Hierarchy:

Makefile

Root dispatcher routing to platform-specific Makefiles

Makefile.kmp

KMP dev local & library deployment (50+ targets)

iosApp/Makefile

iOS build, test, and release automation

# One command to build, tag, and publish library to both platforms
make -f Makefile.kmp deploy_library VERSION=1.2.3

# Output:
# [✓] Package.swift updated to release mode (URL + Checksum)
# [✓] iOS XCFramework built (Debug + Release)
# [✓] Android AAR built & published to GitHub Packages
# [✓] Git tag v1.2.3 created & pushed to origin
# [✓] Release pipeline successfully completed!

Self-Hosted Runners:

  • Migrated from expensive GitHub-hosted macOS runners to dedicated Apple Silicon self-hosted nodes.
  • Significant cost reduction while achieving sub-minute Xcode test execution.
  • Cross-hosted variants (xh_ prefixed) for maximum execution flexibility across macOS, Linux, and Windows.

GitHub Actions Highlights:

  • PR Orchestrator auto-routes PRs to correct quality gates based on modified directories.
  • Auto-assign reviewers based on modified paths using CODEOWNERS.
  • Automated changelog generation adhering to Conventional Commits.
  • Slack notifications with test coverage and lint violation summaries.
  • Stale branch cleanup and automated secret rotation checks.
Section 3: Reliability

Every PR Earns Its Merge

A deterministic quality gate running automatically on every pull request to enforce zero regression, binary compatibility, and code safety.

✓
SwiftLint

iOS code style, concurrency checking & formatting

✓
Detekt

Kotlin static analysis with type-resolution & complexity rules

✓
Semgrep SAST

Security scanning & vulnerability detection on PR diffs

✓
ABI Validation

Binary compatibility check against public API breaks

✓
Unit Tests (JVM + Simulator)

Automated test suite across Android JVM and iOS Simulator

✓
Kover Coverage

Code coverage metrics with configurable threshold gates

✓
License Compliance

Automated dependency license allowlist validation

✓
PR Title Lint & Size Guard

Conventional Commits enforcement & mega-PR prevention

🛡 ABI Validation (The One Most People Miss)

Uses Kotlin 2.2.x built-in abiValidation to detect accidental breaking changes to the public API surface. Dump files are committed to shared/api/ — any modifications require explicit updateLegacyAbi, preventing consumers from breaking silently.

🔒 Semgrep SAST & Coverage Strategy

Runs security-focused static analysis on every PR with results posted directly as GitHub annotations. Coverage is measured with Kover with a clear philosophy: prioritize sustained >99% crash-free rate first, then scale coverage gates iteratively.

Section 4: Distribution

Ship a Library, Not a Monolith

Seamless dual-platform distribution allowing iOS engineers to consume pure Swift Package Manager targets while Android engineers consume Maven artifacts.

shared/ module (Kotlin Multiplatform)
↓
🍎 iOS: XCFramework + SPM
Package.swift binaryTarget
🤖 Android: Maven Packages
Published to GitHub Packages
↓
GitHub Release
ZIP archive + SHA-256 Checksum
GitHub Packages Repository
Standard Gradle dependency

Automated Release Pipeline:

Release Automation Pipeline
# Single command does everything:
# 1. Switches Package.swift to release mode
# 2. Builds XCFramework (debug + release)
# 3. Builds Android AAR & publishes to GitHub Packages
# 4. Commits, tags, and creates GitHub Release with checksum
$ make -f Makefile.kmp deploy_library VERSION=1.2.3

Semantic Versioning: Strict SemVer (x.y.z) with auto-increment support: make -f Makefile.kmp deploy_library_bump BUMP=minor. Versions are automatically suggested from Conventional Commit headers.

Section 5 & 6: Developer Experience

If It's Not Written Down, It Doesn't Exist

Every engineering decision, architecture pattern, and CI/CD process is formally documented. New team members can onboard from documentation alone.

📁 Documentations/ — Click any folder to expand/collapse 17+ Technical Guides
▶ 📱 ios/
IOS_ARCHITECTURE_MODES.md How the app switches between local dev & release mode
IOS_NATIVE_ARCHITECTURE.md Modular architecture design (XcodeGen targets)
RUN_SIMULATOR_FROM_CLI.md Developer tooling & headless simulator CLI
support/IOS_DEPENDENCY_INJECTION.md DI patterns & Koin setup
support/IOS_SONARQUBE_GUIDE.md Static analysis integration
uat/UAT_IOS_NATIVE_CICD_*.md User acceptance testing for CI/CD
▶ 🧠 kmp/
KMP_ARCHITECTURE_GUIDE.md Shared module architecture overview
technical/DEPLOY_LIBRARY_GUIDE.md Step-by-step library release process
technical/UNIT_TESTING_GUIDE.md Testing strategy & patterns
technical/DETEKT_RULES_POLICY.md Lint rules & rationale
technical/LICENSE_COMPLIANCE_GUIDE.md Third-party license management
technical/API_DOCS_GUIDE.md Dokka API documentation setup
technical/UAT_GUIDE.md UAT checklist for KMP module
▶ ⚙️ ci/
PR_CI_FLOW.md Full PR pipeline flow documentation
▶ 🏗 infra/
SELF_HOSTED_RUNNER_SETUP_MAC.md macOS Apple Silicon runner provisioning
SELF_HOSTED_RUNNER_SETUP_WINDOWS.md Windows runner provisioning
▶ 📖 general/
CONSUME_LIBRARY_GUIDE.md How consumers integrate the library
SEMANTIC_VERSIONING_GUIDE.md Versioning policy & conventions
CICD_AI_AND_QA_TOOLS_RESEARCH.md Research on tooling decisions
TOKEN_OPTIMIZATION_TOOLS.md Context window optimization research

How Documentation Maps to Engineering Lab Sections:

Lab Section Documentation Source
Architecture ios/IOS_NATIVE_ARCHITECTURE.md, kmp/KMP_ARCHITECTURE_GUIDE.md
CI/CD & Automation ci/PR_CI_FLOW.md, infra/SELF_HOSTED_RUNNER_*.md
Quality Gates kmp/technical/DETEKT_RULES_POLICY.md, kmp/technical/LICENSE_COMPLIANCE_GUIDE.md
SDK Distribution kmp/technical/DEPLOY_LIBRARY_GUIDE.md, general/CONSUME_LIBRARY_GUIDE.md
Testing & Verification kmp/technical/UNIT_TESTING_GUIDE.md, kmp/technical/UAT_GUIDE.md

These systems power the production apps in my Work section → See Shipped Apps

Questions about any of this? Let's talk.

Whether you want to discuss Swift Concurrency, KMP tradeoffs, or CI/CD runner architecture, I'd love to connect.

Get in Touch →