docs: Add comprehensive UML architecture documentation#223
Merged
Conversation
Adiciona docs/arquitetura-uml.md, documentação de arquitetura gerada por análise estática de todo o repositório (~299 .rs, ~407 .py, 5 .ts): - Mapa estrutural e fronteiras entre linguagens (sidecar HTTP + FFI PyO3 + República Constitucional pura-Rust via Σ) - 20 diagramas Mermaid validados: casos de uso, pacotes, componentes, 8 diagramas de classes por camada, 5 de sequência, 3 de atividades e implantação (Compose + k8s) - Notas de design por seção e análise de coesão/acoplamento com oportunidades de refatoramento priorizadas Registra o documento na navegação do MkDocs (Portal do Desenvolvedor). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019wEuw8HPQaDLGqfFQoNUQ4
…versais Adiciona docs/arquitetura-completa.md com 27 diagramas Mermaid validados, cobrindo todo o repositório a partir de análise estática do código: - C4 L1–L3: contexto, contêineres e componentes por serviço (gateway, API de governança, kernel, República Constitucional, SDKs) - Fluxos de dados: decisão via proxy, ciclo da evidência, threat-intel→política, auditoria de fairness (gRPC) - Máquinas de estado: negociação A2A, mandato constitucional, circuit breaker, appeal, reversibilidade de efeito - Segurança: cadeia de auth do gateway, hierarquia de chaves, isolamento multi-tenant, camadas criptográficas - Persistência, topologias de implantação (quickstart/compose/k8s/fly), pipeline de CI/CD e mapa de invariantes fail-secure - Índice de rastreabilidade arquivo → componente Registra o documento na navegação do MkDocs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019wEuw8HPQaDLGqfFQoNUQ4
…campo) Adiciona docs/mapa-de-dados/ — catálogo exaustivo de todos os dados que circulam no sistema (entrada, processamento intermediário e saída) em Rust, Python, TypeScript e HTML/JS, extraído por análise estática de todos os scripts: - 01 Kernel Rust: layouts de bytes (TechnicalEvidence 9632B, Finding 144B, LedgerEntry 384B, ScanContextFlags 64B, BiasDeclaration 512B), FFI wire - 02 Gateway + crates constitucionais: corpos HTTP por rota, AppState, FairnessAuditEvent, tokens lineares btv-core, tipos wire btv-types - 03 Governança Python (~90 módulos): dataclasses/enums/TypedDicts, esquema de payloads do DurableLedger - 04 API + Compliance: modelos Pydantic, esquemas SQLite, ROPA/FRIA/Art.20 - 05 Intelligence/Agentic/Core: LLM/SLM/NER/threat DTOs, negociação A2A, métricas Prometheus, observabilidade e segurança - 06 SDK TS/Python, integrações, MCP, dashboards, OpenAPI, agent-pdp - README: índice, método, panorama de fluxo, sinks de persistência e catálogo global consolidado de variáveis de ambiente Registra os documentos na navegação do MkDocs. Nenhum código foi alterado. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019wEuw8HPQaDLGqfFQoNUQ4
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019wEuw8HPQaDLGqfFQoNUQ4
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds a comprehensive architectural documentation file (
docs/arquitetura-uml.md) that provides a complete multi-language UML analysis of the BuildToValue governance system. The document includes detailed diagrams and explanations of the system's structure, components, and interactions across Rust, Python, and TypeScript codebases.Key Changes
New file:
docs/arquitetura-uml.md(~1535 lines)/v1/decidegateway flowUpdated:
mkdocs.ymlNotable Implementation Details
EthicalContextEngineimplementations, FFI bridge divergence)«entity»,«service»,«linear», etc.) consistently throughoutThis documentation serves as a reference for architecture review, refactoring planning, and onboarding of new contributors.
https://claude.ai/code/session_019wEuw8HPQaDLGqfFQoNUQ4