198 lines (139 loc) · 9.09 KB

Por que Esta Stack Tecnológica?

English | 한국어 | 简体中文 | 日本語 | Português

Este documento explica o raciocínio por trás de cada escolha tecnológica neste template fullstack.

Frontend

Next.js 16 + React 19

Componentes de Servidor: Reduz o bundle JavaScript do cliente, melhora o tempo de carregamento inicial
App Router: Roteamento baseado em arquivos com layouts, estados de loading e error boundaries built-in
Turbopack: Servidor de dev e builds mais rápidos comparado ao Webpack
React 19: Performance melhorada com recursos concorrentes, Actions e hook use()

TailwindCSS v4

Zero runtime: Todos os estilos compilados em tempo de build
Lightning CSS: 100x mais rápido que PostCSS-based v3
Configuração CSS-first: Sintaxe CSS nativa em vez de configuração JavaScript
Bundles menores: Remoção automática de estilos não utilizados

shadcn/ui

Componentes copy-paste: Sem dependência npm, propriedade total do código
Radix primitives: Acessível por padrão (ARIA, navegação por teclado)
Tailwind-native: Consistente com a abordagem de estilização do projeto
Customizável: Fácil de modificar sem lutar com um design system

TanStack Query

Cache automático: Desduplicação, refetching em background, stale-while-revalidate
DevTools: Inspector de queries built-in para debugging
Framework agnostic: O mesmo modelo mental funciona no React Native se necessário
Atualizações otimistas: Suporte de primeira classe para UIs responsivas

Jotai

Modelo atômico bottom-up: Construa estado combinando átomos, otimize renders baseado em dependências de átomos
Sem re-renders extras: Apenas componentes inscritos em átomos alterados re-renderizam
TypeScript-first: Excelente inferência de tipos
Leve: ~3KB, sem providers necessários para uso básico

TanStack Form

Headless & composable: Padrão HOC withForm para composição de formulários modular com segurança de tipos
Type-safe: Inferência completa de TypeScript para valores de formulário e validação
Interface simples: API mais limpa comparada ao React Hook Form ou Formik

Backend

FastAPI

Ecossistema AI/ML: Acesso direto às bibliotecas Python de IA (LangChain, Transformers, etc.)
Async-first: Construído no Starlette com suporte nativo a async/await
Docs auto-geradas: OpenAPI (Swagger) e ReDoc out of the box
Validação Pydantic: Validação de request/response com type hints
Escalabilidade: Fácil escalabilidade horizontal com design stateless

SQLAlchemy (async)

Flexibilidade ORM: Pode escrever SQL raw quando necessário, ORM quando conveniente
Suporte async: Asyncio nativo com driver asyncpg
Migration-friendly: Integração Alembic para versionamento de schema
Ecossistema maduro: Battle-tested em produção por décadas

PostgreSQL 16

Conformidade ACID: Integridade de dados garantida
Suporte a JSON: JSONB para dados semi-estruturados flexíveis
Extensão vetorial: pgvector para embeddings de IA e busca por similaridade
Performance: Query planner avançado, queries paralelas, particionamento
Extensões: PostGIS, full-text search built-in

Redis 7

Latência sub-milissegundo: Armazenamento de estruturas de dados em memória
Versátil: Cache, session store, pub/sub, rate limiting
Opções de persistência: Snapshots RDB ou AOF para durabilidade
Suporte a cluster: Escalabilidade horizontal quando necessário

MinIO

Compatível com S3: Substituto drop-in para AWS S3 API, migração perfeita para Cloud Storage de produção
Desenvolvimento local: Mesma API do ambiente de produção, sem vendor lock-in durante desenvolvimento
Self-hosted: Roda localmente com Docker/Podman, sem dependências externas ou contas de serviço
Open source: Armazenamento de objetos enterprise-grade com controle total sobre dados

Mobile

Flutter 3.41.2

Korea eGovFrame v5: Selecionado como framework mobile oficial pelo Korea e-Government Standard Framework
Versionamento flexível: Fácil fixar e atualizar versões Flutter/Dart por projeto
Hot reload: Iteração de UI em sub-segundos durante desenvolvimento
Performance nativa: Compilado para ARM, sem bridge JavaScript

Riverpod 3

Compile-safe: Dependências verificadas em tempo de compilação
Testável: Fácil de mockar e testar isoladamente
Sem context necessário: Acesse estado de qualquer lugar sem BuildContext
Geração de código: Reduz boilerplate com riverpod_generator

go_router 17

Roteamento declarativo: Navegação baseada em URL como na web
Deep linking: Funciona out of the box para iOS/Android
Type-safe: Parâmetros de rota gerados por código
Navegação aninhada: Shell routes para navegação inferior, tabs

Forui

shadcn/ui para Flutter: Linguagem de design consistente com web (shadcn/ui)
Customizável: Componentes tematizáveis com sistema de tokens similar ao Tailwind
Acessível: Semânticas equivalentes a ARIA para mobile
Leve: Sem dependências pesadas, apenas widgets

Firebase Crashlytics

Relatório de crashes em tempo real: Visibilidade imediata de problemas em produção
Breadcrumbs: Ações do usuário que levaram ao crash
Desobfuscação de stack: Stack traces legíveis para Flutter
Free tier: Limites generosos para a maioria dos apps

Fastlane

Releases automatizados: Um comando para build, assinar e deploy
Cross-platform: iOS e Android com o mesmo workflow
Integração CI: Funciona perfeitamente com GitHub Actions
Gerenciamento de metadados: Screenshots, descrições, changelogs

Infraestrutura

Terraform

Infraestrutura como Código: Mudanças de infra versionadas e revisáveis
Declarativo: Descreva o estado desejado, deixe o Terraform cuidar do resto
Gerenciamento de estado: Rastreie o que está deployado, planeje antes de aplicar
Módulos: Componentes de infraestrutura reutilizáveis e compartilháveis

GCP (Cloud Run, Cloud SQL, Cloud Storage)

Generous free tier: $300 de crédito para novas contas, free tier permanente para muitos serviços
Containers serverless: Sem gerenciamento de servidor, escala para zero
Pay-per-use: Cobrado apenas quando processando requisições
Banco de dados gerenciado: Backups automáticos, HA, manutenção
CDN global: Cloud CDN para assets estáticos e cache de API

GitHub Actions + Workload Identity Federation

Deploy sem chaves: Sem chaves de conta de serviço para gerenciar ou rotacionar
Integração nativa GitHub: Acionado em push, PR, agendado
Matrix builds: Testes paralelos em versões/plataformas
Marketplace: Milhares de ações da comunidade

Experiência do Desenvolvedor

Toolchain Baseada em Rust

Priorizamos velocidade em todo o workflow de desenvolvimento escolhendo ferramentas baseadas em Rust:

Biome: Linter + formatter em uma ferramenta, 100x mais rápido que ESLint + Prettier
uv: Gerenciador de pacotes Python, 10-100x mais rápido que pip/poetry
Turbopack: Bundler Next.js, mais rápido que Webpack
Lightning CSS: Compilador TailwindCSS v4, 100x mais rápido que PostCSS

mise

Suporte a monorepo poliglota: Node, Python, Flutter, Terraform — ecossistemas diferentes, uma ferramenta
Versões locais por projeto: .mise.toml garante ambientes consistentes entre OS durante onboarding de devs
Task runner: Substitua Makefile, npm scripts, shell scripts com comandos mise unificados
Escrito em Rust: Troca instantânea de ferramentas, sem overhead de startup

Monorepo Poliglota

Repositório único: Web (TypeScript), API (Python), Mobile (Dart), Infra (HCL) em um só lugar
Contextos delimitados: Cada ecossistema de linguagem tem escopo em seu diretório, prevenindo contaminação cruzada
Mudanças atômicas: Mudanças frontend + backend em um único PR
Ferramentas unificadas: Mesmos comandos mise em todos os apps

Trade-offs

Escolha	Trade-off	Por que Aceitamos
Next.js vs Remix/SvelteKit	Bundle maior, mais complexidade	Ecossistema, compatibilidade React 19
Next.js vs Flutter Web	Codebase separado do mobile	SEO, SSR, bundle menor, compatibilidade com ecossistema web
FastAPI vs Node.js	Dois runtimes (Node + Python)	Ecossistema Python AI/ML, escalabilidade
Flutter vs React Native	App maior, renderização customizada	Korea eGovFrame v5, versionamento flexível

Resumo

Esta stack otimiza para:

Velocidade do desenvolvedor: Hot reload, segurança de tipos, clientes auto-gerados
Prontidão para produção: Serviços gerenciados, escalabilidade serverless, CI/CD
Escalabilidade de equipe: Fronteiras claras, ferramentas compartilhadas, documentação
Manutenibilidade de longo prazo: Tecnologias comprovadas, comunidades ativas