# comune-di-montesilvano/govpay-interaction-layer architecture

> Architecture diagram of the GitHub repository comune-di-montesilvano/govpay-interaction-layer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/comune-di-montesilvano/govpay-interaction-layer
- Repository: https://github.com/comune-di-montesilvano/govpay-interaction-layer

## Overview

GIL is a PHP platform for public entities using GovPay: operators manage debts and accounting flows in the backoffice, while citizens or counter staff can use a payment frontoffice. The graph separates those interfaces, asynchronous processing, and shared services/data. README-level integrations and capabilities are retained; source evidence is sampled and partial, so uncertain implementation links are omitted rather than inferred.

Main entry points: [`backoffice/src/Controllers/PendenzeController.php`](https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/backoffice/src/Controllers/PendenzeController.php) (Backoffice), [`app/Services/RendicontazioneEngineService.php`](https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Services/RendicontazioneEngineService.php) (Settlement engine), [`frontoffice/public/index.php`](https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/frontoffice/public/index.php) (Frontoffice), [`backoffice/src/Controllers/ReportRagioneriaController.php`](https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/backoffice/src/Controllers/ReportRagioneriaController.php) (Accounting reports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_backoffice["Backoffice"]
  node_frontoffice["Frontoffice<br/>[index.php]"]
  node_reporting["Accounting reports"]
end

subgraph group_operations["Operations and jobs"]
  node_jobs["Job worker<br/>[WorkerKernel.php]"]
  node_massive["Bulk debt processing"]
  node_rend_engine["Settlement engine"]
end

subgraph group_shared["Shared services and data"]
  node_settings[("Settings")]
  node_database[("Application database<br/>[Connection.php]")]
  node_debt_types["Debt types"]
  node_flows[("Accounting flows")]
  node_mailer["Mail delivery<br/>[MailerService.php]"]
  node_logger["Logging<br/>[Logger.php]"]
  node_config_loader["Bootstrap configuration<br/>[ConfigLoader.php]"]
end

subgraph group_integrations["Payment integrations"]
  node_govpay["GovPay API"]
  node_checkout["pagoPA Checkout<br/>[PaymentNotice.php]"]
  node_biz["Biz Events"]
  node_appio["App IO<br/>[AppIoService.php]"]
  node_payment_model["Payment model<br/>[Pagamento.php]"]
  node_config_model["Configuration model<br/>[Configurazione.php]"]
end

node_operators(("Operators"))
node_citizens(("Citizens / staff"))

node_operators -->|"manage debts"| node_backoffice
node_citizens -->|"request payment"| node_frontoffice
node_operators -->|"review flows"| node_reporting
node_backoffice -->|"requests API"| node_govpay
node_frontoffice -->|"starts checkout"| node_checkout
node_frontoffice -.->|"fetches debt"| node_govpay
node_backoffice -->|"reads types"| node_debt_types
node_backoffice -->|"reads settings"| node_settings
node_reporting -->|"queries flows"| node_flows
node_reporting -->|"reads settings"| node_settings
node_jobs -->|"dispatches rows"| node_massive
node_jobs -->|"uses connection"| node_database
node_rend_engine -->|"records settlements"| node_flows
node_rend_engine -->|"fetches debt"| node_govpay
node_rend_engine -->|"sends notice"| node_appio
node_rend_engine -->|"sends email"| node_mailer
node_settings -->|"reads and writes"| node_database
node_settings -->|"falls back to"| node_config_loader
node_backoffice -->|"uses payment data"| node_payment_model
node_frontoffice -->|"uses payment data"| node_payment_model
node_logger -.->|"logs separately"| node_database
node_backoffice -.->|"configures GovPay"| node_config_model
node_reporting -.->|"checks coverage"| node_biz

click node_backoffice "https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/backoffice/src/Controllers/PendenzeController.php"
click node_frontoffice "https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/frontoffice/public/index.php"
click node_reporting "https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/backoffice/src/Controllers/ReportRagioneriaController.php"
click node_jobs "https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Services/Jobs/WorkerKernel.php"
click node_massive "https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Services/Jobs/MassivePendenzeProcessor.php"
click node_rend_engine "https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Services/RendicontazioneEngineService.php"
click node_settings "https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Config/SettingsRepository.php"
click node_database "https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Database/Connection.php"
click node_debt_types "https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Database/EntrateRepository.php"
click node_flows "https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Database/FlussiRendicontazioniRepository.php"
click node_mailer "https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Services/MailerService.php"
click node_govpay "https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Services/GovPayClientFactory.php"
click node_checkout "https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/pagopa-clients/generated-clients/checkout-ec-v1/checkout-ec-client/lib/Model/PaymentNotice.php"
click node_biz "https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/pagopa-clients/generated-clients/biz-events-v1/biz-events-client/lib/Api/PaidNoticeRESTAPIsApi.php"
click node_appio "https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Services/AppIoService.php"
click node_payment_model "https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/govpay-clients/generated-clients/backoffice-v1/backoffice-client/lib/Model/Pagamento.php"
click node_config_model "https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/govpay-clients/generated-clients/backoffice-v1/backoffice-client/lib/Model/Configurazione.php"
click node_logger "https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Logger.php"
click node_config_loader "https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Config/ConfigLoader.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_backoffice,node_frontoffice,node_reporting toneBlue
class node_jobs,node_massive,node_rend_engine toneAmber
class node_settings,node_database,node_debt_types,node_flows,node_mailer,node_logger,node_config_loader toneMint
class node_govpay,node_checkout,node_biz,node_appio,node_payment_model,node_config_model toneRose
class node_operators,node_citizens toneIndigo
```

## Components

### User interfaces

- [Backoffice](https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/backoffice/src/Controllers/PendenzeController.php): `backoffice/src/Controllers/PendenzeController.php`
- [Frontoffice](https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/frontoffice/public/index.php): `frontoffice/public/index.php`
- [Accounting reports](https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/backoffice/src/Controllers/ReportRagioneriaController.php): `backoffice/src/Controllers/ReportRagioneriaController.php`

### Operations and jobs

- [Job worker](https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Services/Jobs/WorkerKernel.php): `app/Services/Jobs/WorkerKernel.php`
- [Bulk debt processing](https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Services/Jobs/MassivePendenzeProcessor.php): `app/Services/Jobs/MassivePendenzeProcessor.php`
- [Settlement engine](https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Services/RendicontazioneEngineService.php): `app/Services/RendicontazioneEngineService.php`

### Shared services and data

- [Settings](https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Config/SettingsRepository.php): `app/Config/SettingsRepository.php`
- [Application database](https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Database/Connection.php): `app/Database/Connection.php`
- [Debt types](https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Database/EntrateRepository.php): `app/Database/EntrateRepository.php`
- [Accounting flows](https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Database/FlussiRendicontazioniRepository.php): `app/Database/FlussiRendicontazioniRepository.php`
- [Mail delivery](https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Services/MailerService.php): `app/Services/MailerService.php`
- [Logging](https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Logger.php): `app/Logger.php`
- [Bootstrap configuration](https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Config/ConfigLoader.php): `app/Config/ConfigLoader.php`

### Payment integrations

- [GovPay API](https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Services/GovPayClientFactory.php): `app/Services/GovPayClientFactory.php`
- [pagoPA Checkout](https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/pagopa-clients/generated-clients/checkout-ec-v1/checkout-ec-client/lib/Model/PaymentNotice.php): `pagopa-clients/generated-clients/checkout-ec-v1/checkout-ec-client/lib/Model/PaymentNotice.php`
- [Biz Events](https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/pagopa-clients/generated-clients/biz-events-v1/biz-events-client/lib/Api/PaidNoticeRESTAPIsApi.php): `pagopa-clients/generated-clients/biz-events-v1/biz-events-client/lib/Api/PaidNoticeRESTAPIsApi.php`
- [App IO](https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/app/Services/AppIoService.php): `app/Services/AppIoService.php`
- [Payment model](https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/govpay-clients/generated-clients/backoffice-v1/backoffice-client/lib/Model/Pagamento.php): `govpay-clients/generated-clients/backoffice-v1/backoffice-client/lib/Model/Pagamento.php`
- [Configuration model](https://github.com/comune-di-montesilvano/govpay-interaction-layer/blob/main/govpay-clients/generated-clients/backoffice-v1/backoffice-client/lib/Model/Configurazione.php): `govpay-clients/generated-clients/backoffice-v1/backoffice-client/lib/Model/Configurazione.php`

### Other components

- **Operators**
- **Citizens / staff**

## Connections

- Operators → Backoffice: manage debts (evidence: `README.md`)
- Citizens / staff → Frontoffice: request payment (evidence: `README.md`)
- Operators → Accounting reports: review flows (evidence: `README.md`)
- Backoffice → GovPay API: requests API (evidence: `backoffice/src/Controllers/PendenzeController.php`)
- Frontoffice → pagoPA Checkout: starts checkout (evidence: `README.md`)
- Frontoffice → GovPay API: fetches debt
- Backoffice → Debt types: reads types (evidence: `backoffice/src/Controllers/PendenzeController.php`)
- Backoffice → Settings: reads settings (evidence: `backoffice/src/Controllers/PendenzeController.php`)
- Accounting reports → Accounting flows: queries flows (evidence: `backoffice/src/Controllers/ReportRagioneriaController.php`)
- Accounting reports → Settings: reads settings (evidence: `backoffice/src/Controllers/ReportRagioneriaController.php`)
- Job worker → Bulk debt processing: dispatches rows (evidence: `app/Services/Jobs/WorkerKernel.php`)
- Job worker → Application database: uses connection (evidence: `app/Services/Jobs/WorkerKernel.php`)
- Settlement engine → Accounting flows: records settlements (evidence: `app/Services/RendicontazioneEngineService.php`)
- Settlement engine → GovPay API: fetches debt (evidence: `app/Services/RendicontazioneEngineService.php`)
- Settlement engine → App IO: sends notice (evidence: `app/Services/RendicontazioneEngineService.php`)
- Settlement engine → Mail delivery: sends email (evidence: `app/Services/RendicontazioneEngineService.php`)
- Settings → Application database: reads and writes (evidence: `app/Config/SettingsRepository.php`)
- Settings → Bootstrap configuration: falls back to (evidence: `app/Config/Config.php`)
- Backoffice → Payment model: uses payment data (evidence: `backoffice/src/Controllers/PendenzeController.php`)
- Frontoffice → Payment model: uses payment data (evidence: `frontoffice/public/index.php`)
- Logging → Application database: logs separately
- Backoffice → Configuration model: configures GovPay (evidence: `backoffice/src/Controllers/PendenzeController.php`)
- Accounting reports → Biz Events: checks coverage