MVP 1 - App - Foundation Layer

Atualizado: 2026-04-07

Objetivo

Formalizar a arquitetura canônica do auraxis-app antes da primeira feature nova de produto. O princípio central é: o app só destrava entrega funcional depois que runtime, contratos, shell, UI foundation, segurança, observabilidade e testabilidade estiverem suficientemente sólidos para sustentar o MVP 2 sem reabrir débito técnico estrutural.

Decisão executiva

O app mobile passa a operar com uma única arquitetura ativa:

• app/ para rotas e composição visual;
• core/ para runtime transversal;
• features/ para domínios de produto;
• shared/ para primitives, forms, tema, testing e contratos compartilhados.

Diretórios legados como components/, hooks/, lib/ e stores/ deixam de ser trilhas válidas para código novo. Durante a transição eles podem existir apenas como camada temporária de compatibilidade, até serem esvaziados e removidos.

Stack canônica do app

Camada	Escolha
Framework	Expo SDK 54
Navegação	Expo Router
UI	Tamagui + tema Auraxis
Server state	TanStack React Query
Client state	Zustand apenas em core/ para shell/sessão/runtime
HTTP	Axios via core/http/http-client.ts
Forms	React Hook Form + Zod
Segurança	expo-secure-store para sessão sensível
Observabilidade	Sentry + telemetria cliente mínima + /ops/* do backend
Build/release	EAS apenas quando o baseline operacional estiver fechado

Objetivos de qualidade

O target canônico do programa de fundação do app é elevar todos os eixos abaixo para >= 9.5:

• arquitetura;
• padrões e separação de responsabilidades;
• reaproveitamento;
• testabilidade;
• escalabilidade do código;
• segurança;
• confiabilidade;
• observabilidade;
• logging;
• DX;
• prontidão para receber novas features.

Arquitetura-alvo

Camadas

Camada	Responsabilidade	Regra
app/	rotas, layouts, composição visual por tela	não contém regra de negócio, HTTP nem store
core/	runtime transversal	sessão, shell, navegação, lifecycle, query, http, logging, telemetry
features/	domínio de produto	contracts, services, hooks, controllers, selectors e components de domínio
shared/	blocos reutilizáveis	primitives, forms, validators, theme, animations, testing e contracts globais

Fluxo de dados

app/route.tsx
  -> feature screen controller hook
    -> feature service
      -> core query/http/session/navigation/runtime
        -> auraxis-api

Regra para arquivos .tsx

Arquivos .tsx do diretório app/ devem conter apenas:

• composição visual;
• binding com props e handlers;
• wiring mínimo de navegação;
• consumo de controllers/hooks canônicos.

Tudo o que for:

• transformação de payload;
• regra de domínio;
• normalização de erro;
• orchestration de mutation/query;
• estado transitório relevante;
• decisão de fluxo;

deve morar em features/* ou core/*.

Estrutura canônica de diretórios

auraxis-app/
  app/
    (public)/
    (private)/
    _layout.tsx
    index.tsx
  core/
    http/
    navigation/
    providers/
    query/
    session/
    shell/
  features/
    auth/
    bootstrap/
    subscription/
    entitlements/
    dashboard/
    wallet/
    alerts/
    goals/
    observability/
    transactions/      # scaffold obrigatório
    shared-entries/    # scaffold obrigatório
    fiscal/            # scaffold obrigatório
    user-profile/      # scaffold obrigatório
    questionnaire/     # scaffold obrigatório
    tools/             # trilha canônica das ferramentas
  shared/
    animations/
    components/
    config/
    contracts/
    forms/
    mocks/
    testing/
    theme/
    types/
    validators/

Domínios obrigatórios antes da primeira feature nova

Domínio	Estado esperado
auth	pronto
bootstrap	pronto
subscription	pronto
entitlements	pronto
dashboard	pronto
wallet	pronto
alerts	pronto
goals	pronto
observability	pronto
transactions	scaffold obrigatório antes de feature
shared-entries	scaffold obrigatório antes de feature
fiscal	scaffold obrigatório antes de feature
user-profile	scaffold obrigatório antes de feature
questionnaire	scaffold obrigatório antes de feature
tools	migrado para trilha canônica

Contratos e integração com API

Fonte de verdade

O app deve consumir a API apenas por meio de:

• contracts/openapi.snapshot.json;
• shared/types/generated/openapi.ts;
• shared/contracts/api-endpoint-catalog.ts;
• shared/contracts/api-contract-map.ts.

Regras obrigatórias

• nenhum endpoint pode ser consumido por string solta fora do catálogo canônico;
• contracts:sync e contracts:check são gates bloqueantes;
• exemplos sensíveis do OpenAPI precisam passar por hygiene antes de serem versionados;
• toda integração nova deve nascer em features/<dominio>/services/* apoiada no apiContractMap.

Shell, sessão e runtime

O runtime canônico do app é sustentado por:

• core/session/session-store.ts;
• core/session/session-storage.ts;
• core/shell/use-app-startup.ts;
• core/shell/runtime-revalidation.ts;
• core/shell/use-runtime-lifecycle.ts;
• core/navigation/routes.ts;
• core/navigation/route-guards.ts;
• core/navigation/deep-linking.ts.

Regras obrigatórias de sessão

• sessão sensível só em expo-secure-store;
• refresh, expiração e falha de autenticação precisam ter política explícita;
• foreground revalidation deve ser centralizada em core/shell;
• retorno de checkout e deep links não podem depender de lógica ad hoc em tela.

UI foundation e composição visual

Direção

O app usa Tamagui como base canônica. Wrappers em shared/components devem encapsular as superfícies mais comuns:

• screen;
• stack;
• heading;
• surface card;
• button;
• input field;
• form message;
• async states;
• badges;
• skeletons;
• métricas e list items.

Regras obrigatórias

• código novo de produto não usa react-native-paper;
• telas de produto não devem usar StyleSheet.create, TextInput, TouchableOpacity ou Pressable cru fora de wrappers controlados;
• .tsx deve preferir AppScreen, AppSurfaceCard, AppButton, AppInputField, AsyncStateNotice e demais primitives canônicas.

Segurança

O app precisa operar com:

• tokens e sessão protegidos por expo-secure-store;
• Sentry com sendDefaultPii = false;
• redaction de erros e breadcrumbs sensíveis;
• runtime config distinguindo corretamente segredo real de EXPO_PUBLIC_*;
• observability export consumida como ferramenta operacional, nunca como segredo forte;
• guards de rota baseados em sessão e entitlement, não em UI state arbitrário.

Observabilidade e logging

Baseline obrigatória

O app deve ter:

• Sentry como error tracker único;
• logger cliente canônico com níveis e redaction;
• breadcrumbs de navegação, HTTP e lifecycle;
• instrumentação mínima de startup, sessão, deep link e retorno de checkout;
• consumo controlado de GET /ops/observability e GET /ops/metrics apenas para inspeção operacional e debug.

Meta

Antes da primeira feature nova, o app deve sair do estado atual de observabilidade rasa e atingir um baseline em que:

• erros silenciosos fiquem rastreáveis;
• regressões de lifecycle sejam reproduzíveis;
• falhas de rede e sessão tenham trilha suficiente para triagem.

Testabilidade

Regras obrigatórias

• shared/testing/test-providers.tsx deve isolar QueryClient por teste;
• cada domínio precisa de factories e mocks próprios;
• runtime e shell precisam de testes de erro e edge case, não só caso feliz;
• componentes shared devem ter testes das variantes principais;
• npm run quality-check continua sendo o gate local canônico.

Guardrails mínimos

• nenhum screen importando de @/lib/*, @/hooks/* ou @/stores/*;
• nenhum import ativo de endpoint fora do catálogo canônico;
• cobertura seletiva de fundação cobrindo runtime, contrato, sessão e navigation;
• hygiene checks locais para contratos, secrets e governança de frontend.

Anti-padrões proibidos

• lógica de negócio em app/*.tsx;
• chamadas HTTP diretas em componentes;
• any;
• strings de endpoint fora do catálogo;
• sessão fora de core/session;
• duplicação de estado entre screen local e store global sem justificativa;
• coexistência indefinida entre arquitetura nova e legado.

Programa de execução antes da primeira feature

Bloco	Objetivo
FND-03A	eliminar consumo ativo do legado em app/
FND-03B	consolidar primitives, forms e wrappers visuais
FND-03C	extrair controllers de tela e remover lógica de view
FND-04A	scaffold dos domínios canônicos restantes
FND-04B	fechar contratos e coverage de endpoints
FND-05A	endurecer sessão, auth runtime e segurança
FND-05B	logging, telemetria e observabilidade cliente
FND-05C	confiabilidade operacional, offline e degraded states
FND-06A	testabilidade canônica e isolamento de runtime
FND-06B	performance, Node LTS e release-readiness

Critério de destravamento de features

Nenhuma feature nova de produto deve começar antes de:

1. app/ depender só de core/, features/ e shared/;
2. todos os domínios core do MVP1 existirem em features/;
3. sessão, lifecycle e deep links estarem endurecidos;
4. logger e observabilidade cliente mínimos estarem prontos;
5. Node estar em LTS;
6. o legado arquitetural ativo ter sido removido.

Consequência prática

O app deixa de ser “um scaffold promissor com duas arquiteturas concorrendo” e passa a ser uma base canônica, previsível e escalável para o MVP2. O objetivo desse programa não é apenas organizar pastas; é reduzir custo cognitivo, eliminar retrabalho e impedir que features novas voltem a introduzir acoplamento ou improviso estrutural.