How mrprompt/celesc works
Tipo e propósito do projeto (o que o diagrama precisa comunicar)
Pelo README e pela árvore de arquivos, trata-se de uma biblioteca PHP (Composer package) para integração com a Celesc via “troca de arquivos” (não é um sistema web, nem serviço; é um *SDK/Library*). O valor arquitetural aqui está em mostrar:
• Como o consumidor (aplicação do cliente) usa a biblioteca
• Quais são os “módulos” internos principais (geração de remessa vs leitura de retorno/recebido)
• Como os arquivos são compostos (Header/Detail/Footer) e como o parsing/serialização acontece
• Pontos de extensão (Factory, modelos de File/Partial)
• Dependências externas (praticamente só PHP runtime/Composer; CI/testes são auxiliares)
Ou seja: o diagrama deve ser orientado a componentes de biblioteca e fluxo de dados (arquivos).
Leitura da estrutura (o que vira “caixa” no diagrama)
A estrutura indica dois domínios espelhados:
• src/Shipment/*
Remessa / envio: geração de arquivo para a Celesc
• src/Shipment/File.php (representa o arquivo inteiro)
• src/Shipment/Partial/{Header,Detail,Footer}.php (partes do arquivo)
• src/Received/*
Retorno / recebido: leitura/parse de arquivo vindo da Celesc
• src/Received/File.php
• src/Received/Partial/{Header,Detail,Footer}.php
• src/Factory.php
Ponto central provável para instanciar os modelos corretos (criação de objetos de “File” e/ou “Partial” por tipo/ação).
A pasta samples/ mostra os fluxos reais de uso:
• samples/remessa.php → geração de remessa
• samples/recebido.php → leitura retorno
• samples/cart.php → parâmetros necessários por transação (provável “catálogo”/mapping)
A pasta tests/ confirma essa decomposição e sugere que Header/Detail/Footer são unidades testáveis separadamente.
O que o README acrescenta (e o que enfatizar)
• “Integração … por meio de troca de arquivos”: não há API HTTP, o “contrato” é um formato de arquivo.
• Dependência: PHP 7.1+ (sem DB, sem filas etc).
• Exemplos existem e são parte essencial para explicar o “como usar”.
Então o diagrama deve destacar claramente:
• Input/Output = arquivos (geração e leitura)
• Consumidor da biblioteca (sistema do cliente)
• Celesc como sistema externo que produz/consome os arquivos
Filesystem → enviado à Celesc (fora do escopo do código, mas parte do processo)
Fluxo de retorno (read/parse)
Celesc → produz “Arquivo de Retorno”
2. Aplicação do Cliente → lê do Filesystem → fornece conteúdo para Received\File (via Factory ou parse)
Received\File → devolve estrutura/objetos/dados para a Aplicação do Cliente
Além disso, você pode ter setas de dependência:
• Factory → depende de Shipment\File e Received\File
• File → depende de Partial/*
4c) Padrões/Princípios arquiteturais a destacar
• Separação por domínio: Shipment vs Received (espelhados).
• Composição: File é composto por Header, Detail, Footer.
• Factory Pattern: centraliza criação e seleção de tipos/variações.
• Pipeline de transformação:
• Shipment: objetos → linhas/arquivo
• Received: linhas/arquivo → objetos
Isso é o coração do diagrama: “modelo interno” ↔ “formato de arquivo”.
4d) Tecnologias relevantes para rotular
• PHP 7.1+
• Composer package (composer.json)
• PHPUnit (testes)
• (Opcional) Travis CI / Scrutinizer (pipeline de qualidade)
Diretrizes específicas para “biblioteca / tool” (em vez de app full-stack)
Como não existe frontend/backend/database, o melhor diagrama é:
Diagrama de Contexto (C4 L1)
Mostra: Aplicação do Cliente ↔ Biblioteca Celesc ↔ Arquivos ↔ Celesc.
Diagrama de Componentes (C4 L2/L3 dentro da biblioteca)
Mostra: Factory, Shipment, Received, File, Partials.
Diagrama de Fluxo (sequence ou dataflow) para dois casos
• “Gerar Remessa”
• “Ler Retorno”
Esse terceiro diagrama é extremamente útil para biblioteca baseada em arquivos, porque evidencia entradas/saídas e responsabilidades.
Elementos obrigatórios no desenho (claridade máxima)
• Rótulos claros nas caixas com nome do componente e caminho (ex.: Shipment\File (src/Shipment/File.php)).
• Setas com verbos (ex.: “compose”, “serialize”, “parse”, “write file”, “read file”).
• Azul: componentes internos da biblioteca
• Cinza: atores/sistemas externos (Cliente, Celesc)
• Documento: artefatos “Arquivo de Remessa/Retorno”
• Tracejado: interações “fora do código” (ex.: envio via SFTP)
Checklist final (para garantir “o mais detalhado e fiel possível”)
• [ ] Separou claramente Shipment vs Received?
• [ ] Mostrou File e seus Partial/*?
• [ ] Indicou Factory como ponto de criação/orquestração?
• [ ] Mostrou “Arquivo” como artefato e o Filesystem/meio de troca?
• [ ] Desenhou os dois fluxos (gerar e ler)?
• [ ] Rotulou tecnologia (PHP+Composer) e, se útil, CI/testes em diagrama separado?
Se você fizer esses 2–3 diagramas (Contexto + Componentes + Fluxos), você captura praticamente toda a arquitetura relevante desse repositório com máxima precisão, sem inventar camadas que não existem (como API/DB), e com a granularidade ideal para uma biblioteca de integração por arquivos.