Arquitetura Frontend (portátil, baseada em módulos)

Quando Usar

Use esta habilidade quando precisar de um estilo de arquitetura portátil e independente de framework para qualquer frontend React ou React Native. Organiza aplicativos em módulos de funcionalidades com diretórios de páginas/telas, uma divisão estrita entre estado do servidor e estado da UI, importações entre módulos apenas por "barrels" (arquivos de índice), estilos co-localizados e regras claras de promoção de componentes....

Habilidade portátil — legível por Claude Code, OpenCode, Codex, Cursor, Windsurf e outros. Esta habilidade descreve uma estrutura e um conjunto de regras, não uma biblioteca de componentes, uma biblioteca de estado ou um estilo visual. É deliberadamente global: o mesmo modelo de módulo/página/estado se aplica a Next.js (App Router), React + Vite (SPA), Remix e Expo / React Native, e funciona com qualquer pilha de gerenciamento de estado e estilização.

O objetivo: um codebase onde qualquer contribuidor possa responder instantaneamente a três perguntas — "onde este código está localizado?", "o que é permitido importar o quê?" e "isso é estado do servidor ou estado da UI?" — sem perguntar a ninguém. A estrutura torna as respostas óbvias.

0. As cinco ideias centrais

1. Módulos de funcionalidades dominam seu mundo. Cada funcionalidade é uma modules/{feature}/ pasta autônoma com suas próprias páginas, componentes, hooks, estado, tipos e um único "barrel" público.
2. Páginas/telas são diretórios, não arquivos. Uma rota é uma pasta que co-localiza seu componente, seus estilos e os componentes/hooks usados apenas por ela.
3. O estado é dividido por origem. Dados do servidor vivem em uma camada de consulta/cache. Estado da UI/cliente vive em um "store". Eles nunca se sobrepõem — independentemente das bibliotecas que você escolher.
4. Importações cruzam limites apenas através de "barrels". Acessar o interior de outro módulo é proibido; você importa de @/modules/{feature} e nada mais profundo.
5. O código é promovido, não pré-colocado. Ele começa o mais local possível e se move para fora apenas quando um segundo consumidor aparece.

Tudo abaixo é a aplicação mecânica dessas cinco ideias. Nada disso está atrelado a uma biblioteca específica — escolha sua pilha nas Seções 4 e 6.

1. Layout de diretórios

A forma é idêntica entre os frameworks; apenas a camada de roteamento acima difere (veja a Seção 7).

src/
├── app/ or routes/ or navigation/   ← framework routing layer (thin — see §7)
├── modules/                         ← feature modules (the heart of the app)
│   └── {feature}/
│       ├── index.ts                 ← PUBLIC BARREL — the only cross-module entry point
│       ├── README.md                ← what this module owns, its routes, its data deps
│       ├── components/              ← components reused by 2+ pages IN THIS MODULE
│       ├── pages/                   ← page/screen directories (one per route)
│       │   └── {page}/
│       │       ├── {page}.tsx               ← the page/screen component
│       │       ├── {page}.styles.ts         ← ALL styling for this page
│       │       ├── index.ts                 ← re-exports the page component
│       │       ├── components/              ← components used ONLY by this page
│       │       ├── hooks/                   ← hooks used ONLY by this page
│       │       ├── constants/
│       │       └── README.md                ← route, params, permissions, data deps
│       ├── hooks/                   ← data hooks (query/mutation) + module hooks
│       ├── stores/                  ← UI/client state store(s) — never server data
│       ├── services/                ← data-access (API calls) for this feature
│       ├── utils/                   ← pure module utilities (co-located *.test.ts)
│       ├── constants/
│       └── types/                   ← module request/response + view-model types
└── shared/                          ← cross-module building blocks
    ├── components/                  ← components used by 2+ MODULES
    ├── hooks/                       ← cross-cutting hooks
    ├── api-client/                  ← one typed client; the only place that talks to the network
    ├── store/                       ← root store wiring (if your state lib needs one — see §4)
    ├── utils/                       ← formatters, cn()/clsx, helpers
    ├── constants/
    └── types/

Cada pasta que pode estar vazia no momento da criação mantém um .gitkeep para que a estrutura seja visível desde o primeiro dia.

2. Módulos de funcionalidades

Um módulo é uma fatia vertical do produto (por exemplo, auth, billing, dashboard, settings). Ele contém tudo o que a funcionalidade precisa e expõe uma superfície deliberadamente pequena.

…