amare/openspec/changes/archive/2026-07-29-setup-foundation/design.md

Context

Repositório greenfield: contém 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.