Integration Plataform

Plataforma de orquestração de integrações criada para modelar conectores, compor pipelines executáveis e operar fluxos técnicos com debug, fila, logs e rastreabilidade.

Visão geral

O IntegrationPlataform é um sistema do ecossistema Archon desenhado para resolver um problema muito específico: transformar integrações entre sistemas em objetos configuráveis e operáveis, sem depender apenas de código espalhado em jobs e serviços isolados.

Papel no ecossistema

O sistema é um consumidor real do stack compartilhado do monorepo.

Backend

Ele usa:

• Archon Framework como base de API, contrato de resposta, persistência e autorização;
• Identity Management para autenticação e validação de sessão quando configurado.

Frontend

Ele usa:

• archon-ui para layout administrativo, autenticação, proteção de rota, HTTP client, loader global e componentes de interface.

Isso torna o IntegrationPlataform um caso real de uso do ecossistema, não apenas um módulo isolado.

Arquitetura da solução

A solução está dividida em:

• IntegrationPlataform.Api
• IntegrationPlataform.Application
• IntegrationPlataform.Domain
• IntegrationPlataform.Infrastructure
• IntegrationPlataform.Testing
• IntegrationPlataform.Web

No frontend, as rotas observadas no código cobrem quatro áreas principais:

• Dashboard
• Configuração
• Operação
• Automação

Como o sistema funciona

O modelo operacional do sistema é este:

1. uma integração define um tipo de integração e seus atributos configuráveis;
2. um conector representa uma instância concreta dessa integração;
3. um pipeline descreve a sequência de etapas executáveis;
4. cada etapa usa um recurso técnico, como chamada HTTP, função JavaScript ou script SQL;
5. uma execução registra o processamento real;
6. os logs detalham tudo o que aconteceu;
7. a fila e as rotinas permitem operação assíncrona e automação futura.

Esse desenho dá ao sistema uma separação clara entre modelagem, configuração técnica e operação.

Mapa de telas

As principais telas reais identificadas no frontend são:

• / — Dashboard
• /integracoes — Integrações
• /integracoes/:id — Detalhe da integração
• /categorias — Categorias de integração
• /conectores — Conectores
• /conectores/:id — Detalhe do conector
• /chamadas-api — Chamadas de API
• /funcoes-javascript — Funções JavaScript
• /scripts-banco-dados — Scripts SQL
• /conexoes-banco — Conexões de banco
• /pipelines — Pipelines
• /pipelines/:id — Detalhe do pipeline
• /execucoes — Execuções
• /fila — Fila de processamento
• /referencias — Referências
• /automacao — Rotinas de pipeline

A seguir estão as telas mais importantes documentadas com base no código e nas imagens do sistema.

Dashboard

O dashboard é a tela inicial operacional do sistema. Pelo código, ele concentra KPIs e visão executiva da plataforma, com foco em monitoramento diário.

O que a tela apresenta

• quantidade de integrações ativas;
• conectores ativos;
• pipelines ativos;
• execuções do dia;
• taxa de sucesso;
• erros do dia;
• gráfico de execuções mensais;
• lista de execuções recentes.

Objetivo da tela

Essa tela funciona como centro de observabilidade do sistema. Ela permite perceber rapidamente se a plataforma está saudável, se houve erro operacional recente e quais fluxos estão executando com maior frequência.

Tela de Integrações

Essa tela é o ponto de partida da modelagem funcional do sistema.

O que o usuário gerencia aqui

• identificador da integração;
• nome;
• categoria;
• status ativo/inativo;
• importação e exportação de definição.

Como ela funciona

O frontend mostra uma tabela com ações de adicionar, editar, remover, atualizar, exportar e importar. O código também evidencia suporte à abertura do detalhe da integração por duplo clique.

Papel dessa tela no fluxo

Ela define o “tipo” de integração. A partir dela, o sistema consegue organizar integrações por categoria e permitir que cada uma tenha atributos técnicos próprios.

Detalhe da Integração

A tela de detalhe da integração aprofunda a configuração funcional.

O que aparece nela

• identificador;
• nome;
• categoria;
• status;
• lista ordenada de atributos da integração.

O que pode ser configurado

Os atributos suportam, pelo modelo e pelo frontend:

• nome técnico do campo;
• label;
• tipo de campo;
• grupo;
• valor padrão;
• campo obrigatório;
• campo sensível;
• ordem de exibição.

Papel dessa tela

Ela transforma a integração em um contrato configurável. Em vez de hardcode de parâmetros por integração, o sistema descreve a configuração necessária em metadados.

Tela de Conectores

Os conectores representam instâncias concretas de integração.

O que a tela apresenta

• nome do conector;
• integração associada;
• status ativo/inativo.

Papel da tela

Enquanto a integração define o modelo, o conector representa a instância operacional. É aqui que uma integração passa a existir em um contexto real de uso.

Detalhe do Conector

A tela de detalhe do conector é uma das mais importantes para configuração técnica.

O que aparece nela

• nome do conector;
• integração relacionada;
• status;
• atributos agrupados;
• formulário dinâmico baseado nos atributos definidos na integração.

Comportamentos observados

O código mostra suporte a:

• campos de texto simples e texto longo;
• número e decimal;
• booleano;
• data e data/hora;
• campos sensíveis com alternância entre exibir/ocultar;
• agrupamento de atributos por seção;
• persistência de valores por atributo.

Papel dessa tela

Ela é a ponte entre o modelo abstrato e a operação real. Credenciais, URLs, tokens, parâmetros e flags técnicas são configurados aqui.

Tela de Chamadas de API

Essa área cadastra chamadas HTTP reutilizáveis dentro dos pipelines.

O que o sistema modela aqui

• método HTTP;
• URL;
• headers template;
• body template.

Papel dessa tela

Ela isola chamadas externas em recursos reutilizáveis. Isso permite montar etapas HTTP no pipeline sem redefinir manualmente cada request em vários pontos.

Tela de Scripts SQL

Essa tela centraliza scripts reutilizáveis vinculados a conexões de banco de dados.

O que ela suporta

• associação com conexão de banco;
• manutenção de scripts SQL reutilizáveis;
• uso posterior por etapas de pipeline do tipo execução de script.

Papel da tela

Ela estende a plataforma além de integrações HTTP, permitindo pipelines que interagem diretamente com banco de dados, especialmente PostgreSQL e SQL Server.

Tela de Pipelines

Pipelines são o coração do sistema.

O que a tela lista

• identificador;
• nome;
• integração associada;
• status ativo/inativo;
• ação de abrir detalhe.

Papel dessa tela

Ela organiza os fluxos executáveis. Uma mesma integração pode ter múltiplos pipelines, cada um com um objetivo específico.

Detalhe do Pipeline

Essa é a tela onde a lógica de execução realmente ganha forma.

O que o código mostra

• visão geral do pipeline;
• listagem ordenada das etapas;
• drag and drop para reordenação;
• edição e remoção de etapas;
• painel lateral com detalhes da etapa selecionada;
• abertura do debugger do pipeline.

Tipos de etapa observados

• HttpRequest
• JavaScriptFunction
• ExecuteScript

Metadados importantes da etapa

• ordem;
• nome;
• status;
• tipo;
• ação em caso de erro;
• opção de ignorar retorno;
• recurso vinculado (API call, função JS ou script SQL).

Papel da tela

Essa tela materializa a orquestração. Aqui o sistema deixa de ser só cadastro e passa a representar um fluxo técnico composto, observável e reordenável.

Debug de Pipeline

O debug é um dos diferenciais mais fortes do sistema.

O que o sistema permite

• iniciar sessão de debug;
• definir etapa inicial opcional;
• avançar passo a passo;
• comparar resultados entre etapas;
• inspecionar logs;
• baixar resposta binária quando houver;
• finalizar sessão de debug.

Papel dessa tela

Ela foi pensada para troubleshooting real. Em vez de tratar pipelines como caixas pretas, a plataforma permite inspeção guiada do fluxo em execução.

Tela de Execuções

A tela de execuções consolida o histórico operacional dos pipelines.

O que ela lista

• tipo de execução;
• conector;
• pipeline;
• status;
• data/hora de início;
• duração.

Papel da tela

Ela serve como histórico operacional do sistema, permitindo auditoria e acompanhamento de fluxos executados manualmente ou por outros mecanismos do motor.

Detalhe da Execução

Essa tela aprofunda a análise de uma execução específica.

O que ela tende a exibir

• status da execução;
• payload de entrada;
• saída consolidada;
• erros;
• logs por etapa;
• duração;
• dados técnicos de request/response.

Papel da tela

Ela é fundamental para operação e suporte. Quando um pipeline falha ou retorna resultado inesperado, essa é a tela usada para investigação detalhada.

Fila de Processamento

A fila representa o modo assíncrono da plataforma.

O que a tela gerencia

• conector;
• pipeline;
• prioridade;
• status;
• agendamento;
• criação.

Observação importante

O desenho principal do sistema considera que pipelines podem ser disparados externamente por API, principalmente pelo endpoint:

• POST /api/executions/execute-by-identifier/{integrationIdentifier}/{pipelineIdentifier}

Esse fluxo permite que outro sistema invoque uma integração conhecendo apenas os identificadores lógicos da integração e do pipeline.

A tela de fila existe como suporte operacional para enfileiramento manual, inspeção do backlog e controle assíncrono de execuções quando o time precisa operar o fluxo pela interface.

Papel da tela

Ela organiza execuções enfileiradas e permite operação assíncrona controlada, inclusive com remoção de itens e inclusão manual de novas entradas.

Tela de Referências

A tela de referências mantém o vínculo entre IDs internos e externos.

O que a tela registra

• conector;
• entidade;
• ID interno;
• ID externo;
• data de criação.

Papel da tela

Ela resolve um problema clássico de integração: manter rastreabilidade entre registros de sistemas diferentes sem acoplamento manual em planilhas ou código disperso.

Tela de Automação

A tela de automação trabalha com rotinas de pipeline.

O que o frontend mostra

• conector;
• pipeline;
• intervalo em minutos;
• status ativo/inativo;
• próxima execução;
• última execução.

Papel da tela

Ela indica a direção de automação recorrente da plataforma. Pelo código e pela documentação, o modelo de rotina existe claramente, ainda que o processamento recorrente automático não apareça completamente fechado na infraestrutura atual.

Fluxo operacional típico

Uma leitura prática de uso do sistema seria:

1. cadastrar uma categoria de integração;
2. cadastrar a integração;
3. definir atributos configuráveis;
4. criar um conector com valores reais;
5. criar recursos técnicos auxiliares, como chamadas HTTP, funções JS e scripts SQL;
6. montar o pipeline e ordenar suas etapas;
7. executar o pipeline manualmente ou via identificador;
8. analisar logs e resultados;
9. usar debug quando necessário;
10. registrar ou consultar referências entre sistemas.

Diferenciais do sistema

Os pontos mais fortes observados no código e na UI são:

• modelagem configurável de integrações;
• separação clara entre integração, conector e pipeline;
• suporte combinado a HTTP, JavaScript e SQL;
• debug passo a passo;
• histórico de execuções e logs;
• rastreabilidade via referências;
• dashboard operacional;
• integração real com o ecossistema Archon e Identity Management.

Evolução em andamento

Está em desenvolvimento uma nova experiência mais friendly para operadores do sistema, com foco em reduzir dependência de configuração técnica manual.

A direção dessa evolução inclui:

• workflows em canvas para modelagem visual;
• criação de integrações sem exigir habilidade técnica em JSON;
• configuração mais guiada para integrações de APIs;
• experiência mais operacional para times que precisam usar a plataforma sem atuar diretamente no nível técnico atual.

Resumo executivo

O IntegrationPlataform não é apenas um CRUD de integrações. Ele funciona como um motor operacional de orquestração, com foco em configuração, execução, observabilidade e troubleshooting. Isso o torna um dos projetos mais fortes do portfólio, porque combina domínio técnico, arquitetura de sistema e experiência administrativa em uma única plataforma.