O LayoutParser é uma plataforma de engenharia de integrações para interpretar, validar, transformar e explicar documentos estruturados e posicionais. Seu núcleo conecta layouts, regras de negócio, motores de transformação e validadores em um pipeline versionável.

O cenário já atendido parte de documentos em TXT posicional, descritos por layouts XML. A plataforma identifica linhas, campos, ocorrências, posições e inconsistências; executa candidatos de transformação; apresenta o resultado em uma aplicação web; e mantém rastreabilidade ponta a ponta por CorrelationId.

Mais do que um conversor isolado, a proposta é funcionar como um framework para novos mapeamentos, no qual cada integração pode ser desenvolvida e homologada como uma unidade:

• contrato de origem e destino;
• modelo estrutural canônico;
• regras determinísticas ou assistidas por IA;
• casos de teste e artefatos sanitizados;
• validação estrutural, fiscal e de negócio;
• empacotamento, versionamento, implantação e observabilidade.

Transparência de maturidade: este README diferencia capacidades disponíveis, capacidades em evolução e itens de roadmap. Uma direção arquitetural não é apresentada como funcionalidade já entregue.

O framework organiza uma transformação em seis responsabilidades desacopladas: adaptar, interpretar, mapear, executar, validar e operar. Isso permite adicionar um novo formato sem reescrever autenticação, catálogo, observabilidade ou experiência de análise.

Camada do framework	Tecnologias que a implementam
Experiência e ingestão Interface, upload e fronteira web	React · TypeScript · Vite · Node.js · Fastify
Modelo e mapeamento Parser, contratos e catálogo	C# · .NET 10 · XML/XSD · SQL Server · Redis
Execução e inteligência Motores determinísticos e IA local	.NET Framework · TCL/XSL/XSLT · XslSynth · Ollama
Assurance e operação Testes, entrega e observabilidade	GitHub Actions · Playwright · Cypress · Docker · PowerShell

flowchart LR
    subgraph Sources["1 · Fontes / Source adapters"]
        TXT["🟢 TXT posicional"]
        XML["🟡 XML"]
        JSON["🔵 JSON"]
    end

    subgraph Canonical["2 · Modelo documental canônico"]
        INGEST["Ingestão segura<br/>encoding · tamanho · tipo"]
        PARSE["Parser estrutural<br/>linhas · campos · posições · ocorrências"]
        MODEL["Document Model<br/>identidade · hierarquia · cardinalidade"]
    end

    subgraph Mapping["3 · Definição e catálogo de mapeamentos"]
        REGISTRY["Mapping Registry<br/>layout · mapper · versão · status"]
        RULES["Mapping Definition<br/>origens · destinos · regras · funções"]
        TRACE["Trace Model<br/>campo ↔ nó · diagnóstico · confiança"]
    end

    subgraph Engines["4 · Motores de execução"]
        LOWCODE["🟢 Sysmiddle / Low-code"]
        XSL["🟢 TCL · XSL · XSLT"]
        AI["🟡 XslSynth + Ollama<br/>RAG · few-shot · auto-correção"]
        FUTURE["🔵 Adaptadores futuros<br/>XML↔XML · XML→TXT · TXT→JSON"]
    end

    subgraph Assurance["5 · Assurance"]
        SCHEMA["Schema validation<br/>XML · XSD · contratos"]
        DIFF["Diff canônico<br/>ground truth · regressão"]
        BUSINESS["Regras de negócio<br/>aceitação externa"]
    end

    subgraph Targets["6 · Destinos / Target adapters"]
        OUTXML["🟢 XML"]
        OUTTXT["🔵 TXT"]
        OUTJSON["🔵 JSON"]
    end

    OPS["Operação transversal<br/>OIDC · autorização · cache · auditoria<br/>CorrelationId · métricas · CI/CD"]

    TXT --> INGEST
    XML --> INGEST
    JSON -. roadmap .-> INGEST
    INGEST --> PARSE --> MODEL
    MODEL --> RULES
    REGISTRY --> RULES
    RULES --> TRACE
    RULES --> LOWCODE
    RULES --> XSL
    RULES --> AI
    RULES -. expansão .-> FUTURE
    LOWCODE --> SCHEMA
    XSL --> SCHEMA
    AI --> SCHEMA
    FUTURE -. roadmap .-> SCHEMA
    SCHEMA --> DIFF --> BUSINESS
    BUSINESS --> OUTXML
    BUSINESS -. roadmap .-> OUTTXT
    BUSINESS -. roadmap .-> OUTJSON
    OPS -. protege e observa .-> INGEST
    OPS -. protege e observa .-> REGISTRY
    OPS -. protege e observa .-> BUSINESS

Legenda: 🟢 disponível · 🟡 em evolução/validação · 🔵 roadmap · ⚪ discovery

As rotas de roadmap reutilizarão o mesmo núcleo de identidade, catálogo, validação, rastreabilidade e observabilidade. Isso evita criar um conversor independente para cada par de formatos.

flowchart TB
    USER["👤 Analista de integração"]

    subgraph Web["LayoutParserReact · experiência e fronteira web"]
        SPA["React 19 + TypeScript<br/>upload · árvore · edição posicional · XML"]
        BFF["Node.js 24 + Fastify 5<br/>Entra OIDC · sessão · rate limit · proxy"]
    end

    subgraph Core["LayoutParserApi · hub de domínio"]
        API["ASP.NET Core · .NET 10<br/>contratos · orquestração · autorização"]
        PARSER["Parsing Engine<br/>layout · linhas · campos · ocorrências"]
        CANDIDATES["Transformation Orchestrator<br/>candidatos · diagnóstico · tickets"]
        XSLSYNTH["XslSynth.Core / Contracts<br/>RAG · geração · validação · diff"]
        MCP["LayoutParser MCP Server<br/>tools de parse e catálogo para agentes"]
    end

    subgraph Runtime["Motores e compatibilidade"]
        RUNNER["LayoutParserLowCodeRunner<br/>runtime Sysmiddle isolado"]
        DECRYPT["LayoutParserDecrypt<br/>fronteira criptográfica externa"]
        LIB["LayoutParserLib<br/>cripto canônica e logging legado"]
        OLLAMA["Ollama local<br/>modelos executados on-premise"]
    end

    subgraph Data["Dados e operação"]
        SQL[("SQL Server<br/>catálogo de layouts e mappers")]
        REDIS[("Redis<br/>cache e catálogo materializado")]
        OBS["Serilog + Elastic<br/>logs estruturados e correlação"]
    end

    subgraph Quality["Quality & delivery"]
        GH["GitHub Actions<br/>build · test · SAST · dependency review"]
        E2E["Playwright + Cypress<br/>desktop · mobile · aceitação externa"]
        IIS["Windows Server + IIS/ARR<br/>development → production"]
    end

    USER -->|HTTPS + Microsoft login| SPA
    SPA -->|same-origin /api| BFF
    BFF -->|identidade confiável + CorrelationId| API
    API --> PARSER
    API --> CANDIDATES
    MCP --> API
    PARSER --> SQL
    PARSER --> REDIS
    API --> DECRYPT
    DECRYPT -. fontes canônicas .-> LIB
    CANDIDATES --> RUNNER
    CANDIDATES --> XSLSYNTH
    XSLSYNTH --> OLLAMA
    API --> OBS
    GH --> IIS
    E2E --> BFF

sequenceDiagram
    autonumber
    actor Analyst as Analista
    participant Web as React + BFF
    participant API as LayoutParserApi
    participant Catalog as SQL / Redis
    participant Engine as Low-code / TCL-XSL / IA
    participant QA as Validação

    Analyst->>Web: Envia documento e seleciona layout
    Web->>API: Upload autenticado + CorrelationId
    API->>Catalog: Resolve layout, mapper e versão
    Catalog-->>API: Definições estruturais
    API->>API: Parse de linhas, campos e ocorrências
    API-->>Web: Modelo navegável + diagnósticos
    Analyst->>Web: Solicita transformação
    Web->>API: execute-candidates
    API->>Engine: Executa pathways aplicáveis
    Engine-->>API: XML candidato + evidências
    API->>QA: XSD + diff + regras de negócio
    QA-->>API: Resultado e confiança
    API-->>Web: Candidatos + diagnóstico por pathway
    Web-->>Analyst: Comparar, revisar, copiar ou baixar

O LayoutParser pode ser evoluído como um serviço de engenharia de mapeamento sob demanda. Cada novo fluxo — por exemplo, TXT→XML de um parceiro, XML→XML entre schemas ou TXT→JSON — é tratado como produto versionado, não como script avulso.

flowchart LR
    D1["1 · Discovery<br/>origem · destino · regras"] -->
    D2["2 · Contrato<br/>schemas · encoding · cardinalidade"] -->
    D3["3 · Mapping Design<br/>modelo canônico · regras · funções"] -->
    D4["4 · Implementação<br/>adapter · mapper · transformação"] -->
    D5["5 · Assurance<br/>fixtures · XSD · diff · negócio"] -->
    D6["6 · Homologação<br/>cenários reais sanitizados"] -->
    D7["7 · Operação<br/>versão · deploy · métricas · evolução"]

• descrição dos formatos de origem e destino;
• layout, XSD, JSON Schema ou especificação equivalente;
• documentos de exemplo sanitizados;
• saída esperada ou regras de negócio verificáveis;
• encoding, terminadores, cardinalidades e convenções de campos vazios;
• critérios de aceite e ambiente de homologação.

• especificação do contrato e da matriz campo→campo;
• adapter de origem e/ou destino;
• mapper determinístico, TCL/XSL/XSLT ou estratégia híbrida;
• suíte de regressão com fixtures sintéticas/sanitizadas;
• diagnóstico estruturado e rastreabilidade de transformação;
• documentação operacional, runbook e estratégia de rollback;
• pacote de implantação e baseline de observabilidade.

1. O mesmo input e a mesma versão de regra produzem resultado reproduzível.
2. Encoding, posições, ocorrências e namespaces possuem testes explícitos.
3. Casos N:1, 1:N, valores estáticos e grupos repetidos estão documentados.
4. Falhas têm código, mensagem segura e CorrelationId; não há fallback silencioso.
5. Nenhum conteúdo sensível aparece em logs, commits ou issues públicas.
6. O resultado passa por schema, regressão e regra de negócio aplicável.
7. A versão implantada pode ser identificada, observada e revertida.

Para iniciar um discovery público, abra uma issue no repositório responsável contendo apenas metadados e exemplos sanitizados. Documentos reais, segredos, dados fiscais e identidades não devem ser anexados ao GitHub.

O ecossistema adota controles em camadas:

• BFF same-origin com Microsoft Entra OIDC, sessão protegida e proxy autenticado;
• limites de upload, rate limiting, headers defensivos e sanitização de erros;
• identidade e X-Correlation-ID propagados entre navegador, BFF, API e processos externos;
• logs estruturados sem conteúdo TXT/XML ou credenciais;
• lint, tipos, testes, cobertura e builds de desenvolvimento/produção;
• Playwright desktop/mobile e Cypress de aceitação externa;
• CodeQL, análise estática, secret scanning, auditoria de dependências e Dependency Review;
• promoção controlada feature/fix → develop → development → main/master → production;
• releases versionadas, smoke tests e possibilidade de rollback.

Resultados gerados por IA são tratados como candidatos, não como verdade automática. Quando não há ground truth, a interface deve sinalizar menor confiança e exigir revisão humana.

O ecossistema já passou de uma prova isolada de parsing para uma plataforma web integrada. Entre os marcos recentes estão:

• fronteira web com BFF, Microsoft Entra OIDC e identidade propagada até a API;
• autorização e auditoria dos endpoints privilegiados da API (PR #43);
• HTTPS e isolamento de rede na implantação (PR #54);
• execução de múltiplos candidatos e fallback de IA com Ollama (PRs #52 e #57);
• extração do núcleo compartilhado XslSynth.Core (PR #61);
• editor transacional de TXT posicional, com validação de comprimento e regressão desktop/mobile (Epic #87);
• árvore XML navegável e polling resiliente dos candidatos gerados em segundo plano (Issues #127 e #140);
• diagnóstico estruturado por pathway e correlação ponta a ponta em finalização na API (PR #200).

flowchart LR
    NOW["Agora<br/>TXT posicional → XML<br/>parse · edição · múltiplos candidatos"] -->
    TRACE["Rastreabilidade<br/>campo TXT ↔ nó XML<br/>N:1 · 1:N · repetição"] -->
    ADAPTERS["Adapter SDK<br/>XML→XML · XML→TXT · TXT→JSON"] -->
    GOVERN["Mapping Registry<br/>versão · promoção · rollback · métricas"] -->
    SCALE["Escala<br/>catálogo reutilizável · templates · novos domínios"]

Prioridades arquiteturais:

1. concluir o contrato de rastreabilidade por campo entre TXT e XML;
2. estabilizar o modelo canônico e o SDK de adapters;
3. implementar XML→XML como próximo fluxo estruturado;
4. validar reconstrução XML→TXT sem perda posicional;
5. implementar TXT→JSON com JSON Schema e validação determinística;
6. evoluir governança de mappers, promoção, rollback e métricas;
7. ampliar o loop de auto-correção XSLT com evidência e revisão humana.

• Commits seguem Conventional Commits.
• Mudanças são desenvolvidas em branch e promovidas por PR.
• O fluxo de promoção passa primeiro pelo ambiente de desenvolvimento.
• Contratos entre repositórios exigem documentação, teste e handoff.
• Issues e PRs públicos nunca devem conter documentos reais ou segredos.
• Cada repositório mantém seus próprios comandos de build, quality gates e regras de agentes.

Licenciamento, uso de componentes de terceiros e condições de oferta devem ser verificados no repositório e no contexto de cada implantação.