Arquitectura Estándar KMP Omni-Channel

Versión: 3.0.0 · Fecha: 2026-05-28 · Área: Arquitectura de Plataforma Omni-Channel (Mobile & Desktop)

Este repositorio contiene el blueprint arquitectónico estándar para proyectos Kotlin Multiplatform (KMP). El enfoque estratégico abarca el espectro Omni-Channel: Android, iOS y Desktop JVM, maximizando la reutilización de código (UI compartida y nativa) sin sacrificar la seguridad ni el performance.

Está organizado en documentos temáticos modulares. Lee solo lo que aplique a tu caso de uso.

---

⚖️ Principios que aplican siempre (Nuestro Contrato)

• La arquitectura sirve al equipo, no al revés. No agregues Clean Architecture si solo vas a pintar un listado simple de red.
• Single Source of Truth. La lógica core de negocio, reglas de negocio complejas y modelos de datos solo existen en KMP. Nunca se duplican en las vistas Swift/Kotlin.
• Fail Fast. Validar errores, biometría y reglas de negocio en la capa de dominio (Use Cases), no en los ViewModels.
• UI "Tonta". Los composables o vistas nativas solo reciben un State inmutable pre-calculado y emiten Intents/Eventos. No toman decisiones de enrutamiento ni de lógica.

---

🛑 Reglas MUST — Innegociables para todo proyecto KMP

Requisito	Estándar Obligatorio	Detalle y Justificación
JVM	Java 21 LTS	Optimización masiva en G1GC y ZGC Generacional, Virtual Threads.
Android Tooling	AGP 9.x	Soporte estricto de compilación y R8 de nueva generación.
Kotlin	2.3.x+ (2.4-EAP recomendado)	K2 Compiler por defecto, Swift Export nativo, Context Parameters.
Gradle	9.x (con parallel execution)	Caché de configuración y builds incrementales veloces. Compatible con AGP 9.
Seguridad	OWASP Mobile/Desktop Top 10	Crypto multi-plataforma (Keystore/Secure Enclave/Keychain).
Dependencias	libs.versions.toml	Fuente única de la verdad con gobierno automatizado en CI/CD.

📚 Leer más: must/toolchain.md | must/security.md | must/dependencies.md | must/performance.md

---

🛣️ Árbol de Decisión — Patrones y Arquitecturas

La arquitectura debe servir al equipo y al producto, no al revés. Evalúa tu escenario:

flowchart TD
    START{¿Qué tipo de proyecto es?} --> Q1{¿Plataformas objetivo?}
    
    Q1 -->|Solo Mobile| Q2{¿Tamaño y complejidad?}
    Q1 -->|Mobile + Desktop| CMP[Compose Multiplatform - Shared UI]
    Q1 -->|Solo Desktop JVM| DESK[KMP Desktop JVM]
    
    Q2 -->|Pantalla simple / MVP| MVVM[MVVM\narchitecture/mvvm.md]
    Q2 -->|Reglas de negocio complejas| CLEAN[Clean Architecture + MVI\narchitecture/clean-architecture.md]
    Q2 -->|Super App / Múltiples Equipos| MODULAR[Modular + Clean\narchitecture/modular.md]
    
    CMP --> CLEAN
    DESK --> CLEAN
    
    style MVVM fill:#10b981,color:#fff
    style CLEAN fill:#3b82f6,color:#fff
    style MODULAR fill:#f59e0b,color:#fff
    style CMP fill:#8b5cf6,color:#fff
    style DESK fill:#ef4444,color:#fff

Loading

📚 Leer Guía de Decisión Detallada: architecture/decision-guide.md

---

🗺️ ¿Por dónde empezar? (Guía de Onboarding)

Si eres nuevo en el equipo o recién llegas al mundo KMP, no intentes leer todos los documentos de golpe. Sigue este camino:

1. Lee los Principios (arriba) para entender la filosofía de nuestro equipo.
2. Revisa las Reglas MUST para saber qué versiones y reglas de seguridad no puedes violar.
3. Elige tu Caso de Uso en la sección 1. Casos de Uso (abajo) y úsalo como plantilla para tu proyecto.
4. Si tienes dudas sobre cómo armar la lógica, ve a 3. Patrones de Diseño KMP.

---

🗂️ Índice de Documentación

1. Casos de Uso y Plantillas (use-cases/)

Empieza por aquí según el tipo de aplicación que vayas a construir:

• 📱 Small App (1-3 devs)
• 🏦 Large App (Clean + Modular)
• 🏢 Super App (Equipos Distribuidos)
• 🖥️ Desktop App (JVM)

2. Fundamentos KMP & Estructura (kmp/)

• 🏗️ Estructura de Proyecto KMP 2026 (Nuevos SourceSets)
• 🌐 Networking & Contratos KMP
• 💾 Storage Seguro en KMP
• 🎨 CMP (UI Compartida) vs Nativa
• 🍎 Estrategia Swift Export 2026 🆕

3. Patrones de Diseño KMP (architecture/)

• 📐 Patrones GOF en KMP (Strategy, Factory, Adapter) 🆕
• 🏛️ Clean Architecture Multiplatform
• 🔄 MVI (Model-View-Intent) unificado
• 🧩 MVVM Clásico
• 📦 Arquitectura Modular
• 🧪 Estrategia de Testing & Mocking

4. Organización de Equipos (teams/)

• 👥 Equipos Distribuidos y Feature Libs
• 👤 Equipo Único
• 🚀 CI/CD (Firma, Promoción, Versionamiento)

---

🌟 Novedades Kotlin 2.3+ & KotlinConf '26

El ecosistema de desarrollo ha dado un salto gigante este año. Nuestra arquitectura se apoya fuertemente en estas nuevas capacidades:

• Context Parameters: Eliminan la necesidad de pasar dependencias implícitas (adiós al verboso dependency injection en scopes pequeños).
• Swift Export Nativo: Ya no usamos puentes Objective-C. Enums de Kotlin mapean a Enums de Swift, Structs, etc.
• Navigation 3 Multiplatform: Rutas tipadas integradas en todo el stack KMP.

---

Mantenido por el equipo de Arquitectura Omni-Channel. Las actualizaciones a los módulos core deben pasar por un proceso ADR (Architecture Decision Record).