MVP 1 - Arquitetura Geral¶

Visao geral¶

O MVP 1 esta organizado em tres canais de produto e um repositorio de plataforma:

Camada	Repositorio	Papel
Backend	`repos/auraxis-api`	regras de negocio, persistencia, autenticacao, contratos REST/GraphQL
Web	`repos/auraxis-web`	interface web com Nuxt 4, Pinia, Vue Query e Naive UI
App	`repos/auraxis-app`	interface mobile com Expo Router, Zustand, React Query e UI transitória em React Native Paper
Plataforma	raiz `auraxis-platform`	governanca, docs, wiki, orquestracao, contracts e tooling

Decisoes estruturais basicas¶

As decisoes de base que sustentam o workspace sao:

auraxis-platform concentra governanca, docs, automacoes e contracts;
auraxis-api, auraxis-web e auraxis-app ficam separados para permitir CI, deploy e ownership tecnico independentes;
contexto compartilhado, Projects e portal de docs vivem na platform para reduzir duplicidade entre repos.

Escolhas de stack¶

As escolhas principais do MVP 1 foram feitas para priorizar:

velocidade de entrega;
DX;
ecossistema maduro;
manutencao multi-repo;
contratos claros entre backend e frontends.

Resumo atual:

Web: Nuxt 4 + Vue 3 + Pinia + TanStack Vue Query + Naive UI
App: Expo Router + React Native + Zustand + TanStack React Query + React Native Paper (transicional; migracao para Tamagui pendente)
Backend: Flask + SQLAlchemy + Marshmallow + Ariadne

Backend¶

Stack atual¶

Flask
SQLAlchemy
Marshmallow
Flask-JWT-Extended
Flask-Migrate
APISpec / Swagger
Ariadne para GraphQL

Padrao geral¶

O backend segue, na maior parte do MVP 1, a estrutura:

controller/resource para entrada HTTP
application service para orquestracao de regra
service/model/schema para validacao e persistencia
response contract de compatibilidade entre legado e contrato padronizado

Arquivos-base:

repos/auraxis-api/app/__init__.py
repos/auraxis-api/app/controllers/response_contract.py

Validacao e pipeline canonicos¶

quality gates de backend combinam ruff, mypy, pytest, Schemathesis, scans de seguranca e Sonar;
o smoke black-box oficial pré-merge da API roda com Newman no ci.yml, contra stack docker efemera;
o smoke oficial pós-deploy roda no deploy.yml via scripts/http_smoke_check.py, cobrindo REST e GraphQL sem depender de um workflow paralelo;
suites legadas paralelas de smoke nao fazem mais parte da arquitetura ativa, para evitar drift entre collections, scripts e runbooks.

Web¶

Stack atual¶

Nuxt 4
Vue 3
Pinia
TanStack Vue Query
Naive UI
organizacao por app/features/* + app/core/*

Padrao geral¶

pagina Vue por fluxo
feature modules para dominios mais complexos
cliente HTTP centralizado em app/core/http
store de sessao com cookie reidratado no cliente
middleware de rota para area autenticada

Arquivos-base:

repos/auraxis-web/app/stores/session.ts
repos/auraxis-web/app/composables/useHttp.ts
repos/auraxis-web/app/features/dashboard/queries/use-dashboard-overview-query.ts

App¶

Stack atual¶

Expo Router
React Native
React Native Paper (transicional)
TanStack React Query
Zustand

Padrao geral¶

rotas publicas e privadas separadas por grupos do router
bootstrap de sessao via secure storage
providers de query e tema
hooks de query/mutation por dominio
migracao planejada de UI kit para Tamagui sem mudar contratos de dominio

Arquivos-base:

repos/auraxis-app/app/_layout.tsx
repos/auraxis-app/stores/session-store.ts
repos/auraxis-app/components/providers/app-providers.tsx

Regras arquiteturais relevantes¶

GitHub Projects e a fonte de verdade operacional
contratos e docs vivem no auraxis-platform
APIs tentam preservar compatibilidade entre payload legado e payload padronizado
autenticacao protege recursos privados e reaproveita guardas e contexto de request
a API mantém uma única trilha oficial de smoke por estagio: Newman antes do merge e smoke HTTP Python após deploy
frontends usam fallback visual seguro quando a integracao ainda nao esta completa

Principios de arquitetura¶

Os principios de desenho que orientam o workspace sao:

arquitetura orientada a dominio;
adapters finos em REST, GraphQL e UI;
regras de negocio centralizadas em servicos/casos de uso;
dependencias invertidas para facilitar teste e evolucao;
contratos explicitos e versionaveis entre camadas e repos.

Regras de desenho¶

evitar logica de negocio em controllers, resolvers ou componentes de borda;
garantir idempotencia em fluxos sensiveis;
manter trilha de auditoria para acoes criticas;
tratar erros com catalogo publico e sem vazamento interno;
preferir composicao sobre heranca para extensibilidade.

Contratos e integracao¶

APIs publicas devem ter contrato formal (OpenAPI ou GraphQL schema);
a referencia publica REST pode usar viewer ligado a snapshot OpenAPI, enquanto a referencia publica GraphQL deve ser estatica e desacoplada do runtime real;
breaking change exige:
aviso no backlog;
plano de migracao;
janela de compatibilidade quando aplicavel.

Testabilidade e evolucao¶

cobrir no minimo:
caso feliz;
validacoes;
autorizacao/autenticacao;
cenarios de erro esperados;
preferir testes de contrato em fronteiras publicas;
refatorar continuamente para manter adapters finos;
registrar debitos tecnicos com urgencia e impacto;
priorizar correcoes que reduzam risco sistemico.

Assimetrias atuais¶

Essas diferencas precisam ficar documentadas:

o backend expoe dashboard financeiro em /transactions/dashboard, enquanto web e app consultam /dashboard/overview
o backend expoe carteira em /wallet/valuation e entradas em /wallet, enquanto web e app consultam /wallet/summary
web e app ainda mantem contratos manuais em types/contracts/*, apesar de ambos possuirem tipos OpenAPI gerados
metas ja existem na API, mas ainda nao aparecem em tela web/app no codigo atual

Consequencia pratica¶

O MVP 1 tem uma base de dominio mais madura na API do que nos frontends. Isso nao invalida o MVP, mas exige comunicacao clara para stakeholder:

backend ja suporta mais comportamento do que o produto exposto em tela
parte da experiencia visual ainda e de integracao parcial

Proxima evolucao natural¶

alinhar contratos consumidos por web/app com os endpoints reais da API
expor metas em tela
substituir fallbacks visuais por dados reais
fechar gaps de rota de auth e dashboard/carteira