Visão Geral da Arquitetura

Esta seção contém diagramas do modelo C4 e documentação arquitetural suplementar para o Invowk. Esses diagramas ajudam desenvolvedores a entender a estrutura do sistema, fluxos de execução e decisões de design.

Visão Geral dos Diagramas

Diagrama	Tipo	Propósito
C4 Contexto (C1)	Modelo C4	Limites do sistema, usuários, sistemas externos
C4 Container (C2)	Modelo C4	Componentes internos e armazenamentos de dados
C4 Componente: Runtime (C3)	Modelo C4	Estrutura interna do pacote runtime
C4 Componente: Container (C3)	Modelo C4	Estrutura interna do pacote container
Execução de Comandos	Sequência	Fluxo temporal do CLI até a execução
Seleção de Runtime	Fluxograma	Árvore de decisão para escolha do runtime
Precedência de Descoberta	Fluxograma	Como comandos são encontrados e conflitos resolvidos

Ordem de Leitura

Para novatos na base de código:

1. Comece com C4 Contexto — Entenda o que é o Invowk e com o que ele interage
2. Então C4 Container — Veja os principais componentes internos
3. Opcionalmente explore Componentes de Runtime ou Componentes de Container — Aprofunde-se em pacotes com estrutura interna complexa
4. Leia Execução de Comandos — Siga a jornada principal do usuário
5. Consulte outros conforme necessário — Seleção de runtime e descoberta para debugging ou extensões

Tecnologia dos Diagramas

Todos os diagramas usam sintaxe D2. D2 é uma linguagem moderna de diagramação que compila definições de texto em SVG, tornando-os fáceis de versionar e manter.

Editando Diagramas

O D2 Playground é útil para testar alterações antes de commitar. Localmente, execute make render-diagrams para regenerar os renders SVG a partir dos fontes D2.

Contexto do Modelo C4

O modelo C4 fornece uma forma hierárquica de descrever arquitetura de software:

Nível	Nome	Descrição
C1	Contexto	Sistema como caixa preta com atores externos
C2	Container	Principais unidades implantáveis/executáveis
C3	Componente	Módulos internos dentro dos containers
C4	Código	Detalhes em nível de classe/código

Para o Invowk (um único binário CLI), C1 e C2 são mais valiosos. Diagramas C3 (Componente) são fornecidos seletivamente para pacotes cuja estrutura interna é genuinamente complexa — especificamente internal/runtime/ (segregação de interfaces, padrão registry, 3 implementações) e internal/container/ (composição via embedding, padrão decorator, opções funcionais). Outros pacotes têm estrutura simples o suficiente para que a documentação no código seja suficiente.

Mantendo Diagramas Atualizados

Ao fazer mudanças arquiteturais significativas:

1. Verifique se diagramas precisam de atualização — Novos componentes, relacionamentos alterados, funcionalidades removidas
2. Atualize o(s) diagrama(s) relevante(s) — Mantenha as mudanças focadas
3. Verifique a renderização — Execute make render-diagrams ou teste no D2 Playground
4. Atualize tabelas e texto — Diagramas sozinhos podem não capturar todo o contexto