Diagrama C4 de Container (C2)

Este diagrama faz zoom no Invowk para mostrar seus containers internos - as principais aplicações, componentes e armazenamentos de dados que compõem o sistema.

observação

Na terminologia C4, "container" refere-se a uma unidade separadamente executável/implantável (não containers Docker). Como o Invowk é um único binário CLI, mostramos os principais componentes internos como containers lógicos.

Diagrama

Componentes Internos

Pontos de Entrada

Componente	Tecnologia	Responsabilidade
CLI Commands	Go/Cobra	Pontos de entrada para todas as interações do usuário: subcomandos cmd, init, config, module, tui, validate, completion, audit, agent

Motor Principal

Componente	Tecnologia	Responsabilidade
Command Service	Go	Serviço de domínio hexagonal (internal/app/commandsvc/) que orquestra a execução de comandos. Recebe requisições da CLI, coordena descoberta, validação, ciclo de vida SSH e despacho de runtime. Retorna resultados/erros tipados; adaptador CLI aplica renderização.
Command Adapters	Go	Adaptadores de infraestrutura (internal/app/commandadapters/) que implementam portas do serviço de comandos para acesso SSH ao host, construção do registro de runtimes, execução interativa, probes de dependências no host/runtime e adaptação do servidor de callback para o host.
Dependency Validator	Go	Domínio de validação de dependências (internal/app/deps/). Verifica dependências raiz, de comando e de implementação no host, além das dependências do runtime container selecionado dentro do container.
Execution Context Builder	Go	Seleção de runtime e construção do contexto de execução (internal/app/execute/). Produz o runtime selecionado e runtime.ExecutionContext; internal/app/commandsvc despacha por meio de runtime.Registry.
Discovery Engine	Go	Encontra diretórios invowkfile.cue e *.invowkmod com ordenação por precedência. Constrói árvore unificada de comandos.
Configuration Manager	Go/CUE	Carrega o arquivo global de config resolvido. Valida contra schema CUE.
CUE Parser	Go/cuelang	Implementa parsing em 3 etapas: compilar schema → unificar com dados → decodificar para structs Go. Fornece mensagens de erro ricas.
Module Resolver	Go	Usado por comandos de módulo como invowk module sync para resolver dependências baseadas em Git. Gerencia cache em ~/.invowk/modules/. Lida com lock files para reprodutibilidade.
Watch Engine	Go	Monitora o sistema de arquivos para mudanças. Aplica debounce nos eventos de mudança e dispara re-execução de comandos para o modo --ivk-watch.
Audit Scanner	Go	Varredura de segurança do sistema de módulos (internal/audit/). Detecta riscos de supply-chain, travessia de caminho, abuso de symlink e injeção de variáveis de ambiente. Suporta flag --llm para análise com LLM.
Agent Command Authoring	Go	Autoria de comandos assistida por LLM (internal/agentcmd/, internal/llm/). Renderiza prompts de agente, resolve backends LLM configurados, valida CUE gerado e aplica patches em invowkfile.cue.
LLM Config Resolver	Go	Resolvedor compartilhado (internal/app/llmconfig/) para defaults configurados, seleção explícita de provider, ajustes de API, requisitos de modelo e credenciais via ambiente.
LLM Provider Layer	Go	Adaptadores de provider (internal/auditllm/, internal/llm/) usados por auditoria e autoria de comandos para chamar providers CLI ou APIs compatíveis com OpenAI.

Runtimes

Componente	Tecnologia	Responsabilidade
Native Runtime	Go	Executa comandos via shell do host (bash/sh no Unix, PowerShell no Windows). Opção mais rápida.
Virtual-Sh Runtime	Go/mvdan-sh	Interpretador POSIX shell embutido. Inclui builtins u-root para portabilidade. Sem dependência de shell externo.
Virtual-Lua Runtime	Go/golua	Runtime Lua embutido com o harness de segurança virtual compartilhado.
Container Runtime	Go	Executa comandos dentro de containers Docker/Podman. Fornece isolamento e reprodutibilidade.

Infraestrutura de Container

Componente	Tecnologia	Responsabilidade
Container Engine Abstraction	Go	Interface unificada para Docker e Podman. Auto-detecta engine disponível com fallback.
Container Plan Policy	Go	Camada de política pura (internal/containerplan/) que resolve alvos de container efêmeros vs persistentes, nomes estáveis, origem dos nomes e comportamento de criação quando ausente para dry-run e execução em container.
Image Provisioner	Go	Cria camadas efêmeras de imagem contendo binário invowk e módulos necessários. Permite execução seamless em container.

Servidores

Componente	Tecnologia	Responsabilidade
SSH Server	Go/Wish	Servidor SSH baseado em token para callbacks container-para-host. Habilita funcionalidade enable_host_ssh.
TUI Server	Go/Bubble Tea	Servidor HTTP tratando requisições de componentes TUI de processos filhos. Habilita prompts interativos em qualquer runtime.
Server Lifecycle Base	Go	Máquina de estados compartilhada em internal/core/serverbase usada pelos servidores SSH e TUI para transições de ciclo de vida.
TUI Wire Protocol	Go	Vocabulário compartilhado de requisição/resposta em internal/tuiwire e nomes de variáveis INVOWK_TUI_* para componentes TUI delegados.

Armazenamentos de Dados

Armazenamento	Formato	Localização	Propósito
Config File	CUE	Caminho de config resolvido específico do SO	Preferências do usuário: engine de container, includes configurados, etc.
Invowkfiles	CUE	./invowkfile.cue, includes configurados	Definições de comandos com implementações
Modules	Diretórios	*.invowkmod/	Comandos empacotados com metadados invowkmod.cue
Module Cache	Sistema de Arquivos	~/.invowk/modules/	Módulos remotos buscados via Git em cache

Interações entre Componentes

Fluxo de Execução de Comandos

1. Usuário invoca invowk cmd <name>
2. CLI Commands recebe requisição, constrói uma requisição de serviço
3. Command Service orquestra o pipeline de execução
4. Discovery Engine encontra todos os comandos disponíveis
5. CUE Parser faz parsing de invowkfile.cue e arquivos de módulos
6. Command Service faz correspondência do comando, seleciona runtime, valida dependências
7. Runtime apropriado executa o comando
8. Para containers: Image Provisioner prepara o ambiente

Carregamento de Configuração

1. Configuration Manager verifica arquivo de config
2. CUE Parser valida contra schema
3. Valores de config influenciam seleção de runtime e comportamento

Resolução de Módulos

1. Discovery Engine lê apenas caminhos de módulos locais, irmãos, configurados e vendorizados
2. Module Resolver é usado por comandos de módulo como invowk module sync para verificar o cache, buscar do Git quando necessário e atualizar o lock file
3. Dependências usam o modelo explícito (toda dep transitiva deve ser declarada no invowkmod.cue raiz)
4. Comandos de módulos sincronizados e descobertos se tornam disponíveis

Fundamentos de Design

Por Que Quatro Runtimes?

Runtime	Caso de Uso	Trade-off
Native	Velocidade, recursos completos do shell	Dependente de plataforma
Virtual-Sh	Shell POSIX portátil, sem dependência de shell	Recursos de shell limitados
Virtual-Lua	Automação Lua portátil, sem dependência de instalação Lua	Apenas harness virtual; não é isolamento de processo
Container	Isolamento, reprodutibilidade	Overhead, apenas Linux

Por Que Servidores Separados?

• SSH Server: Permite que comandos dentro de containers chamem de volta o host (ex: para gerenciamento de secrets)
• TUI Server: Permite que qualquer subprocesso (native, virtual-sh, virtual-lua, container) solicite componentes de UI interativa
• Server Lifecycle Base: Mantém consistentes as transições de start/stop/falha dos servidores SSH e TUI
• TUI Wire Protocol: Mantém estáveis as requisições e respostas TUI delegadas entre runtimes

Por Que CUE para Configuração?

• Validação de schema integrada
• Verificação de tipos antes do runtime
• Configurações combináveis
• Mensagens de erro melhores que YAML/JSON

Diagramas Relacionados

• Diagrama C4 de Contexto (C1) - Limites do sistema e atores externos
• Sequência de Execução de Comando - Fluxo temporal da execução de comandos
• Fluxograma de Seleção de Runtime - Como runtimes são escolhidos
• Fluxograma de Precedência de Descoberta - Como comandos são descobertos