Arquitetura conceitual

Modelo mental dos componentes, fluxo de uma request e os princípios de design.

Modelo mental

O IronShell é uma camada enterprise montada em cima do Claude Code. Ele não reimplementa o agente — ele intercepta, audita e estende o que o Claude Code já faz. Pense em cinco grandes componentes conceituais, cada um com uma responsabilidade única e bem delimitada.

1. Kernel de segurança — audita cada ação antes de executar.
2. Memória persistente — guarda episódios, conhecimento e contexto em três camadas.
3. Sistema de agentes — dispara especialistas para tarefas específicas.
4. Orquestrador — coordena missões DAG com dependências e idempotência.
5. Executor isolado — compila e roda código em sandbox, com resiliência automática.

Cada um desses componentes é substituível individualmente. Nenhum deles depende do estado interno dos outros — a comunicação é via eventos bem definidos. Essa separação permite trocar um componente por uma implementação custom (por exemplo, uma memória externa em Postgres) sem reescrever o resto.

Componentes principais

Kernel de segurança

O kernel é a primeira e a última camada de defesa. Ele recebe qualquer comando, prompt, código ou tool call, normaliza o input, aplica 132 padrões de detecção e retorna um objeto estruturado com o risk score, o risk level e a razão da decisão.

Três propriedades o tornam diferente de um middleware:

• Sempre executado — nenhuma ferramenta do sistema pode ser instanciada sem invocar o kernel. É propriedade arquitetural, não política configurável.
• Contínuo — o risk score vai de 0 a 100, não é binário. Aplicações podem definir seu próprio threshold, mas o padrão de blocked em 70 nunca é contornável.
• Local — nenhum dado é enviado para fora da máquina para a decisão de bloqueio. Tudo acontece em memória, em menos de um microssegundo por chamada.

Memória persistente

A memória é organizada em três camadas, cada uma com um ciclo de vida diferente.

• Memória episódica — eventos da sessão corrente, indexados por timestamp e tópico, com circuit breaker contra crescimento descontrolado. Roda em SQLite WASM dentro do processo, sem depender de servidor externo.
• Knowledge Graph — entidades, relações e snippets de código cristalizados automaticamente quando passam no teste do kernel. A busca é via BM25-lite com boost por frequência de uso. Episódios inativos por 90 dias e usados menos de 3 vezes são podados automaticamente.
• Workspace RAG — busca híbrida BM25 + Jaccard + Reciprocal Rank Fusion sobre documentos do projeto. Permite que o agente encontre referências cruzadas sem ter que ler arquivos aleatoriamente.

Essas três camadas coexistem no mesmo processo, com circuit breakers independentes. Se a memória episódica corromper, o Knowledge Graph continua funcional. Se o RAG falhar, o agente ainda tem contexto recente. Nada é monolítico.

Sistema de agentes

O agente principal é coordenado por um loop que chamamos de agent loop. Ele constrói o system prompt, chama o LLM, parseia as tool calls, passa cada uma pelo kernel, executa as autorizadas e realimenta o modelo com o resultado. Tudo isso em microssegundos por ciclo.

Em cima desse loop, há um time de 6 agentes especializados que podem ser invocados explicitamente:

• @dev — implementação
• @qa — validação e testes
• @architect — decisão de design
• @pm — priorização e escopo
• @analyst — análise de dados e logs
• @sm — scrum master e orquestração

Quando uma decisão crítica precisa ser tomada (por exemplo, deploy em produção), o sistema de consenso entra em cena: os agentes votam, cada voto é registrado com assinatura digital, e só ações com quórum 2/3 passam. Isso não é cosmético — é um gate real, integrado no fluxo.

Orquestrador

Para tarefas que têm dependências entre passos, o orquestrador executa missões como DAGs. Cada passo declara pré-requisitos, timeout e política de erro (fail, skip, continue). O orquestrador faz a ordenação topológica, detecta ciclos, aplica idempotência por chave, e expõe o estado da missão em tempo real.

Exemplos típicos de missão: pipeline de deploy (build → test → push), refactor multi-arquivo com review em paralelo, ingestão de dataset com chunking e embeddings.

Executor isolado

Quando o agente precisa rodar código novo — código que não existe no projeto, que ele está propondo na hora — o executor compila e executa em um sandbox V8 estrito. O sandbox tem acesso apenas a primitivas (Math, Number, String, Boolean, Array, Object, JSON, Date). Não há process, não há fs, não há require. O timeout é de 5 segundos.

Se o código falha, entra em cena o self-healing loop: ele classifica o erro, aplica uma heurística de correção (adicionar null check, corrigir import, etc.), e tenta de novo. Até 3 iterações. Erros de segurança bloqueados pelo kernel são terminais — nunca se tenta novamente um código que o kernel barrou.

Execuções bem-sucedidas são cristalizadas no Knowledge Graph com tags semânticas, para que o próximo pedido similar possa reaproveitar o snippet sem gerar do zero.

Fluxo de uma request

O diagrama abaixo é uma descrição conceitual. Ele omite detalhes de implementação e foca no caminho crítico de uma request.

┌────────────────────────────────────────────────────────────────┐
│  1. Usuário envia mensagem ou comando                          │
│     via CLI, REST, canal (Telegram, Slack) ou dashboard        │
└───────────────────┬────────────────────────────────────────────┘
                    │
                    ▼
┌────────────────────────────────────────────────────────────────┐
│  2. Pré-auditoria do input                                     │
│     Normalização Unicode (NFKC) → strip ANSI → remove evasões  │
│     NanoShield analisa o input do usuário antes de chegar ao LLM│
│     Se risk score >= 70: bloqueia, retorna 403 estruturado     │
└───────────────────┬────────────────────────────────────────────┘
                    │ input limpo
                    ▼
┌────────────────────────────────────────────────────────────────┐
│  3. Construção do contexto                                     │
│     Memória episódica recente + Knowledge Graph relevante      │
│     + Workspace RAG + system prompt + skills disponíveis       │
└───────────────────┬────────────────────────────────────────────┘
                    │ contexto completo
                    ▼
┌────────────────────────────────────────────────────────────────┐
│  4. Chamada ao provedor LLM                                    │
│     SmartRouter escolhe entre 14 provedores por economia/      │
│     velocidade/qualidade. IronBudget verifica saldo antes.     │
│     Se o provedor primário falha, failover automático.         │
└───────────────────┬────────────────────────────────────────────┘
                    │ response com tool calls
                    ▼
┌────────────────────────────────────────────────────────────────┐
│  5. Parse das tool calls + auditoria                           │
│     Cada tool call passa pelo NanoShield individualmente       │
│     Se algum tool call tem risk score >= 70:                   │
│       → bloqueia, sinaliza peers via imunidade coletiva        │
│       → registra no audit log HMAC-encadeado                   │
│       → retorna ao LLM com mensagem de bloqueio                │
└───────────────────┬────────────────────────────────────────────┘
                    │ tool calls aprovadas
                    ▼
┌────────────────────────────────────────────────────────────────┐
│  6. Execução                                                   │
│     Tool calls de shell rodam via IronPTY (sessão auditada)    │
│     Tool calls de código novo rodam via executor sandbox V8    │
│     Tool calls de skill externa passam por skill runner        │
│     Cada execução com timeout configurável                     │
└───────────────────┬────────────────────────────────────────────┘
                    │ resultado
                    ▼
┌────────────────────────────────────────────────────────────────┐
│  7. Pós-auditoria do output                                    │
│     Scanner de leak (credenciais, tokens, PEM, JWT)            │
│     Guard semântico (anti-alucinação, anti-especulação)        │
│     Se detecta leak: redige ou bloqueia antes de devolver      │
└───────────────────┬────────────────────────────────────────────┘
                    │ output limpo
                    ▼
┌────────────────────────────────────────────────────────────────┐
│  8. Persistência + entrega                                     │
│     Episódio cristalizado na memória episódica                 │
│     Se execução foi de código novo: cristaliza no KG           │
│     Audit log encadeado (HMAC chain) é apendado                │
│     Resposta final chega ao usuário                            │
└────────────────────────────────────────────────────────────────┘

A latência total de um turno com comando seguro fica na faixa de 500 ms a 2 s, dominada pela chamada ao LLM. A sobrecarga do IronShell (auditoria, memória, audit log) é menor que 1 ms por turno.

Princípios de design

Os componentes acima seguem cinco princípios que não são negociáveis no core do projeto.

Zero-trust por padrão

Nenhum LLM é confiável. Nenhum tool call é permitido sem auditoria. Nenhum input de usuário chega ao LLM sem passar pelo kernel. O default é bloqueio; a exceção é explícita e logada.

Falha segura

Quando um componente falha, o sistema falha fechado, não aberto. Se o kernel de segurança não consegue decidir, a ação é bloqueada. Se a memória corrompe, o agente continua sem contexto mas não executa ações arriscadas. Se o provedor LLM não responde, o SmartRouter tenta outro; se todos falham, o turno é abortado com erro claro.

Determinismo onde possível

A parte do sistema que não depende do LLM é determinística. O mesmo input gera o mesmo risk score, sempre. O mesmo comando shell é bloqueado pelo mesmo padrão, sempre. Isso permite testes reprodutíveis e audit trails verificáveis.

Cobertura de testes obrigatória

O IronShell atual tem 4.307 testes em 199 arquivos com cobertura de 97,98% em statements e 100% em funções. Nenhum PR que reduza esses números é aceito. Features novas precisam vir com testes antes do merge — o próprio projeto é desenvolvido em TDD.

Sem mutação de estado global

Dados são tratados como imutáveis. Updates criam novas cópias. Isso simplifica debugging, permite time-travel em audit logs, e elimina bugs de concorrência.

Integração com o Claude Code

Decisão arquitetural: o IronShell é um runtime separado que extende o comportamento oficial do Claude Code sem modificar o executável base. Cada release oficial do Claude Code passa por uma bateria automatizada de testes de compatibilidade mantida pelo time do IronShell. Se todos os testes passam, a versão do IronShell é marcada como compatível imediatamente. Se algum teste falha, o time publica uma nova versão do runtime no mesmo SLA enterprise.

Essa escolha tem duas razões:

1. Preservar o investimento em Claude Code — todas as features que a Anthropic adicionar continuam disponíveis. MCP, skills, hooks, sub-agentes, extended thinking, tudo segue funcionando através do runtime IronShell.
2. Evitar divergência — manter um fork pesado é caro. Um runtime separado com arquitetura plugin-based consome muito menos esforço de manutenção e acompanha o upstream sem fricção.

Se em algum momento você quiser voltar ao Claude Code puro, basta desinstalar o IronShell. Totalmente reversível — nenhum dado é perdido; o Claude Code continua com a configuração original.

O que não está na arquitetura

Vale ser explícito sobre escolhas deliberadas de escopo.

• Não há cloud obrigatório. Nenhum componente requer envio de dados para servidor do IronShell. A ativação de licença é o único ponto de contato, e mesmo ela tem cache offline de 30 dias.
• Não há lock-in de provedor LLM. SmartRouter suporta 14 provedores diferentes, incluindo 3 locais (Ollama, vLLM, LocalAI). Você pode começar com Anthropic e migrar depois sem reescrever código.
• Não há vendor de memória. A memória episódica roda em SQLite WASM dentro do processo. Você pode configurar Postgres como backend opcional, mas não é requisito.
• Não há fork do Claude Code. O IronShell é um runtime separado com arquitetura plugin-based, certificado por bateria de testes a cada release oficial.

Essas escolhas são o que permite ao IronShell operar em ambientes air-gapped, sob compliance estrita, e sem gerar dependência cruzada com o time de infra.

Próximos passos

• Segurança — detalhes do kernel, padrões de ataque cobertos e benchmarks acadêmicos.
• Capabilities — squad, consenso Byzantine, JIT, self-healing em profundidade.
• Provedores LLM — como o SmartRouter escolhe entre os 14 provedores.
• Deployment — cenários de self-host, VPS, enterprise on-premise.