Clean Architecture Stack

Una arquitectura opinada y consistente para construir apps React, React Native y librerías npm mantenibles, basada en MVVM + MobX + Inversify + Clean Architecture.

Clean Architecture Stack — capas concéntricas

¿Qué es esto?

Este repositorio es la documentación de una arquitectura que he venido refinando en proyectos React y React Native. No es un framework, no es un paquete npm, no es un boilerplate. Es un conjunto de reglas, convenciones y plantillas que cualquier desarrollador (o LLM, ver más abajo) puede leer y aplicar para escribir código mantenible, testeable y consistente.

Encontrarás aquí:

• Filosofía (docs/00-philosophy.md) — los principios rectores que motivan cada decisión.
• Skills (skills/) — archivos .md con instrucciones precisas, diseñados para que tanto humanos como asistentes de IA (Claude, Cursor, Copilot) los consuman y generen código que cumpla las reglas.
• ADRs (docs/02-decision-records/) — registros de decisiones de arquitectura que explican el "por qué" detrás de cada elección.
• Ejemplos (examples/) — snippets canónicos de cada pieza (ViewModel, UseCase, Entity, Repository, DI bindings).

¿Por qué otra arquitectura?

El ecosistema React actual está dominado por hooks, Zustand/Jotai, server components y patrones funcionales. Son excelentes para muchos casos. Esta arquitectura no compite con ellos en su terreno: compite cuando:

• El dominio del negocio es rico (no eres un wrapper de un CRUD).
• El equipo es mediano o grande (3+ desarrolladores).
• El código va a vivir años y va a ser tocado por gente que no estuvo en su diseño original.
• Quieres que agregar una feature siempre se sienta igual, sin importar quién la escriba.

En esos contextos, la disciplina de capas + DI + ViewModels rinde mucho más que un montón de hooks compartidos. Si tu app es un dashboard de 5 pantallas con 2 endpoints, esto es overkill — usa Zustand y sigue tu camino.

Cuándo SÍ usar esto / Cuándo NO

Más detalle en docs/04-when-not-to-use.md.

Tour rápido (5 min)

Vamos a ver el flujo completo de "agregar un cliente", de la pantalla hasta la API.

sequenceDiagram
    participant S as ClientsScreen
    participant ViewModel as ClientsViewModel
    participant UC as GetAllClientUseCase
    participant R as ClientRepository
    participant API as REST API

    S->>ViewModel: viewModel.loadAll()
    ViewModel->>ViewModel: updateLoadingState(true)
    ViewModel->>UC: uc.run()
    UC->>R: repo.getAll()
    R->>API: GET /clients
    API-->>R: ClientModel[]
    R->>R: models.map(m => m.toDomain())
    R-->>UC: Client[]
    UC-->>ViewModel: Client[]
    ViewModel->>ViewModel: runInAction(() => isItemsResponse = data)
    ViewModel->>ViewModel: updateLoadingState(false)
    ViewModel-->>S: re-render (observer)

1. La pantalla solo bindea inputs y llama a la ViewModel

// src/ui/screens/Clients/ClientsScreen.tsx
const ClientsScreen = observer(() => {
  const viewModel = useViewModel<ClientsViewModel>(TYPES.ClientsViewModel);

  useEffect(() => { viewModel.loadAll(); }, [viewModel]);

  return (
    <SafeAreaView>
      {viewModel.isClientsLoading && <Spinner />}
      {viewModel.isClientsError && <Text>{viewModel.isClientsError}</Text>}
      <FlatList data={viewModel.isClientsResponse} ... />
      <PrimaryButton label="Agregar" onPress={() => viewModel.create(formValues)} />
    </SafeAreaView>
  );
});

2. La ViewModel orquesta estado y delega en UseCases

// src/ui/screens/Clients/ClientsViewModel.ts
@injectable()
export class ClientsViewModel {
  isClientsLoading = false;
  isClientsError: string | null = null;
  isClientsResponse: Client[] | null = null;

  constructor(
    @inject(TYPES.GetAllClientUseCase) private getAll: GetAllClientUseCase,
    @inject(TYPES.CreateClientUseCase) private createUC: CreateClientUseCase,
  ) {
    makeAutoObservable(this);
  }

  async loadAll() {
    this.updateLoadingState(true, null, 'items');
    try {
      const response = await this.getAll.run();
      runInAction(() => { this.isClientsResponse = response; });
      this.updateLoadingState(false, null, 'items');
    } catch (e) { this.handleError(e, 'items'); }
  }

  // ... updateLoadingState, handleError, create, etc.
}

3. El UseCase ejecuta UNA acción de negocio

// src/domain/useCases/GetAllClientUseCase/index.ts
@injectable()
export class GetAllClientUseCase implements UseCase<void, Client[]> {
  constructor(
    @inject(TYPES.ClientRepository) private repo: ClientRepository,
  ) {}

  async run(): Promise<Client[]> {
    return this.repo.getAll();
  }
}

4. La interfaz del repositorio vive en domain/

// src/domain/repositories/ClientRepository.ts
export interface ClientRepository {
  getAll(): Promise<Client[]>;
  create(client: Client): Promise<Client>;
  // ...
}

5. La implementación vive en data/ y mapea modelos a entidades

// src/data/repositories/ClientRepositoryImpl.ts
@injectable()
export class ClientRepositoryImpl implements ClientRepository {
  constructor(
    @inject(TYPES.ClientService) private service: ClientService,
  ) {}

  async getAll(): Promise<Client[]> {
    const models = await this.service.fetchAll();
    return models.map(m => m.toDomain());
  }
}

Eso es todo. Cualquier feature nueva sigue ese mismo flujo, escrito por cualquier persona del equipo, queda igual. Esa es la promesa.

Ver el flujo completo de archivos en examples/.

Las reglas no negociables

flowchart LR
    UI["🖥️ UI<br/>Screens + Components"]
    ViewModel["🧠 ViewModel<br/>(MobX + Inversify)"]
    UC["⚙️ UseCases<br/>(1 acción = 1 UC)"]
    REPO["📜 Repository<br/>Interface (domain)"]
    IMPL["🔌 Repository<br/>Impl (data)"]
    SVC["🌐 Service<br/>HTTP / Firebase"]

    UI --> ViewModel
    ViewModel --> UC
    UC --> REPO
    IMPL -.implements.-> REPO
    IMPL --> SVC

    style UI fill:#1A2F5E,stroke:#2D7EF8,color:#fff
    style ViewModel fill:#1A2F5E,stroke:#2D7EF8,color:#fff
    style UC fill:#0A1628,stroke:#2D7EF8,color:#fff
    style REPO fill:#0A1628,stroke:#2D7EF8,color:#fff
    style IMPL fill:#0A1628,stroke:#9B59B6,color:#fff
    style SVC fill:#0A1628,stroke:#9B59B6,color:#fff

1. UI depende solo del ViewModel. No importa data/, no importa Firebase, no importa axios.
2. ViewModel depende solo de UseCases. No conoce repositorios.
3. UseCases dependen solo de contratos del dominio (interfaces).
4. `domain/` no importa nada de framework ni infraestructura. Es portable.
5. Cada acción de negocio = un UseCase. Uno solo, en su propia carpeta.
6. Los modelos de transporte (DTOs) nunca llegan a la UI. Siempre mapeados a entidades del dominio.
7. Las ViewModels son UI-agnósticas. No tienen Alert, ni navigate, ni hooks, ni window.
8. Cada Screen vive en su propia carpeta con su ViewModel. src/ui/screens/<Feature>/<Feature>Screen.tsx y <Feature>ViewModel.ts, sin excepciones.
9. La Screen solo compone UI. Sin subcomponentes internos, sin transformación de datos, sin branching de negocio; los componentes privados van en components/.
10. Las constantes no viven en la Screen. Tokens visuales en src/ui/styles; configuración y opciones reusables en src/config.

Stack y decisiones

Cómo aplicarlo a tu proyecto

1. Lee este README completo y la filosofía detrás de las decisiones.
2. Revisa el Tour rápido y los ejemplos canónicos.
3. Consulta la skill que aplica a tu plataforma:

• React Native (Expo): skills/react-native/
• React web: _en Fase 2_
• npm package: _en Fase 2_

1. Para cada feature nueva, sigue el PR Checklist.

Más detalle en docs/01-getting-started.md.

Las skills (uso con LLMs)

Las skills en skills/ no son documentación pasiva. Están escritas como instrucciones ejecutables para asistentes de IA: si pegas el contenido de feature-scaffold-rn.md en Claude Projects, Cursor Rules, o un system prompt, el LLM va a generar features que cumplen estas reglas sin que tengas que repetirlas en cada prompt.

Todas siguen un formato canónico (frontmatter + secciones XML <purpose>/<when_to_use>/<rules>/<examples>/<output_format>/<see_also>) basado en las prácticas de prompt y context engineering de Anthropic. El estándar de formato y la convención para instalarlas y mantenerlas en cada proyecto (p.ej. .claude/skills/<name>/SKILL.md) viven en skill-authoring. Este repo es la fuente de verdad; los proyectos consumen copias y se resincronizan desde aquí.

FAQ rápido

¿Por qué MobX en 2026? Porque makeAutoObservable + clases es el match perfecto para MVVM y la ViewModel-as-class. Zustand es excelente, pero te empuja a un estilo funcional/hooks que choca con la disciplina de capas que buscamos. Detalle en ADR 001.

¿Inversify no es exagerado para React? Para una app pequeña, sí. Para apps con 20+ pantallas, decenas de UseCases y múltiples adaptadores de datos, Inversify se paga solo. Detalle en ADR 002.

¿Por qué `[key: string]: any` en entidades? Es una concesión consciente: privilegia velocidad de iteración con backends inestables sobre tipado exhaustivo. Detalle en ADR 003.

¿"1 acción = 1 UseCase" no genera explosión de archivos? En apps puramente CRUD, sí. En apps con dominio rico, esa explosión es _exactamente_ lo que da claridad. Detalle en ADR 004.

Más en docs/03-faq.md.

Roadmap

• ✅ Fase 1 — Skills RN + docs base + ADRs principales (este release)
• 🚧 Fase 2 — Skills React web + monorepo/npm package
• 🔭 Fase 3 — Skills Python (FastAPI + hexagonal)
• 🔭 Fase 4 — CLI generador de features (npx cas-cli new-feature Clients)

Detalle en ROADMAP.md. Historial de cambios en CHANGELOG.md.

Contribuir

Las skills evolucionan con el uso real. Si encuentras un caso que no cubren, una regla que choca con tu contexto, o un patrón mejor: abre un issue o PR. Ver CONTRIBUTING.md.

Licencia

MIT — ver LICENSE.

_Escrito por @Kevinparra535. Si esto te ayudó, deja una estrella ⭐ en el repo._