Architect Architecture — Experimental
Proposta experimental. Esta página descreve a arquitetura de destino. Para desenvolver hoje, use o Architect SDK v1, com
@zerotrusted/forge-sdkeClient.call(...). Exemplos com@titan/architecteArchitect.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.phperealtime/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 comtsc, distribuir.jsemdist/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:
- Upload de
.fexpara área de staging. - Validar tamanho, caminhos do ZIP, arquivos, assinatura, dependências e versão do núcleo.
- Revisar permissões solicitadas e autorizar instalação.
- Instalar em diretório versionado, sem executar scripts arbitrários no núcleo.
- Ativar o runtime isolado e registrar apenas contribuições permitidas.
- Desativar: interromper novas entregas, revogar credenciais e remover menus/rotas ativos, preservando dados.
- Atualizar: validar nova versão, testar e promover com possibilidade de rollback.
- 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.