kotlin-project-modularization

name	kotlin-project-modularization
description	Use when designing, reviewing, or refactoring module boundaries in KMP or Android projects — feature, data, app, and common modules, dependency direction, visibility control, and granularity.
license	Apache-2.0
metadata	{"author":"Mariano Miani","version":"1.1.0"}

Kotlin Multiplatform Modularization

Provenance & vetting (astro-mobile). Imported from mmiani/kotlin-kmp-claude-agent-skills (skills/kotlin-project-modularization/SKILL.md), commit b73b7c1f8bad9c3068a619aa69d383d40809c248, Apache-2.0. Cherry-picked and vetted against the repo's locked conventions before landing — checked = upstream already complied, adapted = conflicting guidance was reworded to comply:

• ktfmt is the sole Kotlin formatter: checked — no conflict (no competing formatter recommended).
• No Detekt suppression baseline file and no source-level suppression annotations to silence findings: checked — no conflict.
• Sealed Result<T> (Success<T> / Error) for error handling: checked — no conflict (error model out of this skill's scope).
• Package layout: base package io.jitrapon.astro, organized by layer (data/, ui/): checked — no conflict (skill is package-structure-agnostic).
• UI stays out of the :shared module: adapted — §4 "Common or core modules" upstream listed a shared "UI/design system" as a common-module example; removed it, substituted non-UI examples, and added a note that platform UI stays out of shared Kotlin.

Use this skill when designing, reviewing, or refactoring module boundaries in a Kotlin Multiplatform project.

This skill is intentionally strict. Its purpose is to keep module boundaries meaningful, dependency direction clean, ownership clear, visibility tight, and project growth manageable.

Primary goals

The modularization strategy should optimize for:

• reusability
• strict visibility control
• scalability
• ownership
• encapsulation
• testability
• build performance
• clear app entry points
• separation of platform-specific dependencies from reusable code

Do not modularize only for aesthetics. Modularization should create clearer ownership and lower coupling.

---

Official defaults to prefer

Unless the codebase has a strong reason not to, prefer:

• modules with a clear purpose
• narrow public APIs
• hidden implementation details
• feature ownership that is easy to infer
• shared code extracted only when it is truly shared
• module boundaries that reduce coupling
• app modules as entry points
• feature modules aligned to screens or closely related flows
• data modules that expose repositories and hide data sources
• common/core modules only for code reused by many modules
• Kotlin/Java modules instead of Android modules where Android resources, assets, and manifest support are unnecessary

---

Benefits to review for

A modular design is stronger when it improves:

• Reusability: modules act as building blocks and can be reused across variants or apps
• Strict visibility control: internal details stay hidden outside the module
• Scalability: changes stay local instead of cascading widely
• Ownership: one team or person can clearly own a module
• Encapsulation: each module knows as little as possible about others
• Testability: logic can be tested in isolation
• Build time: Gradle can better leverage parallelism, caching, and incremental builds

If the proposed modularization does not improve at least some of these, be skeptical.

---

Module types to recognize

1. Data modules

A data module usually contains:

• repositories
• data sources
• model classes

Its primary responsibilities are:

• encapsulate all data and business logic of a certain domain
• expose the repository as the external API
• hide implementation details and data sources from the outside

Review expectations:

• repositories are the public surface
• data sources stay internal to the module
• data ownership is domain-oriented, not endpoint-oriented
• callers do not depend directly on local/remote sources

Flag as a concern when:

• a data module exposes transport or persistence details publicly
• repositories are thin pass-through wrappers
• multiple unrelated domains are bundled together without a good reason

2. Feature modules

A feature module is an isolated part of app functionality, usually a screen or a closely related flow.

Review expectations:

• a feature corresponds to a user-visible capability
• a feature module likely contains UI plus a ViewModel/state-holder
• feature modules depend on data modules
• feature ownership is obvious from the module name and content

Flag as a concern when:

• one feature is scattered across many unrelated modules
• feature modules contain unrelated cross-cutting concerns
• features depend on each other too directly and too broadly

3. App modules

App modules are application entry points.

Review expectations:

• app modules depend on feature modules
• app modules usually provide root navigation
• if multiple device types are targeted, separate app modules may be appropriate to isolate platform-specific dependencies

Flag as a concern when:

• app modules own feature business logic that should live lower
• platform-specific concerns are not separated where they should be
• app modules become oversized containers for unrelated code

4. Common or core modules

Common/core modules contain code that many modules reuse and do not represent one specific app layer by themselves.

Examples may include:

• analytics
• networking infrastructure
• shared domain models and validation

(Note for this project: a UI/design system is not a valid common-module example — UI here is platform-specific and stays out of the :shared module. The per-platform app modules own their UI; only platform-agnostic, non-UI code belongs in common/core.)

Review expectations:

• common modules exist because the code is genuinely reused
• they do not become dumping grounds
• their APIs stay focused and narrow

Flag as a concern when:

• core, common, or shared modules accumulate unrelated responsibilities
• code is moved into common modules too early
• common modules become backdoors that weaken feature boundaries

---

Review dimensions

1. Module purpose clarity

Check whether every module has a clear purpose.

Questions:

• Can the module be described in one sentence?
• Is the module organized around a domain, feature, platform entry point, or a clearly shared capability?
• Would a new developer understand why it exists?

Flag as a concern when:

• the module name is vague
• the module mixes several unrelated purposes
• boundaries are justified only by folder convenience

2. Dependency direction

Check whether dependencies flow in a clean direction.

Prefer:

• app modules -> feature modules -> data/common modules
• feature modules depending on data modules, not vice versa
• shared infrastructure dependencies flowing inward without creating feature coupling

Flag as a concern when:

• feature modules depend on each other cyclically
• lower-level modules depend on UI or app modules
• module relationships are unclear or brittle

3. Visibility control

Use module boundaries to hide internals aggressively.

Check whether:

• implementation details are not publicly exposed without reason
• internal or private visibility is used appropriately
• only the intended API of the module is consumable

Flag as a concern when:

• everything is public by default
• repositories, data sources, mappers, and internals all leak outward
• module boundaries exist but do not enforce encapsulation

4. Granularity

Granularity must be intentional.

The Android modularization guide (https://developer.android.com/topic/modularization) identifies these pitfalls:

• too fine-grained: too much overhead, build complexity, and boilerplate
• too coarse-grained: modules become mini-monoliths and lose modular benefits
• too complex: modularization overhead outweighs benefits for the size of the project

Check whether:

• the number of modules matches the size and complexity of the codebase
• splitting adds clarity rather than ceremony
• module count is justified by ownership, reuse, or coupling reduction

Flag as a concern when:

• module count explodes without real boundary value
• large modules still contain many unrelated features
• the build becomes harder to reason about than the code itself

5. Feature ownership cohesion

Check whether a feature mostly lives in its owning module(s).

Prefer:

• feature UI, state-holder logic, and feature coordination staying together
• dependencies on shared modules only where they are actually shared
• modules that let feature work stay local

Flag as a concern when:

• feature implementation requires touching many unrelated modules
• feature ownership is hidden by broad technical slicing
• multiple modules partially own the same feature with no clear leader

6. Data ownership cohesion

Check whether data domains are modularized coherently.

Prefer:

• data modules aligned to meaningful domains
• repositories as the public API
• data sources hidden internally

Flag as a concern when:

• every endpoint gets its own module without domain cohesion
• data modules expose source internals
• the same domain logic is split across several modules arbitrarily

7. Common-module discipline

Common modules should reduce redundancy, not centralize chaos.

Check whether:

• common modules are truly reused by multiple consumers
• the module API is stable and small
• feature-specific code is not prematurely generalized

Flag as a concern when:

• common modules become default homes for code with unclear ownership
• teams use common modules to avoid choosing proper feature ownership
• changes to one feature require unrelated common-module edits

8. App-entry-point discipline

App modules should act as entry points.

Check whether:

• root navigation lives in app modules or a clearly designated top-level integration layer
• app modules compose features instead of owning their internal business logic
• device-specific entry points are separated when the project targets multiple device types

Flag as a concern when:

• app modules become giant orchestration layers for all business logic
• platform/device concerns are mixed in a single entry point despite differing requirements

9. Build and dependency hygiene

Check whether the module graph supports maintainability and build performance.

Prefer:

• implementation by default unless public API exposure is required
• fewer unnecessary transitive exposures
• module boundaries that support isolated rebuilds and isolated tests

Flag as a concern when:

• api is overused
• implementation details leak through public dependency surfaces
• the module graph forces many rebuilds for small changes

10. Prefer the lightest correct module type

Android library modules add overhead because they carry resources, assets, manifest, and AGP compilation. Use the lightest module type that correctly models the code's role:

• KMP multiplatform library modules (kotlin("multiplatform") plugin): the correct vehicle for shared KMP code targeting multiple platforms (Android, iOS, desktop, web). Not the same as a plain JVM or Android module.
• Plain Kotlin/JVM modules (kotlin("jvm")): suitable for pure JVM logic with no Android or multiplatform needs (e.g., a build-logic module or a server-side module in the same build).
• Android library modules (com.android.library): reserved for code that genuinely needs Android resources, assets, or manifest support and is not shared to non-Android targets.
• Android application modules (com.android.application): app entry points only.

Check whether:

• KMP shared code uses the kotlin("multiplatform") plugin, not the Android library plugin
• Android library modules are reserved for code that actually needs Android-specific packaging
• plain Kotlin/JVM modules are used where neither Android packaging nor multiplatform targeting is required
• the module type choice is intentional rather than defaulted

Flag as a concern when:

• Android library modules are used by default for logic that could live in a KMP multiplatform module
• shared KMP logic is placed in Android-only modules without a clear reason
• the build overhead (resources, manifest, AGP) does not match the module's actual role

11. Testability as a modularization outcome

Check whether modularization improves isolated testing.

Prefer:

• module APIs that can be faked or mocked cleanly
• business logic isolated away from app entry points
• tests that can run at module scope instead of only at app scope

Flag as a concern when:

• modularization does not improve isolation
• critical flows still require app-wide integration tests for simple validation
• module contracts are too broad or unclear to test well

---

Severity framework

High severity

Likely to cause structural problems.

Examples:

• cyclic dependencies
• modules with no clear purpose
• app modules containing feature/business internals
• data modules exposing data-source internals
• common modules acting as dumping grounds

Medium severity

Workable, but likely to add maintenance cost.

Examples:

• granularity slightly too fine or too coarse
• overuse of api
• weak ownership boundaries
• feature logic spread across too many modules
• Android modules used where plain Kotlin modules would suffice

Low severity

Structurally acceptable but worth improving.

Examples:

• naming obscures intent
• a common module could be split later
• a feature boundary is slightly awkward but still understandable

---

Required output format

When performing the review, respond with:

1. Modularization summary

   • current module types
   • dependency direction
   • entry-point modules
   • shared/common modules

2. What is structurally sound

   • concrete strengths only

3. Issues by review dimension

   • module purpose
   • dependency direction
   • visibility control
   • granularity
   • feature ownership
   • data ownership
   • common-module discipline
   • app-entry-point discipline
   • build/dependency hygiene
   • Android vs plain Kotlin module choice
   • testability

4. Severity for each issue

   • high / medium / low

5. Concrete recommendations

   • exact module moves or merges
   • which modules should split or consolidate
   • which APIs should become internal
   • where dependency direction should change
   • where a plain Kotlin module should replace an Android module

6. Suggested target structure

   • proposed module graph if useful

7. Open risks

   • migration cost
   • build impact
   • rollout and compatibility concerns

---

Tone

Be direct and practical. Do not praise modularization just because many modules exist. If the modularization is weak, say why clearly.

---

Anti-patterns to flag aggressively

• cyclic dependencies
• modules with unclear purpose
• too-fine-grained modules that add overhead without stronger boundaries
• too-coarse-grained modules that behave like mini-monoliths
• common/core/shared dumping grounds
• data modules exposing data sources publicly
• feature modules depending broadly on other feature modules
• app modules owning feature internals
• overuse of api
• Android library modules used when KMP multiplatform library modules or plain Kotlin modules would suffice

---

References

• Android modularization guide: https://developer.android.com/topic/modularization
• Android modularization patterns: https://developer.android.com/topic/modularization/patterns
• Kotlin Multiplatform DSL reference: https://www.jetbrains.com/help/kotlin-multiplatform-dev/multiplatform-dsl-reference.html