# 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.