# comune-di-montesilvano/comunicapa architecture

> Architecture diagram of the GitHub repository comune-di-montesilvano/comunicapa, 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/comunicapa
- Repository: https://github.com/comune-di-montesilvano/comunicapa

## Overview

ComunicaPA is a public-administration platform for asynchronous, high-volume communications. Operators create campaigns through the admin portal, upload recipient data and attachments, then launch delivery; background queues process channel-specific sends and track outcomes for search, reporting and citizen access. The backend also supports one-off external API submissions, address verification, enrichment, signature checks and operational controls. The README documents these capabilities, while sampled source confirms selected controller, service, settings and persistence relationships; links for unsampled integrations are limited to documented relationships.

Main entry points: [`apps/frontend-admin/src/App.tsx`](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/frontend-admin/src/App.tsx) (Admin portal), [`apps/backend/src/campaigns/campaigns.service.ts`](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/campaigns/campaigns.service.ts) (Campaign management), [`apps/backend/src/entities/campaign.entity.ts`](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/entities/campaign.entity.ts) (Application database), [`apps/backend/src/campaigns/campaigns.controller.ts`](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/campaigns/campaigns.controller.ts) (Campaign API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portals["User portals"]
  node_admin["Admin portal<br/>[App.tsx]"]
  node_citizen["Citizen portal<br/>[App.tsx]"]
end

subgraph group_campaigns["Campaign workflow"]
  node_api["External API"]
  node_campaign_api["Campaign API"]
  node_campaign_logic["Campaign management"]
  node_enrichment["Track enrichment"]
  node_pdf_extract["PDF extraction<br/>[pdf_extractor.py]"]
end

subgraph group_delivery["Delivery and tracking"]
  node_queue["Notification queues"]
  node_processor["Notification processing"]
  node_channels["Delivery channels"]
  node_postal_tracking["Postal tracking"]
  node_notification_search["Notification search"]
  node_engines["Engine controls"]
end

subgraph group_services["Verification and services"]
  node_address_verification["Address verification"]
  node_pdnd["PDND authentication"]
  node_signature["Signature verification"]
  node_citizen_api["Citizen communications"]
end

subgraph group_platform["Platform and state"]
  node_attachments["Attachments"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_settings["Runtime settings"]
  node_database[("Application database<br/>[campaign.entity.ts]")]
end

node_operator(("Operator"))
node_redis[("Redis")]
node_providers["Channel providers"]

node_operator -->|"operates"| node_admin
node_admin -->|"manages campaigns"| node_campaign_api
node_api -.->|"submits notifications"| node_campaign_logic
node_campaign_api -->|"delegates to"| node_campaign_logic
node_campaign_logic -->|"persists campaign data"| node_database
node_campaign_api -->|"uploads chunks"| node_attachments
node_campaign_logic -.->|"enqueues sends"| node_queue
node_queue -.->|"stores jobs"| node_redis
node_processor -.->|"dispatches delivery"| node_channels
node_channels -->|"sends via"| node_providers
node_postal_tracking -->|"checks tracking"| node_providers
node_engines -->|"pauses or resumes"| node_queue
node_engines -->|"reads job counts"| node_database
node_notification_search -->|"reads delivery history"| node_database
node_admin -->|"starts enrichment"| node_enrichment
node_enrichment -.->|"extracts PDF data"| node_pdf_extract
node_admin -->|"verifies addresses"| node_address_verification
node_address_verification -.->|"obtains credentials"| node_pdnd
node_pdnd -->|"reads credentials"| node_settings
node_admin -->|"checks signatures"| node_signature
node_citizen -->|"authenticates"| node_auth
node_citizen -->|"views communications"| node_citizen_api
node_citizen_api -->|"reads recipient records"| node_database
node_admin -->|"searches notifications"| node_notification_search
node_campaign_logic -->|"resolves attachments"| node_attachments

click node_admin "https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/frontend-admin/src/App.tsx"
click node_citizen "https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/frontend-citizen/src/App.tsx"
click node_api "https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/external-api/external-notifications.controller.ts"
click node_campaign_api "https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/campaigns/campaigns.controller.ts"
click node_campaign_logic "https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/campaigns/campaigns.service.ts"
click node_enrichment "https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/enrichment/enrichment.service.ts"
click node_pdf_extract "https://github.com/comune-di-montesilvano/comunicapa/blob/main/services/pdf-extractor/app/pdf_extractor.py"
click node_queue "https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/queue/notification-queues.service.ts"
click node_processor "https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/queue/notification.processor.ts"
click node_channels "https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/channels/channel.interface.ts"
click node_postal_tracking "https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/channels/postal/postal-status-sync.service.ts"
click node_notification_search "https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/notifications-search/notifications-search.service.ts"
click node_engines "https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/engines/engines.controller.ts"
click node_address_verification "https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/channels/registro-imprese/registro-imprese.service.ts"
click node_pdnd "https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/pdnd/pdnd-auth.service.ts"
click node_signature "https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/signature-verification/signature-verification.service.ts"
click node_citizen_api "https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/citizen/citizen.controller.ts"
click node_attachments "https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/attachments/attachment.service.ts"
click node_auth "https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/auth/auth.service.ts"
click node_settings "https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/settings/app-settings.service.ts"
click node_database "https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/entities/campaign.entity.ts"

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_admin,node_citizen toneBlue
class node_api,node_campaign_api,node_campaign_logic,node_enrichment,node_pdf_extract,node_redis toneAmber
class node_queue,node_processor,node_channels,node_postal_tracking,node_notification_search,node_engines toneMint
class node_address_verification,node_pdnd,node_signature,node_citizen_api toneRose
class node_attachments,node_auth,node_settings,node_database,node_operator,node_providers toneIndigo
```

## Components

### User portals

- [Admin portal](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/frontend-admin/src/App.tsx): `apps/frontend-admin/src/App.tsx`
- [Citizen portal](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/frontend-citizen/src/App.tsx): `apps/frontend-citizen/src/App.tsx`

### Campaign workflow

- [External API](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/external-api/external-notifications.controller.ts): `apps/backend/src/external-api/external-notifications.controller.ts`
- [Campaign API](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/campaigns/campaigns.controller.ts): `apps/backend/src/campaigns/campaigns.controller.ts`
- [Campaign management](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/campaigns/campaigns.service.ts): `apps/backend/src/campaigns/campaigns.service.ts`
- [Track enrichment](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/enrichment/enrichment.service.ts): `apps/backend/src/enrichment/enrichment.service.ts`
- [PDF extraction](https://github.com/comune-di-montesilvano/comunicapa/blob/main/services/pdf-extractor/app/pdf_extractor.py): `services/pdf-extractor/app/pdf_extractor.py`

### Delivery and tracking

- [Notification queues](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/queue/notification-queues.service.ts): `apps/backend/src/queue/notification-queues.service.ts`
- [Notification processing](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/queue/notification.processor.ts): `apps/backend/src/queue/notification.processor.ts`
- [Delivery channels](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/channels/channel.interface.ts): `apps/backend/src/channels/channel.interface.ts`
- [Postal tracking](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/channels/postal/postal-status-sync.service.ts): `apps/backend/src/channels/postal/postal-status-sync.service.ts`
- [Notification search](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/notifications-search/notifications-search.service.ts): `apps/backend/src/notifications-search/notifications-search.service.ts`
- [Engine controls](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/engines/engines.controller.ts): `apps/backend/src/engines/engines.controller.ts`

### Verification and services

- [Address verification](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/channels/registro-imprese/registro-imprese.service.ts): `apps/backend/src/channels/registro-imprese/registro-imprese.service.ts`
- [PDND authentication](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/pdnd/pdnd-auth.service.ts): `apps/backend/src/pdnd/pdnd-auth.service.ts`
- [Signature verification](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/signature-verification/signature-verification.service.ts): `apps/backend/src/signature-verification/signature-verification.service.ts`
- [Citizen communications](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/citizen/citizen.controller.ts): `apps/backend/src/citizen/citizen.controller.ts`

### Platform and state

- [Attachments](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/attachments/attachment.service.ts): `apps/backend/src/attachments/attachment.service.ts`
- [Authentication](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/auth/auth.service.ts): `apps/backend/src/auth/auth.service.ts`
- [Runtime settings](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/settings/app-settings.service.ts): `apps/backend/src/settings/app-settings.service.ts`
- [Application database](https://github.com/comune-di-montesilvano/comunicapa/blob/main/apps/backend/src/entities/campaign.entity.ts): `apps/backend/src/entities/campaign.entity.ts`

### Other components

- **Operator**
- **Redis**
- **Channel providers**

## Connections

- Operator → Admin portal: operates (evidence: `README.md`)
- Admin portal → Campaign API: manages campaigns (evidence: `README.md`)
- External API → Campaign management: submits notifications
- Campaign API → Campaign management: delegates to (evidence: `apps/backend/src/campaigns/campaigns.controller.ts`)
- Campaign management → Application database: persists campaign data (evidence: `apps/backend/src/campaigns/campaigns.service.ts`)
- Campaign API → Attachments: uploads chunks (evidence: `apps/backend/src/campaigns/campaigns.controller.ts`)
- Campaign management → Notification queues: enqueues sends (evidence: `apps/backend/src/campaigns/campaigns.service.ts`)
- Notification queues → Redis: stores jobs (evidence: `README.md`)
- Notification processing → Delivery channels: dispatches delivery
- Delivery channels → Channel providers: sends via (evidence: `README.md`)
- Postal tracking → Channel providers: checks tracking (evidence: `README.md`)
- Engine controls → Notification queues: pauses or resumes (evidence: `apps/backend/src/engines/engines.controller.ts`)
- Engine controls → Application database: reads job counts (evidence: `apps/backend/src/engines/engines.controller.ts`)
- Notification search → Application database: reads delivery history (evidence: `apps/backend/src/notifications-search/notifications-search.service.ts`)
- Admin portal → Track enrichment: starts enrichment (evidence: `README.md`)
- Track enrichment → PDF extraction: extracts PDF data
- Admin portal → Address verification: verifies addresses (evidence: `README.md`)
- Address verification → PDND authentication: obtains credentials
- PDND authentication → Runtime settings: reads credentials (evidence: `apps/backend/src/pdnd/pdnd-auth.service.ts`)
- Admin portal → Signature verification: checks signatures (evidence: `README.md`)
- Citizen portal → Authentication: authenticates (evidence: `README.md`)
- Citizen portal → Citizen communications: views communications (evidence: `apps/backend/src/citizen/citizen.controller.ts`)
- Citizen communications → Application database: reads recipient records (evidence: `apps/backend/src/citizen/citizen.controller.ts`)
- Admin portal → Notification search: searches notifications (evidence: `README.md`)
- Campaign management → Attachments: resolves attachments (evidence: `apps/backend/src/campaigns/campaigns.service.ts`)