Arquitetura do Sistema de Módulos do AIOS

🌐 EN | PT | ES

Guia completo para a arquitetura modular v4.2 do Synkra AIOS.

Versão: 2.1.0 Última Atualização: 2025-12-01

Visão Geral

Por Que Arquitetura Modular?

A arquitetura modular v4.2 aborda vários desafios da estrutura flat da v2.0:

Princípios de Design

1. Responsabilidade Única - Cada módulo tem um propósito claro
2. Dependências Explícitas - Módulos declaram o que precisam
3. Acoplamento Fraco - Mudanças em um módulo não propagam
4. Alta Coesão - Funcionalidade relacionada permanece junta
5. Lazy Loading - Carrega apenas o necessário

Estrutura de Módulos

O Synkra AIOS organiza o diretório .aios-core/ em quatro módulos principais:

.aios-core/
├── core/              # Fundamentos do framework
├── development/       # Artefatos de desenvolvimento
├── product/           # Templates voltados ao usuário
└── infrastructure/    # Configuração do sistema

Diagrama de Módulos

Módulo Core

Caminho: .aios-core/core/ Propósito: Fundamentos do framework - configuração, sessão, elicitation e componentes essenciais de runtime.

Conteúdos

APIs Principais

// Configuração
const { loadAgentConfig, globalConfigCache } = require('./.aios-core/core');
 
// Sessão
const { ContextDetector, SessionContextLoader } = require('./.aios-core/core');
 
// Elicitation
const { ElicitationEngine, ElicitationSessionManager } = require('./.aios-core/core');
 
// Registry
const { getRegistry, loadRegistry } = require('./.aios-core/core/registry/registry-loader');
 
// Quality Gates
const QualityGateManager = require('./.aios-core/core/quality-gates/quality-gate-manager');

Dependências

• Externas: js-yaml, fs-extra
• Internas: Nenhuma (módulo de fundação)

Módulo Development

Caminho: .aios-core/development/ Propósito: Assets relacionados a agentes - definições de agentes, tarefas, workflows e scripts de desenvolvimento.

Conteúdos

Agentes

Times de Agentes

Dependências

• Internas: core/ (configuração, sessão, elicitation)

Módulo Product

Caminho: .aios-core/product/ Propósito: Assets PM/PO - templates, checklists e dados de referência para geração de documentos.

Conteúdos

Templates Principais

Checklists

• architect-checklist.md - Revisão de arquitetura
• pm-checklist.md - Validação PM
• po-master-checklist.md - Validação master PO
• story-dod-checklist.md - Definition of Done de story
• pre-push-checklist.md - Validação pre-push
• release-checklist.md - Validação de release

Dependências

• Internas: core/ (engine de template, validadores)
• Externas: Nenhuma (assets estáticos)

Módulo Infrastructure

Caminho: .aios-core/infrastructure/ Propósito: Configuração do sistema - scripts, ferramentas e integrações externas.

Conteúdos

Scripts Principais

Configurações de Ferramentas

tools/
├── cli/           # Configs de ferramentas CLI (gh, railway, supabase)
├── mcp/           # Configs de servidores MCP
└── local/         # Configs de ferramentas locais

Dependências

• Internas: core/ (configuração, utilitários)
• Externas: Várias APIs de ferramentas

Limites de Módulos

Regras de Dependência

Regras:

1. core/ não tem dependências internas
2. development/, product/, infrastructure/ dependem apenas de core/
3. Dependências circulares não são permitidas
4. CLI/ferramentas podem acessar qualquer módulo

Comunicação Inter-Módulos

Módulos se comunicam através de:

1. Service Registry - Descobrir workers e serviços disponíveis
2. Sistema de Configuração - Compartilhar settings e preferências
3. Sistema de Eventos - Publish/subscribe para acoplamento fraco
4. Sistema de Arquivos - Diretórios de dados compartilhados

Checklist de Limites de Módulos

Ao adicionar nova funcionalidade:

• Pertence a um módulo existente?
• Introduz novas dependências?
• Mantém fluxo de dependência unidirecional?
• É coeso com o propósito do módulo?
• Pode ser testado isoladamente?

Organização de Arquivos

Convenções de Nomenclatura

Adicionando Novos Arquivos

Migração da v2.0

Para projetos atualizando da estrutura flat v2.0:

# Dry run para visualizar mudanças
aios migrate --dry-run
 
# Executar migração
aios migrate --from=2.0 --to=2.1
 
# Validar migração
aios migrate --validate

Veja o Guia de Migração para instruções detalhadas.

Documentação Relacionada

• Guia de Service Discovery
• Guia de Quality Gates
• Guia de Setup Global MCP
• Guia de Migração
• ADR-002: Mapa de Migração

Arquitetura do Sistema de Módulos Synkra AIOS v4