3. Arquitectura do Sistema

3.1 Visão Geral

A arquitectura da PawLink segue o padrão de aplicação web moderna com separação clara entre frontend, backend e serviços externos. Adoptamos uma abordagem server-first com Next.js, que permite renderização no servidor (SSR) para melhor SEO e desempenho inicial, combinada com componentes interactivos no cliente onde necessário.

┌─────────────────────────────────────────────────────────────┐
│                        CLIENTE (Browser)                    │
│           React 18 · Tailwind CSS · TanStack Query          │
└───────────────────────┬─────────────────────────────────────┘
                        │ HTTPS
┌───────────────────────▼─────────────────────────────────────┐
│                  VERCEL (Edge Network)                      │
│        Next.js 14 — SSR · API Routes · Middleware           │
├──────────────┬──────────────┬───────────────────────────────┤
│  Auth Layer  │  API Routes  │      Static Assets (CDN)      │
│  NextAuth.js │  Prisma ORM  │      Cloudflare               │
└──────┬───────┴──────┬───────┴───────────────────────────────┘
       │              │
┌──────▼──────┐ ┌─────▼──────────────────────────────────────┐
│  Supabase   │ │           Serviços Externos                  │
│ PostgreSQL  │ │  Stripe · Resend · Anthropic · Upstash      │
│  + Storage  │ │                                              │
└─────────────┘ └──────────────────────────────────────────────┘

3.2 Camadas da Arquitectura

Camada de Apresentação (Frontend)

Tecnologia	Função
Next.js 14+ (App Router)	Framework principal — SSR, routing, optimização de imagens
TypeScript	Tipagem estática para reduzir bugs em desenvolvimento
Tailwind CSS	Estilos utilitários responsivos e consistentes
shadcn/ui	Componentes acessíveis (ARIA) e personalizáveis
TanStack Query	Cache de dados do servidor, loading/error states
Zustand	Estado global da aplicação (sessão, preferências UI)
React Hook Form + Zod	Formulários com validação type-safe

Camada de Lógica de Negócio (Backend)

Tecnologia	Função
Next.js API Routes	Endpoints serverless co-localizados com o frontend
NextAuth.js	Autenticação completa com middleware de protecção de rotas
Prisma ORM	Acesso type-safe à base de dados com migrações automáticas
Zod	Validação rigorosa de todos os dados de entrada
bcryptjs	Hash seguro de palavras-passe

Camada de Dados

Tecnologia	Função
PostgreSQL via Supabase	Base de dados relacional principal
Supabase Storage	Armazenamento de imagens de animais e documentos
Upstash Redis	Cache de sessões e rate limiting

Serviços Externos

Serviço	Função
Stripe	Processamento de pagamentos (Cartão, MBWay via Payment Element)
Resend + react-email	Envio de emails transaccionais com templates profissionais
Anthropic Claude API	IA para match inteligente e chatbot de suporte
Cloudflare	CDN global, protecção DDoS, cache de assets
Sentry	Monitorização de erros em produção
Vercel Analytics	Core Web Vitals e métricas de performance

3.3 Fluxo de Dados — Adopção

Utilizador
    │
    ▼
[1] GET / → Next.js SSR → Prisma query → PostgreSQL
    │       Renderiza lista de animais no servidor
    │
    ▼
[2] Aplica filtros → TanStack Query → GET /api/animals?district=Lisboa&species=DOG
    │
    ▼
[3] API Route valida params (Zod) → Prisma query com WHERE clause
    │
    ▼
[4] Resposta JSON → React actualiza componentes AnimalGrid
    │
    ▼
[5] Clica "Adoptar" → Middleware Next.js verifica sessão JWT
    │  (sem sessão → redirect /login)
    │
    ▼
[6] Selecciona data → POST /api/reservations { animalId, date }
    │
    ▼
[7] API Route valida (Zod) → Prisma: UPDATE animal SET status='RESERVED'
                           → Prisma: CREATE reservation
    │
    ▼
[8] Resend envia email de confirmação com template react-email
    │
    ▼
[9] Resposta 201 → TanStack Query invalida cache → UI actualiza estado do animal

3.4 Fluxo de Dados — Doação Monetária

[1] Utilizador selecciona canil e montante
[2] POST /api/donations/intent → Stripe cria PaymentIntent
[3] Frontend renderiza Stripe Payment Element (dados do cartão tratados pelo Stripe)
[4] Stripe processa pagamento → webhook POST /api/payments/webhook
[5] API Route verifica assinatura HMAC do webhook
[6] Prisma: UPDATE donation SET status='COMPLETED'
[7] Resend envia recibo de doação

3.5 Decisões de Arquitectura

Porque Next.js e não SPA pura (Vite/React)?

O SEO é crítico para uma plataforma de adopção — os animais devem aparecer nos resultados de pesquisa do Google. Com SSR, a página /animals/bobi-labrador-lisboa renderiza HTML completo no servidor, indexável pelos motores de busca. Uma SPA devolveria apenas HTML vazio.

Porque Supabase e não base de dados gerida manualmente?

O Supabase oferece PostgreSQL gerido, storage de ficheiros, autenticação e realtime numa única plataforma com free tier generoso. Reduz a complexidade operacional para uma equipa pequena sem comprometer escalabilidade.

Porque Stripe e não Paypal?

O Stripe tem suporte nativo a MBWay (método de pagamento dominante em Portugal), SEPA Direct Debit e MB Multibanco através do Stripe Payment Element. Tem a melhor integração com o ecossistema Node.js/TypeScript e é PCI DSS Level 1.

6.5 KiB Raw Blame History