ARKHE

Arquitetura como modelo executável - não como desenho.

Você descreve o sistema em texto. O ARKHE compila esse texto num modelo verificado: reprova
o build no CI quando a arquitetura quebra uma regra, calcula SLO por caminho crítico direto
da fonte, liga o modelo a decisões (ADR) e detecta deriva entre o modelo e o código real. O
portal auto-hospedado, os diagramas, o Mermaid e o editor no browser são apenas visões
derivadas do mesmo modelo.

_{O mesmo compilador roda no CI, no editor (LSP) e no browser (WebAssembly) - a prévia nunca diverge do arkhe check.}

Novo por aqui? O guia de 5 minutos coloca uma regra de arquitetura reprovando o CI - sem você modelar o sistema inteiro.

O portal

Um binário Go único embarca um SPA (React + React Flow) e serve um portal de arquitetura
multi-org: conecte suas orgs do GitHub, e o ARKHE varre os .arkhe de todos os repos e monta
o catálogo verificado, o landscape C4 navegável, o painel de governança e um editor ao vivo.

Landscape C4 com drill-in. O nível de contexto mostra só o essencial - ator, frontend e
backend, com as dependências externas alinhadas embaixo. Um clique entra no sistema e revela
seus componentes internos (gateway, serviços, banco), com breadcrumb para voltar. Escala de
dois serviços a uma arquitetura estilo Netflix sem virar um emaranhado.

Governança: o modelo executável, não um diagrama parado. Fitness functions (políticas)
passando ou reprovando, SLO por caminho crítico medido contra o orçamento, contratos e ADRs -
tudo recalculado a cada varredura.

Editor ao vivo, split de código. Crie e edite .arkhe dentro da plataforma: o mesmo
compilador do CI roda no browser via WebAssembly, o diagrama e os diagnósticos se atualizam a
cada tecla, e a prévia nunca diverge do arkhe check.

Catálogo verificado. Cada repositório com seus KPIs, dono, criticidade, stack e devs
principais - derivado do .arkhe e enriquecido com sinais do GitHub, não de um YAML paralelo
que apodrece.

docker compose up -d           # sobe portal + Caddy (TLS); persistência em SQLite por padrão

Por que existe

Uma pesquisa do mercado (Structurizr, LikeC4, D2, Ilograph, Backstage, C4-PlantUML) apontou um
nicho que ninguém entrega num único artefato de texto:

• Fitness functions são construtos da linguagem, não testes em outra ferramenta. arkhe check
  reprova o build como um type-check que falha.
• Relações tipadas com contrato: protocolo, sync/async/stream, classe de dado, SLO.
• SLO estático calculado da fonte: latência por caminho crítico e disponibilidade composta em
  série, sem runtime.
• Deriva modelo-vs-código (arkhe sync) com veredito convergente/divergente/ausente e baseline
  (ratchet), para o modelo não apodrecer.
• ADR e depreciação com prazo que vira erro na data.

Instalação

go build -o arkhe ./cmd/arkhe
go build -o arkhe-lsp ./cmd/arkhe-lsp

Requer Go 1.26 ou superior. Sem dependências externas.

Uso

arkhe check    examples/ecommerce.arkhe              # valida; sai com 1 se houver erro (CI)
arkhe fmt      examples/ecommerce.arkhe -w           # formata no estilo canônico (preserva comentários)
arkhe json     examples/ecommerce.arkhe              # modelo semântico resolvido
arkhe mermaid  examples/netflix.arkhe play           # diagrama Mermaid de uma visão
arkhe html     examples/ecommerce.arkhe -o out.html  # explorador interativo, arquivo único
arkhe sync     examples/westack.arkhe --go examples/godemo   # deriva modelo-vs-código
arkhe playground                                     # editor ao vivo no browser (WASM)

O caminho pode ser um arquivo .arkhe ou um diretório (carrega todos e segue os import). No CI,
a arquitetura vira teste:

- run: ./arkhe check arquitetura/

SLO calculado da fonte

Fora do portal, o arkhe html também gera um explorador de arquivo único (~50 KB, sem CDN) com
layout automático em camadas, roteamento ortogonal, zoom com drill-in, arestas tipadas por cor
e um painel de código-fonte. A reprodução de fluxo mostra o waterfall de latência de cada passo
contra o orçamento - se o checkout estoura o orçamento, o check reprova o build.

Playground ao vivo (CLI)

arkhe playground   # código à esquerda, diagrama à direita

A mesma experiência do editor do portal, standalone: estilo Mermaid Live Editor, mas com o
mesmo compilador do CI rodando no browser via WebAssembly. A prévia nunca diverge do
arkhe check; os diagnósticos e o SLO se atualizam a cada tecla.

Federação: o landscape da org

Um .arkhe por repositório. Cada projeto modela seu próprio C4 e declara o que expõe
(expose), de quem depende (depends) e a que workspace pertence (workspace). O ARKHE
agrega todos num único grafo verificado - o landscape da organização - onde os projetos se
agrupam em workspaces (times/domínios), cada projeto é uma caixa navegável, e as arestas
conectam as dependências reais dentro e entre workspaces. Como um catálogo estilo Backstage,
mas verificado: políticas org-wide reprovam violações que cruzam repositórios.

arkhe scan   ./repos               # agrega os .arkhe de vários projetos (landscape federado)
arkhe server --root ./repos        # serve o landscape ao vivo (Structurizr-in-Docker)
arkhe server --github minha-org --token $GH_TOKEN   # varre todos os repos de uma org

Cada projeto declara seu workspace, sua superfície e suas dependências:

meta { id "orders" }
depends checkout

system orders "Pedidos" {
  workspace "comercio"                 # agrupa o projeto no landscape
  expose service api "Orders API"      # público: outros projetos podem referenciar
  service worker "Worker"              # interno: encapsulado
}

orders.api -> checkout.api "inicia checkout"   # aresta cross-projeto

A verificação atravessa os repos: LNK001 (depende de projeto inexistente), LNK002
(referencia um nó não exposto de outro projeto), LNK003 (dependência cross-projeto que não
resolve). Rode em Docker com docker run -v ./repos:/data -p 8080:8080 arkhe, ou instale como
GitHub App (auth via --app-id/--key/--installation) com webhook em /webhook para
atualizar no push.

Catálogo: cada nó é uma entidade

O nó carrega os metadados de catálogo que os times de plataforma cobram - dono, criticidade,
centro de custo, tipo e ciclo de vida - e a verificação cobra higiene: um sistema crítico sem
dono reprova (CAT001), valores inválidos avisam (CAT002/CAT003). O catálogo é derivado do
.arkhe verificado, não de um YAML paralelo que apodrece.

system pagamentos "Pagamentos" {
  owner       "@acme/plataforma"
  criticality critical            # critical | high | medium | low
  costcenter  "CC-1001"
  type        service
  lifecycle   production          # production | experimental | deprecated
}

Para não escrever do zero, arkhe init gera um rascunho a partir dos sinais reais do repo no
GitHub (descrição, linguagens, topics, CODEOWNERS, OpenAPI) - o time revisa e commita:

arkhe init acme/service-pagamentos -o service-pagamentos.arkhe
arkhe check service-pagamentos.arkhe          # o rascunho já passa na verificação

Rodando o portal

No primeiro acesso o portal pede para criar o administrador; depois é só conectar uma org
(GitHub App ou token) e ele varre os .arkhe de todos os repos, montando catálogo, landscape,
governança e editor. A fonte da verdade continua no código: tudo é derivado dos .arkhe dos
repositórios.

docker compose up -d           # sobe portal + Caddy (TLS); persistência em SQLite por padrão

A persistência é SQLite (zero-config, num volume), que dá conta da carga de um catálogo
(leitura pesada, escrita só nos scans); para Postgres, suba com --profile postgres e aponte
DATABASE_URL. Sem Docker, o binário sozinho também serve o portal:

arkhe server --db ./arkhe.db --port 8080

Copie .env.example para .env para configurar domínio (TLS automático via Caddy), GitHub App
e segredo de webhook.

A linguagem em 30 segundos

kind agent { shape hex }

contract AgentTask { taskId string  channel string  payload json }

person cliente "Cliente"

system westack "Escritório Virtual" {
  scope internal
  gateway edge "Edge / BFF"           { tech "Next.js" source "westack/svc/edge" }
  service orquestrador "Orquestrador"  { source "westack/svc/orquestrador" }
  broker  barramento "Barramento"      { tech "NATS" }
  agent   sac "Agente SAC"             { status experimental source "westack/svc/sac" }
  store   memoria "Memory Layer"       { tech "Redis" tag pii }
}

cliente -> westack.edge "abre"                 { p50 40ms p99 90ms availability 99.9 }
westack.edge -> westack.orquestrador "cria"    { proto gRPC p99 60ms availability 99.95 }
westack.orquestrador ~> westack.barramento "evt" {
  contract AgentTask
  delivery at-least-once
  p99 15ms
}

flow "atendimento" {
  budget 600ms
  availability 99.5
  cliente               -> westack.edge         "clica"
  westack.edge          -> westack.orquestrador  "CreateTask"
  westack.orquestrador  ~> westack.barramento    "publica"
}

policy "a borda não toca dados sensíveis" { forbid westack.edge -> tag:pii }
policy "agente sempre por evento"         { require * -> kind:agent as async }

decision "adr-002" { status accepted  affects westack.barramento }

deployment prod "Produção GCP" {
  node gke "GKE Autopilot"
  place westack.edge on gke { replicas 3 }
}

view interno { title "Dentro do WeStack"  of westack  depth 2 }

A visão conceitual está em docs/LINGUAGEM.md; a gramática formal em EBNF,
em docs/GRAMATICA.md.

Ecossistema

Deriva modelo-vs-código (arkhe sync)

arkhe sync modelo.arkhe --go ./src --asyncapi ./specs --openapi ./specs --baseline drift.json

• --go: grafo de imports Go (arestas síncronas).
• --asyncapi: canais publish/subscribe (arestas de evento que imports não veem).
• --openapi: verifica endpoints declarados contra as rotas realmente expostas.

Cada aresta recebe um veredito convergente/divergente/ausente. --baseline aplica um ratchet:
só deriva nova reprova o build.

Exemplos de escala real

• examples/ecommerce.arkhe: marketplace estilo Amazon (37 nós, bounded contexts DDD, contratos,
  deployment multirregião). Reprova de propósito em SLO001 (orçamento) e AVL001/AVL004
  (disponibilidade e domínio de falha compartilhado us-east-1).
• examples/netflix.arkhe: streaming estilo Netflix (Open Connect, Zuul, playback, DRM, pipeline
  Kafka). Passa dentro do orçamento, com avisos de depreciação (Hystrix) e domínio de falha.
• examples/c4-banking.arkhe: o exemplo canônico do C4 (Internet Banking), navegável por camadas
  contexto / container / componente.

Arquitetura do interpretador

Layout idiomático de Go, seguindo a convenção da stdlib (go/token, go/scanner, go/ast, go/parser,
go/types):

cmd/arkhe/          binário CLI (check, fmt, json, mermaid, html, sync, playground)
cmd/arkhe-lsp/      servidor Language Server (stdio)
cmd/arkhe-mcp/      servidor MCP para agentes (stdio)
cmd/arkhe-wasm/     mesmo compilador em WebAssembly (playground no browser)
internal/
  token/            tipos de token e posições
  lexer/            scanner
  ast/              árvore sintática
  parser/           parser recursivo-descendente
  format/           formatter canônico (arkhe fmt)
  diag/             diagnósticos
  model/            modelo semântico e resolvedor de nomes qualificados
  check/            fitness functions (validação)
  slo/              confiabilidade (caminho crítico, disponibilidade, domínio de falha)
  drift/            deriva modelo-vs-código (Go, AsyncAPI, OpenAPI)
  render/           json, mermaid, html, engine.js (diagrama) e playground (WASM)
  loader/           carga multiarquivo com import
  lsp/              lógica do Language Server
  mcp/              lógica do servidor MCP (consulta da arquitetura)

O playground embute internal/render/arkhe.wasm. Regenere-o com make wasm sempre que o
interpretador mudar.

Testes

go test ./...

Cobrem resolução de nomes qualificados, merge multiarquivo, cada código de diagnóstico, o motor de
SLO (caminho crítico, disponibilidade, domínio de falha), os vereditos de deriva das três fontes, o
formatter e o Language Server.

Licença

MIT © Vinicius Azevedo.