6.1 KiB
6. Stack Tecnológica
6.1 Frontend
| Tecnologia | Versão | Função | Justificação |
|---|---|---|---|
| Next.js | 14+ | Framework React principal | SSR/SSG integrado, App Router, optimizações automáticas de imagem e font, middleware nativo |
| TypeScript | 5+ | Linguagem de programação | Tipagem estática reduz bugs, melhora DX e facilita manutenção a longo prazo |
| Tailwind CSS | 3+ | Framework de estilos | Produtividade elevada, classes utilitárias, sistema de design consistente e responsivo por defeito |
| shadcn/ui | latest | Componentes base | Acessíveis por defeito (ARIA), totalmente personalizáveis, sem overhead de bundle desnecessário |
| TanStack Query | 5+ | Gestão de dados do servidor | Cache automático, invalidação, loading/error states, optimistic updates sem boilerplate |
| Zustand | 4+ | Estado global cliente | Minimalista, sem boilerplate, ideal para preferências UI e dados de sessão no cliente |
| React Hook Form | 7+ | Gestão de formulários | Performance superior (sem re-renders a cada tecla), integração nativa com Zod |
| Zod | 3+ | Validação de esquemas | Type-safe, partilhado entre frontend e backend, mensagens de erro em português |
| react-email | latest | Templates de email | Componentes React para emails transaccionais com preview em browser |
| next/image | built-in | Optimização de imagens | WebP automático, lazy loading, placeholder blur, responsive sizes |
6.2 Backend
| Tecnologia | Versão | Função | Justificação |
|---|---|---|---|
| Next.js API Routes | 14+ | Endpoints da API | Co-localizados com o frontend, serverless por defeito, sem configuração de servidor separado |
| Prisma ORM | 5+ | Acesso à base de dados | Type-safe, migrações declarativas, excelente DX, Prisma Studio para explorar dados |
| NextAuth.js | 4+ | Autenticação | Suporte a múltiplos providers, sessões seguras (JWT/database), middleware de protecção de rotas |
| bcryptjs | 2+ | Hash de palavras-passe | Standard seguro para hashing de credenciais, factor de custo configurável |
| Resend | 2+ | Envio de emails | API moderna com alta taxa de entrega, integração directa com react-email, webhook de eventos |
| Stripe SDK | 14+ | Pagamentos | PCI DSS Level 1, suporte MBWay/SEPA/MB, webhooks robustos, excelente documentação |
6.3 Infra-estrutura e Serviços
| Serviço | Plano Inicial | Função | Custo Estimado |
|---|---|---|---|
| Supabase | Free → Pro | PostgreSQL + Storage + Auth | Gratuito até 500MB DB; $25/mês no Pro |
| Vercel | Hobby → Pro | Hosting + CDN + CI/CD automático | Gratuito na fase inicial; $20/mês no Pro |
| Upstash Redis | Free | Cache e rate limiting | Gratuito até 10.000 comandos/dia |
| Resend | Free | Email transaccional | Gratuito até 3.000 emails/mês |
| Stripe | Pay-as-you-go | Pagamentos online | 1,4% + 0,25€ por transacção (cartões UE) |
| Cloudflare | Free | CDN e protecção DDoS | Gratuito para sites |
| Sentry | Free | Monitorização de erros | Gratuito até 5.000 eventos/mês |
| Anthropic Claude API | Pay-as-you-go | IA — match e chatbot | ~$3/1M tokens input (Sonnet 4) |
Custo total estimado na fase MVP: ~0–25€/mês
6.4 Ferramentas de Desenvolvimento
| Ferramenta | Função |
|---|---|
| pnpm | Gestor de pacotes (mais rápido e eficiente que npm) |
| ESLint + Prettier | Linting e formatação automática de código |
| Husky + lint-staged | Git hooks para validar código antes de cada commit |
| Vitest | Framework de testes unitários e de integração |
| Playwright | Testes end-to-end e de acessibilidade |
| Prisma Studio | Interface visual para explorar e editar a base de dados |
| @next/bundle-analyzer | Análise do tamanho do bundle JavaScript |
| Storybook | Documentação e desenvolvimento isolado de componentes UI |
6.5 Variáveis de Ambiente
# .env.local (nunca commitar — usar .env.example como template)
# Base de Dados
DATABASE_URL="postgresql://user:password@host:5432/pawlink"
# Autenticação
NEXTAUTH_SECRET="gerar com: openssl rand -hex 32"
NEXTAUTH_URL="http://localhost:3000"
# Stripe
STRIPE_SECRET_KEY="sk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."
# Email
RESEND_API_KEY="re_..."
RESEND_FROM_EMAIL="noreply@petlink.pt"
# Supabase Storage
NEXT_PUBLIC_SUPABASE_URL="https://xxx.supabase.co"
NEXT_PUBLIC_SUPABASE_ANON_KEY="..."
SUPABASE_SERVICE_ROLE_KEY="..."
# Anthropic (IA)
ANTHROPIC_API_KEY="sk-ant-..."
# Redis (Rate Limiting)
UPSTASH_REDIS_REST_URL="https://..."
UPSTASH_REDIS_REST_TOKEN="..."
6.6 Justificação das Escolhas Tecnológicas
Porque Next.js em vez de Remix ou Astro?
Next.js tem o ecossistema mais maduro para aplicações React complexas com SSR. O App Router (Next.js 14) oferece Server Components que permitem buscar dados directamente no servidor sem APIs intermediárias para o conteúdo estático. A integração com Vercel é nativa e o deploy é trivial.
Porque PostgreSQL em vez de MongoDB?
Os dados da PetLink são fortemente relacionais (utilizador → reserva → animal → canil). Uma base de dados relacional como PostgreSQL garante integridade referencial por defeito, suporta transacções ACID (críticas para reservas e pagamentos) e tem melhor suporte a queries complexas com joins.
Porque Tailwind CSS em vez de CSS Modules ou Styled Components?
Tailwind elimina a necessidade de alternar entre ficheiros CSS e JSX. As classes utilitárias são co-localizadas com o markup, tornando o código mais fácil de ler e manter. O modo JIT garante que apenas as classes usadas chegam ao bundle final.
Porque Stripe em vez de SIBS/Multibanco directo?
O Stripe suporta MBWay, MB Multibanco e SEPA através da sua abstracção unificada (Payment Element), é PCI DSS Level 1 (o mais alto), tem webhooks fiáveis para confirmações assíncronas, e tem documentação e SDK TypeScript excelentes. A integração directa com SIBS requer certificações e processos burocráticos inadequados para a fase inicial.