# pi-grupo/aprova architecture

> Architecture diagram of the GitHub repository pi-grupo/aprova, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pi-grupo/aprova
- Repository: https://github.com/pi-grupo/aprova

## Overview

aPRova é um GitHub App para analisar mudanças de Pull Request em sandbox isolado, avaliar risco e produzir uma decisão auditável; o README ressalva que esta ainda é a fundação do produto. O fluxo principal vai do webhook à execução e avaliação pelo worker, com recibos assinados e publicação de resultados. A API também oferece consultas, verificação de recibos e ações remotas. O protótipo inclui visões gerais e fila de aprovação. O mapa usa chamadas visíveis nos trechos e relações descritas no README; subsistemas não amostrados aparecem apenas quando documentados, sem presumir suas ligações internas.

Main entry points: [`cmd/worker/main.go`](https://github.com/pi-grupo/aprova/blob/main/cmd/worker/main.go) (Worker), [`internal/worker/etapas.go`](https://github.com/pi-grupo/aprova/blob/main/internal/worker/etapas.go) (Etapas de análise), [`cmd/api/main.go`](https://github.com/pi-grupo/aprova/blob/main/cmd/api/main.go) (Servidor API), [`internal/api/webhooks.go`](https://github.com/pi-grupo/aprova/blob/main/internal/api/webhooks.go) (Webhooks PR)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrada["Entrada e API"]
  node_api["Servidor API<br/>[main.go]"]
  node_webhook["Webhooks PR<br/>[webhooks.go]"]
  node_consultas["Consultas de análise"]
  node_acoes["Ações remotas<br/>[contrato.go]"]
end

subgraph group_execucao["Análise e execução"]
  node_worker["Worker<br/>[main.go]"]
  node_etapas["Etapas de análise<br/>[etapas.go]"]
  node_sandbox["Sandbox multi-linguagem<br/>[etapas.go]"]
end

subgraph group_decisao["Risco e evidências"]
  node_gate["Regras de risco<br/>[regra.go]"]
  node_calibrador["Calibração histórica<br/>[calibrador.go]"]
  node_recibos["Recibos assinados<br/>[conteudo.go]"]
  node_verificador["Verificador de recibos<br/>[main.go]"]
  node_publicacao["Publicação no GitHub<br/>[publicador.go]"]
  node_textos["Textos de decisão<br/>[textos.go]"]
  node_sarif["Envio SARIF<br/>[envio.go]"]
end

subgraph group_persistencia["Dados e consultas"]
  node_postgres[("Repositório PostgreSQL<br/>[postgres.go]")]
  node_fila[("Fila de trabalho<br/>[fila.go]")]
end

subgraph group_interface["Interface de análise"]
  node_dashboard["Visão geral<br/>[visao-geral.ts]"]
  node_mapa["Mapa de calor<br/>[MapaDeCalor.tsx]"]
  node_celula["Lista da célula<br/>[ListaDaCelula.tsx]"]
  node_aprovacao["Fila de aprovação"]
end

node_github(("GitHub"))

node_github -->|"envia webhook"| node_webhook
node_webhook -->|"registra PR"| node_postgres
node_worker -->|"constrói motor"| node_etapas
node_worker -->|"cria pool"| node_fila
node_etapas -->|"executa testes"| node_sandbox
node_etapas -->|"avalia risco"| node_gate
node_etapas -->|"emite recibo"| node_recibos
node_worker -->|"configura calibração"| node_calibrador
node_worker -->|"configura publicação"| node_publicacao
node_publicacao -->|"formata decisão"| node_textos
node_worker -->|"configura SARIF"| node_sarif
node_sarif -->|"envia SARIF"| node_github
node_api -->|"registra rotas"| node_consultas
node_api -->|"configura repositório"| node_postgres
node_verificador -->|"verifica recibo"| node_recibos
node_dashboard -.->|"apresenta métricas"| node_mapa
node_mapa -->|"renderiza lista"| node_celula

click node_api "https://github.com/pi-grupo/aprova/blob/main/cmd/api/main.go"
click node_webhook "https://github.com/pi-grupo/aprova/blob/main/internal/api/webhooks.go"
click node_consultas "https://github.com/pi-grupo/aprova/blob/main/internal/api/consulta_analises.go"
click node_acoes "https://github.com/pi-grupo/aprova/blob/main/internal/acaoremota/contratotentativas/contrato.go"
click node_worker "https://github.com/pi-grupo/aprova/blob/main/cmd/worker/main.go"
click node_etapas "https://github.com/pi-grupo/aprova/blob/main/internal/worker/etapas.go"
click node_sandbox "https://github.com/pi-grupo/aprova/blob/main/internal/sandbox/python/etapas.go"
click node_gate "https://github.com/pi-grupo/aprova/blob/main/internal/calibracao/regra.go"
click node_calibrador "https://github.com/pi-grupo/aprova/blob/main/internal/calibracao/calibrador.go"
click node_recibos "https://github.com/pi-grupo/aprova/blob/main/internal/receipt/conteudo.go"
click node_verificador "https://github.com/pi-grupo/aprova/blob/main/cmd/verificar-recibo/main.go"
click node_publicacao "https://github.com/pi-grupo/aprova/blob/main/internal/publicacao/publicador.go"
click node_textos "https://github.com/pi-grupo/aprova/blob/main/internal/publicacao/textos.go"
click node_sarif "https://github.com/pi-grupo/aprova/blob/main/internal/sarif/envio.go"
click node_postgres "https://github.com/pi-grupo/aprova/blob/main/internal/repository/postgres.go"
click node_fila "https://github.com/pi-grupo/aprova/blob/main/internal/repository/fila.go"
click node_dashboard "https://github.com/pi-grupo/aprova/blob/main/design/prototipo/src/lib/visao-geral.ts"
click node_mapa "https://github.com/pi-grupo/aprova/blob/main/design/prototipo/src/componentes/MapaDeCalor.tsx"
click node_celula "https://github.com/pi-grupo/aprova/blob/main/design/prototipo/src/componentes/ListaDaCelula.tsx"
click node_aprovacao "https://github.com/pi-grupo/aprova/blob/main/design/prototipo/src/telas/FilaDeAprovacao.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_webhook,node_consultas,node_acoes toneBlue
class node_worker,node_etapas,node_sandbox toneAmber
class node_gate,node_calibrador,node_recibos,node_verificador,node_publicacao,node_textos,node_sarif toneMint
class node_postgres,node_fila toneRose
class node_dashboard,node_mapa,node_celula,node_aprovacao,node_github toneIndigo
```

## Components

### Entrada e API

- [Servidor API](https://github.com/pi-grupo/aprova/blob/main/cmd/api/main.go): `cmd/api/main.go`
- [Webhooks PR](https://github.com/pi-grupo/aprova/blob/main/internal/api/webhooks.go): `internal/api/webhooks.go`
- [Consultas de análise](https://github.com/pi-grupo/aprova/blob/main/internal/api/consulta_analises.go): `internal/api/consulta_analises.go`
- [Ações remotas](https://github.com/pi-grupo/aprova/blob/main/internal/acaoremota/contratotentativas/contrato.go): `internal/acaoremota/contratotentativas/contrato.go`

### Análise e execução

- [Worker](https://github.com/pi-grupo/aprova/blob/main/cmd/worker/main.go): `cmd/worker/main.go`
- [Etapas de análise](https://github.com/pi-grupo/aprova/blob/main/internal/worker/etapas.go): `internal/worker/etapas.go`
- [Sandbox multi-linguagem](https://github.com/pi-grupo/aprova/blob/main/internal/sandbox/python/etapas.go): `internal/sandbox/python/etapas.go`

### Risco e evidências

- [Regras de risco](https://github.com/pi-grupo/aprova/blob/main/internal/calibracao/regra.go): `internal/calibracao/regra.go`
- [Calibração histórica](https://github.com/pi-grupo/aprova/blob/main/internal/calibracao/calibrador.go): `internal/calibracao/calibrador.go`
- [Recibos assinados](https://github.com/pi-grupo/aprova/blob/main/internal/receipt/conteudo.go): `internal/receipt/conteudo.go`
- [Verificador de recibos](https://github.com/pi-grupo/aprova/blob/main/cmd/verificar-recibo/main.go): `cmd/verificar-recibo/main.go`
- [Publicação no GitHub](https://github.com/pi-grupo/aprova/blob/main/internal/publicacao/publicador.go): `internal/publicacao/publicador.go`
- [Textos de decisão](https://github.com/pi-grupo/aprova/blob/main/internal/publicacao/textos.go): `internal/publicacao/textos.go`
- [Envio SARIF](https://github.com/pi-grupo/aprova/blob/main/internal/sarif/envio.go): `internal/sarif/envio.go`

### Dados e consultas

- [Repositório PostgreSQL](https://github.com/pi-grupo/aprova/blob/main/internal/repository/postgres.go): `internal/repository/postgres.go`
- [Fila de trabalho](https://github.com/pi-grupo/aprova/blob/main/internal/repository/fila.go): `internal/repository/fila.go`

### Interface de análise

- [Visão geral](https://github.com/pi-grupo/aprova/blob/main/design/prototipo/src/lib/visao-geral.ts): `design/prototipo/src/lib/visao-geral.ts`
- [Mapa de calor](https://github.com/pi-grupo/aprova/blob/main/design/prototipo/src/componentes/MapaDeCalor.tsx): `design/prototipo/src/componentes/MapaDeCalor.tsx`
- [Lista da célula](https://github.com/pi-grupo/aprova/blob/main/design/prototipo/src/componentes/ListaDaCelula.tsx): `design/prototipo/src/componentes/ListaDaCelula.tsx`
- [Fila de aprovação](https://github.com/pi-grupo/aprova/blob/main/design/prototipo/src/telas/FilaDeAprovacao.tsx): `design/prototipo/src/telas/FilaDeAprovacao.tsx`

### Other components

- **GitHub**

## Connections

- GitHub → Webhooks PR: envia webhook (evidence: `README.md`)
- Webhooks PR → Repositório PostgreSQL: registra PR (evidence: `internal/api/webhooks.go`)
- Worker → Etapas de análise: constrói motor (evidence: `cmd/worker/main.go`)
- Worker → Fila de trabalho: cria pool (evidence: `cmd/worker/main.go`)
- Etapas de análise → Sandbox multi-linguagem: executa testes (evidence: `internal/worker/etapas.go`)
- Etapas de análise → Regras de risco: avalia risco (evidence: `internal/worker/etapas.go`)
- Etapas de análise → Recibos assinados: emite recibo (evidence: `internal/worker/etapas.go`)
- Worker → Calibração histórica: configura calibração (evidence: `cmd/worker/main.go`)
- Worker → Publicação no GitHub: configura publicação (evidence: `cmd/worker/main.go`)
- Publicação no GitHub → Textos de decisão: formata decisão (evidence: `internal/publicacao/textos.go`)
- Worker → Envio SARIF: configura SARIF (evidence: `cmd/worker/main.go`)
- Envio SARIF → GitHub: envia SARIF (evidence: `internal/sarif/envio.go`)
- Servidor API → Consultas de análise: registra rotas (evidence: `cmd/api/main.go`)
- Servidor API → Repositório PostgreSQL: configura repositório (evidence: `cmd/api/main.go`)
- Verificador de recibos → Recibos assinados: verifica recibo (evidence: `cmd/verificar-recibo/main.go`)
- Visão geral → Mapa de calor: apresenta métricas
- Mapa de calor → Lista da célula: renderiza lista (evidence: `design/prototipo/src/componentes/MapaDeCalor.tsx`)
