Skip to content

Documento de arquitetura da plataforma - #143

Merged
tecrodrigocastro merged 3 commits into
mainfrom
docs/arquitetura
Nov 19, 2026
Merged

tecrodrigocastro merged 3 commits into
mainfrom
docs/arquitetura

Conversation

@tecrodrigocastro

Copy link
Copy Markdown
Member

Closes #142

Documento visual de como a plataforma funciona, no estilo do documento de arquitetura do RideApp: A4 paisagem, diagramas em SVG gerados por script e PDF versionado. As cores são as do tema Sertão.

docs/arquitetura/PHPeste_Arquitetura.pdf (18 páginas)

Página Conteúdo
1 Capa, resumo em cinco pontos e legenda
2 Visão geral: painel, site, site próprio, Caddy, API, Horizon, scheduler, MySQL, Redis, gateways, Resend, GitHub, Sentry
3 Tenancy: o que é global (users, perfis de palestrante), o que é da comunidade (fornecedores) e o que é da edição, e como o isolamento é garantido
4 Como uma requisição encontra a edição: apiV1Edition, apiV1PublishedEdition, rotas públicas e de máquina, jobs, eventos, resolução pelo host
5 Ciclo de vida da edição: estados, o que cada um libera e bloqueia, guards, quem reage, clonagem, Visão geral
6 Os 15 módulos, com rotas de cada um e quais ainda são casca
7 Como os módulos conversam: contratos e pontos de extensão por tag
8 Banco por domínio: as 65 tabelas
9 Papéis × permissões
10 Ingresso: da compra ao QR (pedido, cobrança, webhook, job, emissão, rotinas)
11 CFP: da proposta à grade
12 Dinheiro: patrocínio, fornecedores e finanças
13 Fila, rotinas agendadas, e-mail e auditoria
14 Segurança
15 Desenvolvimento, CI e deploy
16 Telas: design do painel (docs/design/)
17 Telas: o painel em uso (capturas reais)
18 Onde estamos e o que falta, por marco

Como é gerado

  • docs/arquitetura/fonte/gerar.py escreve arquitetura.html, e imprimir.mjs gera o PDF com o Chromium do Playwright do front-admin. Com uma pasta como argumento, salva também um PNG de cada página, para revisar o layout.
  • Os prints do painel saem de front-admin/e2e/capturas-arquitetura.spec.ts. É um spec que só roda com CAPTURAR_TELAS=1, com a API simulada como nos outros e2e, e fica pulado no npm run test:e2e normal.
  • O README do documento explica como regenerar e traz os comandos que conferem os números contra o código: tabelas, rotas e contratos.

Manter atualizado

  • backend/CLAUDE.md ganhou a seção "Documento de arquitetura": todo PR que muda a arquitetura atualiza o documento no mesmo PR. Isso vale para módulo, tabela, contrato, permissão, rotina, serviço externo ou fluxo.
  • Os CLAUDE.md do front-admin e do front-public ganharam a mesma instrução, aplicada a telas e à integração com a API.
  • O README.md da raiz linka o documento e os ADRs.

O que não entrou

O protótipo de design linkado no README é um artifact do claude.ai. Ele não renderiza fora do navegador logado, então não consegui tirar print dele. A página 16 usa as duas imagens de design que já estão no repositório e aponta para o protótipo.

Test plan

  • As 18 páginas foram conferidas uma a uma no PNG gerado: sem texto cortado nem sobreposto.
  • Números conferidos contra o código: 65 tabelas, 247 rotas na API, 24 contratos, 21 eventos auditados, 8 rotinas agendadas, 12 permissões.
  • Lint (eslint) e nuxt typecheck do front-admin passam com o spec novo.

18 páginas em A4 paisagem geradas por docs/arquitetura/fonte/gerar.py:
visão geral, tenancy por edição, caminho da requisição, ciclo de vida
da edição, módulos e contratos, banco por domínio, papéis, fluxos de
ingresso, CFP e dinheiro, operação, segurança, CI e telas. Os prints do
painel saem de um spec Playwright que só roda com CAPTURAR_TELAS=1.
@tecrodrigocastro tecrodrigocastro self-assigned this Nov 19, 2026
@tecrodrigocastro
tecrodrigocastro merged commit d250d72 into main Nov 19, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Documento de arquitetura da plataforma

1 participant