Pular para conteúdo

ADR-0003 — Ambiente local em origem única, roteado por path

Contexto

Um ambiente de desenvolvimento local com múltiplos serviços (frontend, API, documentação técnica, e-mail de teste) precisa decidir como cada um fica endereçável: domínios .test separados com certificado local, portas distintas, ou uma origem única com roteamento por path.

Decisão

Uma origem única, roteada por path: o Caddy serve HTTP puro na :8080, e o ambiente é http://localhost:8080 — sem domínios .test, sem certificado local, sem entrada em /etc/hosts. /app é o frontend (Vite com base: "/app/"), /api/v1/... é a API, /api/docs é o Swagger, /wiki é a documentação técnica (Sphinx), /mail é o Mailpit.

Revisado em 2026-09-17: o TLS saiu, a decisão ficou. Até esta data o tailscale serve publicava a :8080 no tailnet com certificado, e o ambiente era https://oto.tail10981f.ts.net. A camada saiu por desuso. Nada do que esta decisão justifica dependia dela — a origem única, a ausência de CORS e o roteamento por path são do Caddy, não do TLS; e localhost é origem segura para o browser, então service worker, PWA e clipboard seguem funcionando. O que se perdeu está na consequência negativa abaixo.

Alternativas consideradas

  • Domínios .test locais com certificado próprio — exige gerar e confiar num CA local por máquina de desenvolvedor, e não elimina CORS entre frontend e API se forem origens diferentes.
  • Portas distintas sem proxy (:5173 para o web, :8000 para a API) — reintroduz CORS, e o comportamento de path deixa de espelhar produção (que também roteia por path/origem única).

Consequências positivas

  • Sem CORS: o frontend chama /api/v1/... relativo, mesma origem, em todos os ambientes (local, dev-remote, produção) — API_URL é "" por padrão.
  • O comportamento de roteamento por path é o mesmo em desenvolvimento e em produção, reduzindo surpresa entre ambientes.

Consequências negativas

  • Cada serviço precisa saber o próprio prefixo (a API registra rotas sob /api/v1, o Vite usa base: "/app/", o Mailpit usa MP_WEBROOT) — mexer em vite.config.ts ou no roteador sem preservar essa base tira a aplicação do ar sob o proxy.
  • O proxy não remove o prefixo (exceto para /wiki), então essa regra precisa ser lembrada toda vez que uma rota nova é adicionada a um dos serviços.
  • A stack local não é alcançável de outro aparelho (desde 2026-09-17). Enquanto havia o tailnet, abrir o ambiente num celular de verdade era imediato e sem instalar CA nenhuma; hoje a conferência de mobile é por emulação de largura, que é o que o e2e e os scripts de screenshot já fazem em 375px. Reverter é reintroduzir dois alvos no Makefile, que o histórico do git guarda.

Riscos

Esquecer a base de path ao adicionar rota nova é o erro mais provável — mitigado documentando a regra em CLAUDE.md da raiz, seção "Ambiente local".

Status

aceita.

Documentos relacionados

CLAUDE.md da raiz, seção "Ambiente local"; ../architecture/deployment.md.