Rn Architecture

React Native — Arquitetura

Objetivo

Aplicar uma arquitetura em camadas, testável e escalável para features React Native, com fluxo de dados previsível da fonte de dados à UI.

Quando utilizar

• Criar um módulo ou feature novo.
• Decidir onde colocar lógica (UI, estado, caso de uso, dados).
• Refatorar código com regra de negócio na UI ou chamada de API no componente.

Conhecimentos necessários

• Clean Architecture e a regra de dependência (dependências apontam para dentro).
• Padrões Repository, Use Case e Mapper/Helper.
• Injeção de dependência simples (construtor/factory).
• Diferença entre transformação de shape (mapper) e cálculo/estado (helper).

Fluxo de execução

1. Modele o contrato de dados: DTOs de entrada/saída e models de domínio.
2. Implemente o repositório: encapsula IO/HTTP e retorna resultado tipado (sucesso/erro), sem lançar exceção crua.
3. Implemente o caso de uso: orquestra repositório + mappers/helpers e retorna estado tipado ({ type: 'SUCCESS' | 'ERROR' }).
4. Exponha estado via store/hook que consome o caso de uso (nunca o repositório direto).
5. Conecte a UI por um hook de tela (use-*-screen); mantenha a tela fina.
6. Escreva testes por camada.

Tela → hook de tela → estado → caso de uso → repositório → cliente HTTP
                                   ↘ mappers / helpers ↗

Estrutura de pastas

Reflita as camadas na organização física. Os nomes são convenção — adapte ao seu projeto, preservando os papéis. Separe código de domínio (modules/) de código compartilhado (common/).

Módulo / feature

modules/{module}/
├── dtos/            ← contratos de dados da API (request/response)
├── models/          ← models de domínio
├── repositories/    ← acesso a dados/IO; retorna resultado tipado (sem exceção crua)
├── use-cases/       ← orquestra repositório + mappers/helpers (obrigatório)
├── mappers/         ← transformação de shape (DTO ↔ Model ↔ Request) — puro
├── helpers/         ← cálculos e transformações imutáveis de estado — puro
├── stores/          ← estado do módulo (slices por domínio)
├── hooks/           ← hooks de tela (use-*-screen) e reutilizáveis do módulo
├── ui/              ← componentes de UI do módulo (tokens/tema)
├── factories/       ← montagem/registro de telas e dependências
├── screens/         ← telas finas
└── index.ts         ← barrel público (API do módulo)

Toda ação de negócio/IO passa por use-cases/; mappers/ e helpers/ são puros, sem efeito colateral.

Camada comum (compartilhada)

Código reutilizável entre módulos e integrações globais. Os papéis importam mais que os nomes:

| Subdiretório | Conteúdo | |---|---| | ui | Componentes de UI reutilizáveis (design tokens/tema) | | hooks | Hooks compartilhados | | stores | Estado global (ex.: sessão, configurações) | | protocols | Contratos de HTTP/cliente, interceptors, auth/token | | repositories | Acesso a dados de serviços comuns | | providers | Providers globais (contextos) | | routes | Navegação (stacks, tabs, tipos de rota) | | configs | Configurações gerais (deep linking, refs de navegação, dev tools) | | database | Persistência local | | errors | Classes de erro e códigos | | constants | Valores estáveis e reutilizáveis | | factories | Factories compartilhadas (ex.: navigators, webviews) | | analytics | Integrações de analytics/telemetria | | system-design / theme | Design tokens, spacing, tipografia | | utils | Funções utilitárias genéricas |

Boas práticas

• Uma responsabilidade por camada; funções puras para regra de negócio.
• Módulos autocontidos; compartilhe via camada comum, não entre irmãos.
• Estado é fonte única da verdade; mutações apenas pela API do store.
• Barrel (index.ts) expõe a API pública do módulo.

Armadilhas comuns

• Chamar API/repositório direto do componente ou hook de tela.
• Pular a camada de caso de uso.
• Cálculo/transformação inline em store ou caso de uso.
• Dependências circulares entre módulos.

Critérios de sucesso

• Fluxo de dados segue a direção única acima.
• Regra de negócio isolada e testável sem UI.
• Trocar detalhe de IO/UI não afeta as regras.
• Cada camada tem teste próprio.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cmaranho
• Source: cmaranho/rn-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.