## Context

Repositório greenfield: contém [SPEC.md](../../../SPEC.md) (especificação normativa aprovada), scaffold OpenSpec e um commit inicial. Não existe aplicação Laravel, banco, CI ou contêiner.

Versões-alvo confirmadas no Packagist (jul/2026): Laravel 13.23, Filament 5.7, Livewire 4.3, Pest 4.7, Larastan 3.10, Pint 1.29. Ambiente local: PHP 8.5.8, Composer 2.9.5, Node 22, Docker 29 + Compose v5.3.

ADRs ADR-001..ADR-010 do SPEC §21 são aceitas e serão registradas em `docs/adr/` sem reabertura de decisões.

## Goals / Non-Goals

**Goals:**

- Entregar esqueleto Laravel funcional com Filament autenticado, Livewire/Tailwind configurados e Postgres local.
- Estabelecer gates de qualidade (Pint, Larastan, Pest, arch tests) e scripts Composer padronizados.
- Produzir imagem Docker FrankenPHP reproduzível com healthcheck e processos web/queue/scheduler.
- CI verde nos 5 jobs bloqueantes antes de avançar para Fase 1.
- Design tokens mínimos e layout público placeholder para validar pipeline visual futuro.

**Non-Goals:**

- Implementar requisitos funcionais das Fases 1–5 (site, CRM, eventos, financeiro, documentos).
- Deploy em staging ou produção (adiado).
- FrankenPHP worker mode, Redis, S3 em produção, integração de e-mail transacional.
- Qualquer item listado em SPEC §4.2 "Fora do MVP".

## Decisions

### 1. Bootstrap via `composer create-project` em diretório temporário

**Decisão:** Instalar Laravel 13 com `composer create-project laravel/laravel` em diretório temporário e mover arquivos para a raiz, preservando `SPEC.md`, `openspec/` e `.codex/`.

**Alternativas:** Instalar na raiz (conflita com arquivos existentes); copiar skeleton manualmente (mais erro-prone).

**Rationale:** Padrão Laravel garante estrutura correta; evita sobrescrever artefatos de spec.

### 2. PostgreSQL 17 via Docker Compose local

**Decisão:** Serviço `postgres:17` no Compose com volume nomeado, healthcheck e credenciais em `.env.example`.

**Alternativas:** SQLite local (proibido pelo SPEC §14.2 para integração); Postgres instalado no host (sem `psql` no ambiente).

**Rationale:** Alinha dev local com CI; evita diferenças SQLite/Postgres.

### 3. Sessão, cache e fila em `database`

**Decisão:** `SESSION_DRIVER=database`, `CACHE_STORE=database`, `QUEUE_CONNECTION=database`.

**Alternativas:** Redis (fora do MVP, ADR-008); file/cookie session (menos alinhado com deploy containerizado).

**Rationale:** ADR-008; sem dependência extra; migrations padrão Laravel cobrem tabelas.

### 4. Papéis via enum `UserRole` na coluna `users.role`

**Decisão:** Enum PHP `UserRole: admin|assistant` + coluna `is_active` boolean. Filament `canAccessPanel()` nega inativos.

**Alternativas:** Spatie Permission (proibido pelo SPEC §3.4); flags booleanas separadas.

**Rationale:** YAGNI; atende ADM-01 e §12.2 sem complexidade.

### 5. Design tokens como CSS custom properties + Tailwind theme extension

**Decisão:** Arquivo `resources/css/tokens.css` com custom properties; `tailwind.config.js` referencia tokens via `theme.extend`.

**Alternativas:** SCSS variables espalhadas; JSON tokens com build step extra.

**Rationale:** Centraliza SPEC §6.3; Tailwind consome nativamente; sem dependência extra.

### 6. Isolamento visual: layout público separado do painel Filament

**Decisão:** Layout Blade público em `resources/views/layouts/public.blade.php` com tokens próprios; Filament usa tema padrão do painel.

**Alternativas:** Tema Filament customizado para site (mistura concerns); component library compartilhada prematura.

**Rationale:** Mitiga conflito Tailwind 4 / Filament 5 / tema público premium.

### 7. FrankenPHP regular mode, multi-stage Dockerfile

**Decisão:** Dockerfile com stages `composer`, `frontend`, `runtime` (FrankenPHP). PHP fixado conforme suporte Laravel 13 no momento da instalação (8.4 ou 8.5). `config:cache` apenas no entrypoint/deploy, nunca em stage sem env final.

**Alternativas:** Nginx + PHP-FPM (SPEC exige FrankenPHP); worker mode (ADR-006 proíbe no MVP).

**Rationale:** ADR-006; imagem única para web/queue/scheduler (§15.2).

### 8. CI em GitHub Actions com PostgreSQL service container

**Decisão:** Workflow `.github/workflows/ci.yml` com jobs `static`, `unit`, `feature`, `browser`, `container`. Feature tests usam Postgres service; browser job builda imagem e roda Pest Browser com locale `pt-BR`, TZ `America/Fortaleza`, animações desabilitadas.

**Alternativas:** GitLab CI; CircleCI (remote já é GitHub).

**Rationale:** Remote `manoel-freitas/amore-site`; SPEC §14.1.

### 9. Estrutura de diretórios modular preparada, não populada

**Decisão:** Criar apenas diretórios quando primeiro arquivo for adicionado (SPEC §9.4). Na Fase 0, garantir `tests/Architecture/` e namespace base; não criar `app/Application/`, `app/Domain/` vazios.

**Rationale:** YAGNI; arch tests validam boundary quando Domain existir na Fase 2+.

## Risks / Trade-offs

| Risco | Mitigação |
|---|---|
| Conflito Tailwind 4 + Filament 5 + tema público | Layouts separados; Vite entries distintos se necessário |
| Snapshots visuais instáveis no CI | Imagem Linux fixa, fontes instaladas, relógio congelado, seed determinístico (preparação na Fase 1) |
| `config:cache` congela env incorreto | Cache apenas no entrypoint com env final do deploy |
| PHP 8.5 muito novo para alguma extensão | Fixar versão PHP no Dockerfile conforme matriz Laravel 13; testar build no job `container` |
| Filament panel + Livewire 4 coexistência | Seguir docs oficiais de instalação Filament 5; testes feature de login |

## Migration Plan

1. Bootstrap Laravel em diretório temp → mover para raiz.
2. Configurar `.env` / `.env.example` com Postgres e locale.
3. Instalar Filament, Pest, Larastan, Pint; configurar scripts Composer.
4. Adicionar Compose, Dockerfile, CI workflow.
5. Seed admin local; documentar credenciais apenas para dev.
6. Validar `composer quality` e jobs CI no PR.

**Rollback:** Reverter commit da Fase 0; repo volta ao estado spec-only.

## Open Questions

- **Staging target:** VPS próprio, Fly.io, Render ou Railway — decisão adiada; change futura para deploy.
- **Registry de imagem:** GitHub Container Registry vs Docker Hub — definir na change de deploy.
- **Provedor S3-compatible:** necessário na Fase 1+ para mídia pública; local usa `storage/app/public` ou MinIO opcional no Compose.
- **Provedor de e-mail:** necessário na Fase 2 (notificação de leads); Fase 0 usa `log` driver ou Mailpit no Compose opcional.