# mrprompt/celesc architecture

> Architecture diagram of the GitHub repository mrprompt/celesc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mrprompt/celesc
- Repository: https://github.com/mrprompt/celesc

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Context / External Actors
  %% =========================
  Client["Aplicação do Cliente\n(ERP/Billing/etc)"]:::external
  Celesc["Celesc\n(Sistema externo)"]:::external
  Exchange["Filesystem / Meio de troca\n(pasta/SFTP/e-mail)"]:::external

  RemFile["Arquivo de Remessa\n(artefato de arquivo)"]:::artifact
  RetFile["Arquivo de Retorno/Recebido\n(artefato de arquivo)"]:::artifact

  %% =========================
  %% Library (Composer Package)
  %% =========================
  subgraph "Biblioteca (PHP + Composer) - Integração via troca de arquivos"
    direction TB

    Readme["README\n(Guia de uso)"]:::doc
    Composer["Composer Package\n(composer.json)"]:::doc

    Factory["Factory\n(Ponto central de instanciação)"]:::core

    subgraph "Módulo Shipment (Remessa) - serialização"
      direction TB
      ShipMod["Shipment (módulo)"]:::module
      SFile["Shipment\\File\n(arquivo inteiro)"]:::core

      subgraph "Shipment\\Partial (partes do arquivo)"
        direction TB
        SHeader["Shipment\\Partial\\Header"]:::component
        SDetail["Shipment\\Partial\\Detail"]:::component
        SFooter["Shipment\\Partial\\Footer"]:::component
      end
    end

    subgraph "Módulo Received (Retorno) - parsing"
      direction TB
      RecMod["Received (módulo)"]:::module
      RFile["Received\\File\n(arquivo inteiro)"]:::core

      subgraph "Received\\Partial (partes do arquivo)"
        direction TB
        RHeader["Received\\Partial\\Header"]:::component
        RDetail["Received\\Partial\\Detail"]:::component
        RFooter["Received\\Partial\\Footer"]:::component
      end
    end

    subgraph "Samples (exemplos de uso)"
      direction TB
      SampleBoot["samples/bootstrap.php"]:::sample
      SampleCart["samples/cart.php\n(mapping/parâmetros)"]:::sample
      SampleRem["samples/remessa.php\n(gera remessa)"]:::sample
      SampleRec["samples/recebido.php\n(lê retorno)"]:::sample
    end

    subgraph "Testes e Qualidade"
      direction TB
      PHPUnitCfg["PHPUnit Config\n(phpunit.xml.dist)"]:::quality

      subgraph "Tests - Shipment"
        direction TB
        TestsShipMod["tests/Shipment/"]:::quality
        ShipFileTest["tests/Shipment/FileTest.php"]:::quality
        TestsShipPartial["tests/Shipment/Partial/"]:::quality
      end

      subgraph "Tests - Received"
        direction TB
        TestsRecMod["tests/Received/"]:::quality
        RecFileTest["tests/Received/FileTest.php"]:::quality
        TestsRecPartial["tests/Received/Partial/"]:::quality
      end

      Travis["Travis CI\n(.travis.yml)"]:::quality
      Scrut["Scrutinizer\n(.scrutinizer.yml)"]:::quality
    end
  end

  %% =========================
  %% Relationships (Data Flows)
  %% =========================

  %% How client uses library
  Client -->|"usa|exemplos|guia"| Readme
  Client -->|"instancia/orquestra"| Factory

  %% Shipment (write/serialize)
  Factory -->|"cria"| SFile
  SFile -->|"compose"| SHeader
  SFile -->|"compose"| SDetail
  SFile -->|"compose"| SFooter
  SFile -->|"serializa"| RemFile
  RemFile -->|"write"| Exchange
  Exchange -.->|"envio/transferência\n(fora do código)"| Celesc

  %% Received (read/parse)
  Celesc -.->|"gera arquivo\n(fora do código)"| Exchange
  Exchange -->|"read"| RetFile
  Factory -->|"cria"| RFile
  RetFile -->|"parse"| RFile
  RFile -->|"delegates parsing"| RHeader
  RFile -->|"delegates parsing"| RDetail
  RFile -->|"delegates parsing"| RFooter
  RFile -->|"retorna dados/objetos"| Client

  %% Samples usage paths
  Client -->|"executa"| SampleRem
  Client -->|"executa"| SampleRec
  SampleBoot -->|"bootstrap"| SampleRem
  SampleBoot -->|"bootstrap"| SampleRec
  SampleCart -->|"mapping"| SampleRem
  SampleRem -->|"usa"| Factory
  SampleRec -->|"usa"| Factory

  %% Tests & CI relations (supporting)
  PHPUnitCfg -->|"executa"| ShipFileTest
  PHPUnitCfg -->|"executa"| RecFileTest
  TestsShipMod -->|"cobre"| ShipMod
  TestsShipPartial -->|"cobre"| SHeader
  TestsShipPartial -->|"cobre"| SDetail
  TestsShipPartial -->|"cobre"| SFooter
  TestsRecMod -->|"cobre"| RecMod
  TestsRecPartial -->|"cobre"| RHeader
  TestsRecPartial -->|"cobre"| RDetail
  TestsRecPartial -->|"cobre"| RFooter
  Travis -->|"roda"| PHPUnitCfg
  Scrut -->|"analisa"| Composer

  %% =========================
  %% Click Events (component mapping)
  %% =========================
  click Composer "https://github.com/mrprompt/celesc/blob/master/composer.json"
  click Readme "https://github.com/mrprompt/celesc/blob/master/README.md"
  click Factory "https://github.com/mrprompt/celesc/blob/master/src/Factory.php"

  click ShipMod "https://github.com/mrprompt/celesc/tree/master/src/Shipment/"
  click SFile "https://github.com/mrprompt/celesc/blob/master/src/Shipment/File.php"
  click SHeader "https://github.com/mrprompt/celesc/blob/master/src/Shipment/Partial/Header.php"
  click SDetail "https://github.com/mrprompt/celesc/blob/master/src/Shipment/Partial/Detail.php"
  click SFooter "https://github.com/mrprompt/celesc/blob/master/src/Shipment/Partial/Footer.php"

  click RecMod "https://github.com/mrprompt/celesc/tree/master/src/Received/"
  click RFile "https://github.com/mrprompt/celesc/blob/master/src/Received/File.php"
  click RHeader "https://github.com/mrprompt/celesc/blob/master/src/Received/Partial/Header.php"
  click RDetail "https://github.com/mrprompt/celesc/blob/master/src/Received/Partial/Detail.php"
  click RFooter "https://github.com/mrprompt/celesc/blob/master/src/Received/Partial/Footer.php"

  click SampleRem "https://github.com/mrprompt/celesc/blob/master/samples/remessa.php"
  click SampleRec "https://github.com/mrprompt/celesc/blob/master/samples/recebido.php"
  click SampleCart "https://github.com/mrprompt/celesc/blob/master/samples/cart.php"
  click SampleBoot "https://github.com/mrprompt/celesc/blob/master/samples/bootstrap.php"

  click PHPUnitCfg "https://github.com/mrprompt/celesc/blob/master/phpunit.xml.dist"
  click TestsShipMod "https://github.com/mrprompt/celesc/tree/master/tests/Shipment/"
  click ShipFileTest "https://github.com/mrprompt/celesc/blob/master/tests/Shipment/FileTest.php"
  click TestsShipPartial "https://github.com/mrprompt/celesc/tree/master/tests/Shipment/Partial/"
  click TestsRecMod "https://github.com/mrprompt/celesc/tree/master/tests/Received/"
  click RecFileTest "https://github.com/mrprompt/celesc/blob/master/tests/Received/FileTest.php"
  click TestsRecPartial "https://github.com/mrprompt/celesc/tree/master/tests/Received/Partial/"

  click Travis "https://github.com/mrprompt/celesc/blob/master/.travis.yml"
  click Scrut "https://github.com/mrprompt/celesc/blob/master/.scrutinizer.yml"

  %% =========================
  %% Styles (Color is critical)
  %% =========================
  classDef external fill:#E5E7EB,stroke:#6B7280,color:#111827,stroke-width:1px
  classDef artifact fill:#FFF7ED,stroke:#F59E0B,color:#111827,stroke-width:1px
  classDef core fill:#DBEAFE,stroke:#2563EB,color:#0B1B3A,stroke-width:1px
  classDef component fill:#E0F2FE,stroke:#0284C7,color:#082F49,stroke-width:1px
  classDef module fill:#EEF2FF,stroke:#4F46E5,color:#1E1B4B,stroke-width:1px
  classDef sample fill:#ECFDF5,stroke:#10B981,color:#064E3B,stroke-width:1px
  classDef quality fill:#FCE7F3,stroke:#DB2777,color:#4A044E,stroke-width:1px
  classDef doc fill:#F3F4F6,stroke:#9CA3AF,color:#111827,stroke-width:1px
```
