Visao Geral da Arquitetura

O docs/ARCHITECTURE.md no seu projeto e a fonte de verdade que todos os agentes seguem. Esta pagina resume os padroes principais.

Estrutura Modular

Cada funcionalidade e um modulo autocontido:

src/modules/[feature]/
├── components/     ← UI
├── composables/    ← Logica (service → adapter → query)
├── services/       ← HTTP puro (sem try/catch)
├── adapters/       ← Parsers (API ↔ App)
├── stores/         ← Apenas estado do cliente (Pinia)
├── types/          ← .types.ts (API) + .contracts.ts (App)
├── views/          ← Paginas
├── __tests__/      ← Testes
└── index.ts        ← Barrel export (API publica)

Regras de Importacao

• Modules → Shared: ✅ Permitido
• Modules → Modules: ❌ Nunca (mova o codigo compartilhado para shared/)
• App → Modules: ✅ Apenas router e registro

Arquitetura de Quatro Camadas

Camada	Faz	NAO Faz
Service	Chamadas HTTP	try/catch, transformacao, logica
Adapter	Parsear API ↔ App (snake_case → camelCase)	HTTP, efeitos colaterais
Composable	Orquestrar service + adapter + Vue Query	Renderizar UI
Pinia Store	Estado do cliente (UI, filtros, preferencias)	Estado do servidor, HTTP
Component	UI + composicao	Logica de negocio pesada

Exemplo de Fluxo de Dados

Veja o que acontece quando um usuario visita a pagina de Produtos:

Separacao de Gerenciamento de Estado

Pinia = Estado do cliente (UI, filtros, preferencias) Vue Query = Estado do servidor (dados da API, cache, atualizacao em segundo plano)

Convencoes de Nomenclatura

Arquivos

Tipo	Padrao	Exemplo
Diretorios	kebab-case	user-settings/
Componentes	PascalCase.vue	UserSettingsForm.vue
Views	PascalCase + View.vue	MarketplaceView.vue
Composables	use + PascalCase.ts	useMarketplaceList.ts
Services	kebab-case-service.ts	marketplace-service.ts
Adapters	kebab-case-adapter.ts	marketplace-adapter.ts
Stores	kebab-case-store.ts	marketplace-store.ts
Types	kebab-case.types.ts	marketplace.types.ts
Contracts	kebab-case.contracts.ts	marketplace.contracts.ts

Codigo

Tipo	Padrao	Exemplo
Variaveis / funcoes	camelCase	getUserById, isLoading
Types / Interfaces	PascalCase	UserProfile, MarketplaceItem
Constantes	UPPER_SNAKE_CASE	API_BASE_URL, MAX_RETRIES
Composables	use + PascalCase	useAuth, useMarketplaceList
Booleanos	is/has/can/should	isLoading, hasPermission
Event handlers	handle + acao	handleSubmit, handleDelete

Padroes Principais

• Pare o Prop Drilling: Use slots + provide/inject + composables diretos
• Utils vs Helpers: Utils = funcoes puras, Helpers = funcoes com efeitos colaterais
• Tratamento de Erros: Centralizado nos composables (Vue Query onError)
• SOLID no Vue: Cada arquivo = 1 responsabilidade

Mergulho Profundo

• Camadas — Exemplos detalhados de cada camada
• Componentes — Padroes e composicao de componentes
• Referencia completa: docs/ARCHITECTURE.md no seu projeto