Visão Geral da Arquitetura¶

O AIOS é construído sobre quatro pilares que refletem as melhores práticas de sistemas distribuídos modernos:

1. Hierarquia de Tiers — Separação de responsabilidades por camada
2. Contratos Tipados — Comunicação inter-agente sem ambiguidade
3. Segurança em Profundidade — OWASP LLM Top 10 aplicado em cada camada
4. Portabilidade — Qualquer squad pode rodar em qualquer plataforma

Diagrama de componentes¶

C4Context
  title Aguia-Cibernetica — ELROI OS — Visão de Componentes

  Person(ceo, "CEO", "Vinícius Rodegheri")

  System_Boundary(aios, "AIOS") {
    System(gateway, "API Gateway", "Hono.js — Auth, Rate Limit, OWASP")
    System(n8n, "n8n", "Motor de automação e orquestração")
    System(squads, "Squads", "18 squads / 245 agentes")
    SystemDb(db, "PostgreSQL", "Squads, execuções, audit logs")
    SystemDb(cache, "Redis", "Rate limiting, fila, cache")
  }

  System_Ext(claude, "Claude Pro", "LLM Tier 1")
  System_Ext(ollama, "Ollama", "LLM Tier 2 (local)")
  System_Ext(openrouter, "OpenRouter", "LLM Tier 3 (cloud)")

  Rel(ceo, gateway, "Requisições via API / Claude Code")
  Rel(gateway, n8n, "Webhooks de execução")
  Rel(gateway, db, "Persistência")
  Rel(gateway, cache, "Rate limit + fila")
  Rel(n8n, squads, "Roteamento de tasks")
  Rel(squads, claude, "Tier 1")
  Rel(squads, ollama, "Tier 2")
  Rel(squads, openrouter, "Tier 3")

Fluxo de execução¶

sequenceDiagram
    participant C as CEO / Cliente
    participant G as API Gateway
    participant R as Redis (Rate Limit)
    participant N as n8n
    participant B as bridge-agent
    participant S as Squad Destino
    participant L as LLM (Tier 1/2/3)
    participant DB as PostgreSQL

    C->>G: POST /v1/squads/copywriting/run
    G->>G: 1. Sanitização (OWASP LLM01)
    G->>G: 2. Auth JWT + tenant isolation
    G->>R: 3. Rate limit check
    R-->>G: OK / 429
    G->>DB: 4. Criar execution record
    G->>N: 5. Webhook → executar squad
    N->>B: 6. bridge-agent roteia
    B->>S: 7. Envelope tipado (INTER-AGENT-CONTRACT)
    S->>L: 8. Model routing (Tier 1/2/3)
    L-->>S: 9. Output
    S->>S: 10. Quality gate (score 0-100)
    S-->>G: 11. Resultado + score
    G->>DB: 12. Audit log imutável (SHA-256)
    G-->>C: 13. Resposta com envelope tipado

Decisões de design¶

Por que Hono.js no API Gateway?¶

• Performance: ~4x mais rápido que Express em edge runtimes
• Tipo-seguro: TypeScript first, sem overhead de runtime
• Multi-runtime: Node.js, Deno, Bun, Cloudflare Workers — portabilidade total
• Middleware ecosystem: rate limiting, JWT, secure headers built-in

Por que PostgreSQL + Redis?¶

Por que n8n como orquestrador?¶

• Visual: fluxos visíveis e auditáveis sem código
• Self-hosted: dados não saem da sua infraestrutura
• Webhook-native: integração trivial com API Gateway
• MCP-compatible: pode chamar agentes Claude diretamente

Padrões aplicados¶