Architect Architecture — Experimental

Proposta experimental. Esta página descreve a arquitetura de destino. Para desenvolver hoje, use o Architect SDK v1, com @zerotrusted/forge-sdk e Client.call(...). Exemplos com @titan/architect e Architect.on(...) são propostas e não fazem parte do contrato v1 distribuído.

1. Objetivo

Transformar o Titan Continuum em um monólito modular extensível, preservando o núcleo PHP e permitindo que desenvolvedores de diferentes empresas criem, instalem e gerenciem extensões sem modificar o código-fonte central. O modelo de distribuição e gerenciamento é inspirado nas extensões do phpBB, com isolamento adicional para código de terceiros.

O Architect SDK fornece contratos e bibliotecas de desenvolvimento; o Architect Engine é responsável pelo ciclo de vida, integração e execução das extensões. Os nomes e APIs deste documento são propostas, não garantias de funcionalidades já disponíveis.

2. Arquitetura geral

flowchart TD
    U[Navegador / TitanStorm] --> A[Apache HTTPS]
    A --> P[PHP-FPM / Titan Continuum Core]
    P --> M[(MySQL)]
    P --> W[Workerman / WebSocket]
    P <--> E[Titan Architect Engine / Gateway]
    E <--> R[(Redis Streams)]
    R --> PH[PHP CLI Workers isolados]
    R --> TS[Node.js Workers isolados]
    PH --> E
    TS --> E

Administração e extensibilidade do núcleo

O Apache mantém a entrega HTTP e o proxy reverso. O PHP-FPM executa o núcleo e as APIs. O TypeScript não é executado pelo PHP: é compilado para JavaScript e executado pelo Node.js em processos independentes. Plugins PHP também devem executar fora do processo do núcleo quando não forem plenamente confiáveis.

Tecnologia Responsabilidade Situação
Apache HTTP, HTTPS e proxy reverso Existente
PHP / PHP-FPM Núcleo e regras de negócio Existente
MySQL Persistência central Existente
Workerman WebSocket e comunicação em tempo real Existente
Architect SDK PHP e TS Contratos e clientes Clientes do contrato v1 disponíveis; APIs propostas nesta página são experimentais
Architect Engine Registro, ciclo de vida e execução Registro nativo e gateway interno implementados no piloto. Ciclo de vida e supervisão previstos.
Node.js Runtime de plugins TypeScript Previsto
Redis Streams Entrega persistente de eventos Previsto
Docker ou isolamento equivalente Restrições de execução Previsto
Composer / npm Dependências e distribuição dos SDKs Proposto para extensões

A classificação é baseada no diagnóstico anterior da source e nas decisões discutidas, não em nova inspeção do servidor ou teste de produção.

3. Modularização do Titan Continuum

Preservar as rotas e os módulos atuais durante a migração. Separar gradualmente autenticação, permissões, serviços, persistência, navegação e eventos em interfaces estáveis. Adotar autoload PSR-4 e contratos versionados. Use Chamados e Downloads como referências para controles de acesso, migrações e serviços publicados.

Pontos de integração identificados anteriormente:

  • includes/permissoes.php: autorização;
  • includes/seguranca.php: segurança e sessões;
  • includes/navegacao.php: navegação;
  • includes/realtime.php: atualizações em tempo real;
  • includes/schema.php: migrações;
  • realtime/src/Protocol.php e realtime/src/Executor.php: infraestrutura realtime.

O WebSocket existente comunica alterações por módulo; não deve ser confundido com um barramento de eventos de negócio durável. A granularidade dos eventos precisa ser implementada progressivamente.

4. Componentes do Architect

Componente Função
SDK PHP / TypeScript Clientes tipados, eventos e interfaces de extensão
Engine Gerenciamento do ciclo de vida e supervisão de runtimes
API Gateway Autenticação, autorização e exposição de serviços controlados
Event Bus Distribuição de eventos de negócio
Module Manager Registro de módulos nativos
Plugin Manager Instalação, ativação, atualização e desativação
Menu / Route Registry Registro de menus e rotas com autorização
Permission Registry Catálogo de capacidades e políticas
Registry / Marketplace Catálogo de extensões homologadas
Migration Manager Evolução de dados próprios de extensões
Security Isolamento, auditoria, limites e revogação

5. Estrutura proposta

titansource/
  nucleo/
    core/
    bootstrap.php
  plugins/
    native/
      chamados/
      downloads/
  includes/
  revenda/
  chamados/
  inventario/
/var/lib/titan/architect/
  extensions/<vendor>/<plugin>/<version>/
  registry/
  data/

Manter pacotes, código executável de terceiros e dados privados fora da raiz pública do Apache. Apenas recursos públicos explicitamente aprovados devem ser servidos.

6. Pacote de extensão (.fex)

O formato FEX v1 é um ZIP de até 250 MB (262.144.000 bytes), com manifesto, código, recursos e assinatura Ed25519. O verificador implementado confere a assinatura do índice canônico e o SHA-256 de todos os arquivos, incluindo o manifesto. O staging privado recebe a chave pública escolhida pelo operador. Cadastro de confiança e ciclo de vida integrados ao painel permanecem planejados.

inventory-analytics.fex
  manifest.json
  files.sha256
  signature.sig
  src/
  dist/             # JavaScript compilado, para TS
  assets/
  migrations/
  README.md
  LICENSE

Exemplo conceitual de manifesto:

{
  "id": "empresa.inventory-analytics",
  "name": "Inventory Analytics",
  "version": "1.0.0",
  "sdkVersion": "^0.1.0",
  "runtime": "typescript",
  "entrypoint": "dist/index.js",
  "permissions": ["inventory.read", "dashboard.register"],
  "events": ["inventory.updated"]
}

Para PHP, utilizar runtime: php e um entrypoint como src/Plugin.php. A compatibilidade do manifesto, as permissões e o formato final ainda devem ser consolidados com o SDK real.

7. Execução PHP e TypeScript

  • PHP: workers PHP CLI com Composer e autoload PSR-4.
  • TypeScript: desenvolver em .ts, verificar tipos e compilar com tsc, distribuir .js em dist/ e executar com Node.js.
  • O build e a resolução de dependências devem ocorrer em ambiente controlado, não durante uma requisição PHP nem automaticamente no servidor operacional.
  • Os dois runtimes devem usar os mesmos contratos e passar pelo Gateway. Não compartilhar credenciais do banco ou sessões de usuários.
plugin.ts -> tsc -> dist/index.js -> Node.js Worker
plugin.php -----------------------> PHP CLI Worker
                    ambos <-> Architect Gateway

8. Eventos de negócio

Exemplo: uma venda é despachada no módulo Revenda. A operação é validada pelo PHP e registrada no MySQL. Um evento é produzido somente quando a alteração é confirmada. Recomenda-se gravar a operação e o evento de outbox na mesma transação; um publicador encaminha o evento ao Redis Streams posteriormente.

// API conceitual, ainda não integrada ao núcleo.
$architect->events()->emit('revenda.dispatched', [
    'order_id' => 1520,
    'status' => 'dispatched'
]);
// API conceitual do SDK TypeScript.
import { Architect } from '@titan/architect';

Architect.on('revenda.dispatched', async (event) => {
    console.log('Pedido despachado:', event.order_id);
    await Architect.notifications.send({
        message: 'Uma venda foi despachada.'
    });
});
// API conceitual do SDK PHP.
use Titan\Architect\Plugin;

$plugin = new Plugin();
$plugin->on('inventory.updated', function ($event) {
    // Processar atualização autorizada do estoque.
});

Cada evento deve conter identificador único, tipo, versão de esquema, horário UTC, tenant e identificador de correlação. Expor apenas dados necessários e autorizados. O Gateway deve validar permissões também nas chamadas de retorno, como a solicitação de notificação.

Redis Streams permite distribuição com grupos de consumidores, confirmação (ACK), novas tentativas e recuperação de pendências. A entrega deve ser tratada como pelo menos uma vez, com consumidores idempotentes, limite de tentativas e fila de falhas. Plugins não devem consumir diretamente streams internos com dados de outros tenants.

9. Comunicação entre processos

Mecanismo Uso
HTTP/JSON API do Architect; primeira opção para chamadas síncronas
Redis Streams Eventos assíncronos e retomada de processamento
Unix sockets Alternativa local de IPC com permissões do sistema
WebSocket Comunicação em tempo real com clientes, via Workerman
gRPC Alternativa futura para contratos tipados entre serviços

Recomendação inicial: HTTP/JSON e Redis Streams. Manter Workerman no papel atual. A API deve ser versionada, autenticar cada extensão, aplicar escopo por tenant e operação, limitar requisições e validar todos os dados recebidos. Não expor serviços internos diretamente à internet.

10. Instalação e ciclo de vida

Inspirado no phpBB, o painel administrativo deve listar extensões, versões, autores, permissões, estado e logs. Operações propostas:

  1. Upload de .fex para área de staging.
  2. Validar tamanho, caminhos do ZIP, arquivos, assinatura, dependências e versão do núcleo.
  3. Revisar permissões solicitadas e autorizar instalação.
  4. Instalar em diretório versionado, sem executar scripts arbitrários no núcleo.
  5. Ativar o runtime isolado e registrar apenas contribuições permitidas.
  6. Desativar: interromper novas entregas, revogar credenciais e remover menus/rotas ativos, preservando dados.
  7. Atualizar: validar nova versão, testar e promover com possibilidade de rollback.
  8. Desinstalar: remover pacote; exclusão definitiva de dados exige confirmação separada.

Estados sugeridos: staged, installed, enabled, disabled, failed, uninstalled. Registrar transições e impedir alterações concorrentes. Rollback do código não garante rollback de banco: migrações precisam de estratégia de compatibilidade, backup e recuperação.

11. Segurança e isolamento

O manifesto declara capacidades, mas não impõe isolamento sozinho. Código PHP ou Node.js arbitrário pode acessar recursos do processo em que executa.

  • Executar terceiros em contêineres ou ambientes segregados, com usuários sem privilégios, sistema de arquivos restrito e sem montagem de diretórios do núcleo.
  • Aplicar limites de CPU, memória, processos, tempo de execução, armazenamento e rede; bloquear saída de rede por padrão e permitir destinos necessários.
  • Proibir acesso direto ao MySQL central, segredos, tokens internos, socket Docker e arquivos privados.
  • Credenciais específicas por instalação/tenant, de escopo mínimo, revogáveis e com validade controlada.
  • Verificar autorização no servidor em cada API, rota, evento e operação; não confiar em campos de tenant ou permissão recebidos do plugin.
  • Validar pacotes contra path traversal, links simbólicos, arquivos excessivos e bombas de descompressão. Assinatura comprova origem e integridade, não ausência de código malicioso.
  • Revisar dependências, licenças e vulnerabilidades antes da homologação; evitar scripts de instalação não autorizados.
  • Registrar auditoria sem segredos ou dados pessoais desnecessários; oferecer modo seguro e desligamento individual.
  • Interfaces de terceiros devem usar componentes controlados ou iframe com sandbox e origem separada, evitando execução de JavaScript não confiável no contexto autenticado do Titan.

12. Disponibilidade e desempenho

Supervisionar workers com reinício limitado, health checks, timeouts, circuit breakers e backoff. Operações do núcleo não devem bloquear indefinidamente esperando plugins. Uma falha de extensão deve degradar somente a funcionalidade relacionada sempre que possível. Testar saturação de filas, concorrência, duplicidade de eventos, queda de Redis, indisponibilidade do runtime e recuperação após reinício.

13. Roadmap de implementação

  • [ ] Inventariar dependências e contratos do núcleo; modularizar um módulo piloto.
  • [ ] Consolidar autenticação, autorização, rotas, menus e serviços compartilhados.
  • [ ] Definir schemas versionados de manifestos, eventos e API.
  • [ ] Implementar Gateway, registro de permissões e eventos de negócio com outbox.
  • [ ] Implementar Plugin Manager e painel inspirado no phpBB.
  • [ ] Implementar execução isolada PHP e Node.js, supervisão e Redis Streams.
  • [ ] Validar um plugin PHP e um TypeScript com as mesmas capacidades.
  • [ ] Implementar instalação assinada, atualizações, rollback e modo seguro.
  • [ ] Documentar SDK, exemplos, CI e requisitos de homologação.
  • [ ] Homologar segurança, carga e isolamento antes de abrir o Registry a terceiros.

14. Critérios mínimos para liberar extensões externas

  • Instalar, ativar, desativar e remover uma extensão sem modificar o núcleo.
  • Demonstrar que os runtimes PHP e TypeScript usam contratos compatíveis.
  • Bloquear acessos sem permissão e tentativas de acesso entre empresas.
  • Garantir que travamentos de plugins não interrompam operações centrais.
  • Verificar recuperação de eventos, idempotência, auditoria e revogação.
  • Testar pacotes inválidos, adulterados, incompatíveis e migrações malsucedidas.
  • Homologar em ambiente separado antes da promoção ao operacional.

15. Decisão arquitetural

Manter PHP como autoridade das regras de negócio do Titan Continuum. Usar Node.js como runtime complementar e TypeScript como segunda linguagem oficial de desenvolvimento de extensões. O Architect deve ser a única interface autorizada entre plugins e o núcleo. A modularização será incremental e não exige substituir Apache, MySQL ou Workerman.

Este documento descreve a arquitetura pretendida. A implementação e os testes de integração, segurança e produção ainda são necessários; os exemplos de API são ilustrativos.

Consulte a referência dos módulos públicos para conhecer os contratos disponíveis por módulo.