118 lines
6.1 KiB
Markdown
118 lines
6.1 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
# .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.
|