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, Tamagui, React Query e arquitetura `app + core + features + shared`
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 + Tamagui + TanStack React Query + arquitetura feature-first com shell/runtime canônico
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
Tamagui
TanStack React Query
Zustand apenas em core/ para shell, sessao e runtime transversal

Padrao geral¶

rotas publicas e privadas separadas por grupos do router;
shell, sessao, lifecycle e deep links centralizados em core/;
contratos, services e hooks de dominio centralizados em features/;
primitives, forms, tema, animations e testing em shared/;
arquivos .tsx de app/ contendo apenas composicao visual e wiring minimo de tela.

Arquivos-base:

repos/auraxis-app/app/_layout.tsx
repos/auraxis-app/core/providers/runtime-provider.tsx
repos/auraxis-app/core/session/session-store.ts
repos/auraxis-app/core/shell/use-app-startup.ts
repos/auraxis-app/shared/contracts/api-contract-map.ts
repos/auraxis-app/shared/components/app-screen.tsx

Leitura complementar:

docs/wiki/MVP-1-App-Foundation-Layer.md

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
o app ainda conclui a transicao da arquitetura legada (components/, hooks/, lib/, stores/) para a trilha canônica (core/, features/, shared/)
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
concluir a fundacao do app antes da primeira feature nova, conforme MVP-1-App-Foundation-Layer

Programas de readiness pre-FastAPI¶

Antes do MVP 2 em FastAPI, o backend do MVP 1 passou por tres movimentos complementares:

API10, para estabilizar a superficie funcional e contratual;
API18, para elevar a maturidade operacional final do backend;
API19, para endurecer a suite integrada de desenvolvimento e entrega.

API10 - Estabilizacao pre-FastAPI¶

O API10 tratou a API do MVP 1 como plataforma canonica, previsivel e documentada.

Objetivos centrais:

tornar REST a superficie canonica e OpenAPI/Scalar a referencia publica realmente confiavel;
explicitar ownership entre REST e GraphQL por dominio;
eliminar drift de semantica (PUT vs PATCH, startDate vs start_date, page_size vs per_page);
reduzir custo de leitura em endpoints quentes, principalmente GET /user/me, GET /user/bootstrap e read models de transacoes;
endurecer autenticacao, identidade e politica de sessao;
normalizar wallet, goals, simulations e dashboard em torno de contratos de produto coerentes;
fechar o ciclo de publicacao de docs para que o portal nao fique defasado.

Backlog executavel:

API11 - governanca contratual REST, GraphQL e OpenAPI
API12 - autenticacao por email e politica de sessao
API13 - contexto autenticado e bootstrap
API14 - wallet para REST estrito
API15 - normalizacao de goals e simulations
API16 - ownership canônico de GraphQL
API17 - dashboard como read model proprio

Criterio de saida:

toda rota publica relevante com semantica REST clara;
GraphQL sem contradizer o contrato canonico REST;
docs publicas refletindo o runtime real;
endpoints quentes sem trabalho desnecessario;
ownership explicito e rastreavel por dominio.

API18 - Hardening final do MVP 1 backend¶

O API18 foi o ciclo final de hardening para elevar maturidade operacional sem mexer indevidamente na regra de negocio.

Objetivos:

aumentar seguranca;
elevar manutenibilidade;
melhorar DX;
remover complexidade acidental;
reforcar previsibilidade de contratos;
reduzir drift estrutural e operacional.

Frentes executadas:

API18.4 - higiene estrutural do repo e remocao de drift acidental
API18.1 - hardening de identidade e autenticacao canonica
API18.2 - simplificacao e performance das queries de transacoes
API18.3 - limpeza de ownership entre dashboard, transactions e GraphQL
API18.6 - sweep final de consistencia em wallet e goals
API18.5 - padronizacao operacional dos modulos perifericos do MVP 1

Principio operacional:

nenhuma dessas etapas deve quebrar consumidores ativos de web/app;
toda mudanca precisa manter observabilidade, compatibilidade explicita e docs sincronizadas;
o ciclo so termina quando o backend estiver pronto para coexistencia controlada com FastAPI sem depender de refactors emergenciais.

API19 - Suite integrada de desenvolvimento e entrega¶

O API19 endureceu a esteira de desenvolvimento e entrega do backend MVP1 para coexistir com FastAPI sem herdar fragilidade operacional.

Objetivo:

tornar a cadeia de build, smoke, integration, security e observability robusta, escalavel, previsivel, segura, auto-recuperavel em falhas de infraestrutura e economicamente viavel.

Causa raiz dos problemas tratados:

dependencia de pulls externos em tempo real para subir stack e construir imagens;
rebuild repetido dos mesmos artefatos em jobs diferentes;
falhas de registry/network e falhas de produto misturadas no mesmo fluxo;
bootstrap, retry e diagnostico espalhados pelo workflow;
paridade imperfeita entre local e CI;
ausencia de uma classificacao canonica de falha.

Frentes executaveis:

API19.1 - supply chain de imagens e registry hardening
API19.2 - bootstrap canonico de stack e auto-recuperacao
API19.3 - classificacao de falhas, diagnostico e artifacts
API19.4 - paridade local/CI e contratos operacionais
API19.5 - canarios continuos, governanca economica e readiness de entrega

Criterios de aceite:

smoke e full consumirem artefatos e bootstrap canonicos;
falhas de registry/network nao dependerem de rerun manual cego;
falhas de infra e falhas funcionais claramente separadas;
local e CI reutilizando a mesma trilha operacional principal;
evidencias suficientes para triagem em um unico run;
reducao observavel de rebuild redundante e tempo desperdicado de triagem;
robustez com custo incremental controlado.

Programa de monetizacao MVP 1¶

Com a estabilizacao tecnica do backend e da esteira, o proximo programa transversal do MVP 1 passa a ser monetizacao.

Ele combina tres eixos:

billing e checkout;
entitlements e superfícies premium;
email transacional e reminder engine.

O programa tambem passa a incorporar um quarto eixo:

observabilidade e monitoramento centralizado com rollout zero-cost first.

Diretrizes executivas:

manter somente Free e Premium como tiers publicos;
tratar trial como lifecycle interno;
usar mensal e anual como unicas ofertas iniciais;
priorizar checkout hospedado e baixo atrito operacional;
sincronizar estado premium entre API, web e app com uma unica fonte de verdade server-side.

Referencia curada:

MVP-1-Monetizacao-e-Assinaturas.md
MVP-1-Monitoramento-e-Observabilidade.md