Notas de projeto pro Claude Code (e qualquer dev que entre depois). Resume todas as decisões tomadas ao longo das conversas. Linguagem do projeto: **PT-BR**.
---
## 1. Visão geral
App web pro casamento de **Stefanie & Leandro**. Convidados escaneiam um QR Code na mesa, abrem o site, mandam fotos/vídeos + uma mensagem. Os noivos administram tudo num painel `/admin`.
**Escopo**: single-tenant (um casamento). Multi-tenant (SaaS) foi avaliado — fica pra um pivot futuro se houver demanda real (3+ pedidos).
No disco todos ficam como **diretórios irmãos** (ex.: `C:\Users\lrone\code\lronetto-*`). O `Makefile` orquestrador (neste repo, `lronetto-main`) referencia os outros por caminho relativo — sobrescrevível via `GITEA_DIR=` / `WEDDING_DIR=` / `FINANCE_DIR=` / `CLAUDEWEB_DIR=`.
Duas pegadinhas de layout, já tratadas no Makefile orquestrador:
- **claudeweb**: o compose fica em `deploy/compose.yml`, mas o `.env` fica na **raiz** do repo (daí o `--env-file` explícito). E o `up` dele builda antes a imagem do worker efêmero (`make worker-image`), que **não é serviço do compose** — por isso `up-claudeweb` delega pro Makefile do próprio repo em vez de chamar `docker compose` direto.
- **claudeweb** declara uma segunda network external, `claudeweb-workers` (isola os workers efêmeros da `infra-net`). O alvo `network-claudeweb` a cria reusando o `network.sh` via `INFRA_NETWORK=`.
**Por que repos separados**: cada stack tem ciclo de vida, histórico e CI próprios. Subir/derrubar ou versionar uma não afeta as outras. Gitea pode ser desativado sem tocar no app.
**`lronetto-main` é o "platform layer"** que os consumidores usam. `gitea`, `wedding`, `finance` e `claudeweb` conectam ao Postgres/Redis/MinIO de lá pela `infra-net`, e são expostos pelo Caddy de lá.
> Histórico: nasceu como monorepo `wedding-app` (branch `main`) com tudo em `infra/{main,gitea,wedding_photo}/`. Foi dividido em 3 repos (fresh start, sem histórico herdado — o monorepo original fica arquivado como backup).
`infra-net` é **external**. Criada pelo `network.sh` (chamada por `make network`). Containers de stacks diferentes se enxergam por nome via DNS interno do Docker.
`claudeweb-workers` é uma segunda network external, usada só pelo claudeweb: os workers efêmeros sobem **apenas** nela, isolados da `infra-net` (egress via `worker-proxy`). Criada por `make network-claudeweb`. Os containers da stack main que os workers precisam alcançar (`redis`, `gitea`, `minio`) têm que ser **conectados manualmente** a ela — ver README do claudeweb:
`wedding_app` tem `extra_hosts: media.{DOMAIN_BASE}:host-gateway` e `wedding.{DOMAIN_BASE}:host-gateway` pra que, mesmo dentro do container, ele resolva esses hostnames pro Docker host gateway → Caddy. Assim assinaturas S3 fecham (signing host == host que o browser usa pra PUT).
2. Browser faz **`PUT` direto no MinIO** (não passa pelo backend) com a URL pré-assinada
3. Decisão **single vs multipart**:
-`<= 50 MB`: single PUT
-`> 50 MB`: multipart 10 MB chunks
4.`POST /api/uploads/:id/confirm` → backend faz HEAD pra verificar o objeto, completa multipart se aplicável, **se for HEIC**: transcoda pra JPEG e substitui o storage_key, marca `approved` (ou `pending` se moderation=`pre`)
5. Galeria pública lista só `status=approved`
### HEIC transcoding
- Detecção: `mime_type in {"image/heic", "image/heif"}`
- Em `/confirm` após HEAD: baixa, decoda com pillow-heif, aplica EXIF rotation, salva JPEG quality 88 progressive, escreve com `.jpg`, deleta HEIC
- **Falha não bloqueia o upload**: log + mantém HEIC original (gallery mostra placeholder)
- Razão: browsers (especialmente Android) não renderizam HEIC nativamente
### Multipart upload (cliente)
- Em `apps/web/src/lib/upload.ts`
- Sequential (não paralelo pra MVP) com `XMLHttpRequest` (precisa de progress event)
- ETag de cada chunk via header `etag` na resposta — exige CORS `ExposeHeaders: ["ETag"]` no bucket
### Admin login
-`POST /api/admin/login` body `{email, password}`
- Valida email contra `ALLOWED_ADMIN_EMAILS` (separados por vírgula no env)
- Compara senha com `ADMIN_PASSWORD` via `hmac.compare_digest` (constant-time)
- Issue cookie HttpOnly JWT HS256 com email + exp 7 dias
-`GET /api/admin/*` decora com `Depends(get_admin_email)` que verifica o cookie
### Admin: gestão de uploads
-`GET /api/admin/uploads?status=...&kind=photo|video&q=...&cursor=...` — paginação por timestamp DESC
-`PATCH /api/admin/uploads/:id` — edita `authorName` + `message`
### Caddy e Postgres do main não conhecem finance nem claudeweb (pendente)
`caddy/Caddyfile` (neste repo) tem blocos só pra `gitea`, `wedding`, `pgadmin`, `minio` e `media`. E `postgres/init/01-create-databases.sh` cria role/DB só pra wedding e gitea. Os dois apps novos trazem os trechos prontos pra colar aqui:
Enquanto não forem aplicados, `make up-finance` / `make up-claudeweb` sobem os containers mas eles não ficam acessíveis por HTTPS (e falham ao conectar no banco). Lembre que o init do postgres **só roda com `PGDATA` vazio** — em banco já existente, crie role/DB manualmente (ver abaixo).
`postgres/init/01-create-databases.sh` (neste repo, `lronetto-main`) é executado pelo entrypoint do postgres **apenas quando `PGDATA` está vazio**. Pra "rerodar":
```bash
make down-main
sudo rm -rf postgres/data
make up-main
```
Alternativa: criar manualmente via `docker exec -i postgres psql`.
### `docker exec -it` com heredoc
`-t` aloca TTY e conflita com stdin redirecionado. Usar **`-i` só**:
```bash
docker exec -i postgres psql -U postgres <<EOF
CREATE ROLE gitea WITH LOGIN PASSWORD 'xxx';
EOF
```
### Gitea reservou nomes
`admin`, `api`, `user`, `org`, `explore`, `install`, `repo` etc. são reservados. Use outro nome (ex.: `lronetto`, `gitadmin`). O role admin vem do flag `--admin`, não do username.
Usamos a **regular** com `INSTALL_LOCK=true` pra pular o wizard `/install` no primeiro boot.
### `docker exec` por padrão entra como root
Pra Gitea, isso quebra (`Gitea is not supposed to be run as root`). Sempre `docker exec -u git ...` quando for chamar binário do gitea.
### CORS no MinIO
Bucket precisa de `ExposeHeaders: ["ETag"]` pra multipart funcionar (cliente lê ETag de cada PUT). Aplicado pelo `minio/init.sh` (repo `lronetto-main`) via `mc cors set`.
### Postgres path-style URLs
`S3_FORCE_PATH_STYLE=true` é necessário pra MinIO. Sem isso, boto3 monta URL virtual-hosted (`bucket.endpoint/key`) que MinIO single-instance não suporta.
### Mudança em `.env` exige restart
Compose só lê env vars no boot do container. `make down-X && make up-X` após editar.
### TLS local em `*.localhost`
Caddy emite cert auto-assinado pelo root local. Browser pede pra aceitar (1x por subdomínio). Pra evitar prompts:
Pra produção, registros A pros subdomínios (`wedding`, `gitea`, `media`, `pgadmin`, `minio`) precisam estar propagados antes do Caddy tentar emitir cert. Senão ele entra em backoff e demora.
### `ACME_EMAIL` obrigatório em prod
Let's Encrypt requer email pra contato de renovação. Em dev pode ficar vazio (Caddy usa internal CA).
### Hairpin DNS no `wedding_app`
O `extra_hosts: host-gateway` pra `media.{DOMAIN_BASE}` faz o container resolver o subdomínio pro host. Sem isso, requests server-side (HEAD/DELETE/multipart complete) vão pra IP público → roteador → host → Caddy (lentidão). Com host-gateway: container → host → Caddy (rápido).
---
## 10. Histórico de iterações (sem detalhe — referência rápida)
1.**MVP Cloudflare**: Workers + D1 + R2 + Pages + Access. Funcionou mas Access não rola em `*.workers.dev`.
2.**Migração 1**: full Docker (Node/Hono + Postgres + MinIO + Caddy). Single compose, deploy num VPS.
3.**Migração 2**: backend reescrito em Python (FastAPI + SQLAlchemy + boto3 + pyjwt). Mesmo contrato de API. Frontend não mexeu.
4.**HEIC + backup**: pillow-heif no `/confirm`, 2 sidecars de backup (Postgres + MinIO mirror).
5.**Reorganização em 3 stacks**: `infra/{main,gitea,wedding_photo}` no monorepo `wedding-app`, compartilhando `infra-net`. Caddy concentrado em `main/`.
6.**Deploy CI + rename main**: workflow Gitea Actions de deploy via SSH; branch renomeada pra `main`.
7.**Split em 3 repos**: `lronetto-main` + `lronetto-gitea` + `lronetto-wedding` (fresh start). Orquestrador no main, deploy CI no wedding. Monorepo `wedding-app` arquivado.
8.**Novas apps na plataforma**: `lronetto-finance` (open finance via Pluggy) e `lronetto-claudeweb` (Claude Code via web, com workers efêmeros em rede isolada). Ambas entraram no Makefile orquestrador; os snippets de Caddy/Postgres delas ainda não foram aplicados neste repo (§9).
| Nova app na rede | novo repo com `docker-compose.yml`, declarar `infra-net` como external, conectar a `postgres`/`redis`/`minio` por nome, e referenciar no Makefile orquestrador |
| Nova tela no front | `apps/web/src/routes/` + rota em `App.tsx` |
| Schema compartilhado front-back | duplica: Zod em `packages/shared/src/schemas.ts` (TS) + Pydantic em `apps/api/app/schemas/api.py` (Python). **Camelo nos dois** |
| Workflow CI no Gitea | `.gitea/workflows/*.yml` no repo alvo (sintaxe GitHub Actions) — runner já registrado. Ex.: deploy do app em `lronetto-wedding` |
---
## 12. Decisões deferidas (a fazer se necessário)
- **Thumbnails server-side**: galeria carrega imagens full-size. Pra otimizar: `sharp` no upload `/confirm` (ou um job async), salvar `thumbnail_key`. ~2h.
- **Export ZIP do admin**: streamed ZIP de todos os uploads. ~1h.
- **Rate limit em `/uploads/init`**: hoje sem limite. Vale colocar Redis-based se houver suspeita de abuso. ~1h.
- **Email aos noivos quando upload chegar**: Resend ou SMTP. ~2h.
- **Slideshow pra projetar na recepção**: tela `/slideshow` com auto-advance. ~30 min.
- **Custom domain do bucket público** (em vez de `media.X`): mais "branded". DNS + CNAME pro MinIO. ~15 min.
- **Pivot multi-tenant SaaS**: ver seção 1 — 2-4 semanas se valer a pena.
