Paperopoli: un Comune finto costruito sul serio

Paperopoli è un Comune immaginario, ma non è una semplice scenografia digitale. Ha uffici, servizi, tributi, scadenze, un portale istituzionale e cittadini che possono accedere con un'identità digitale. Dispone inoltre di un assistente che risponde alle domande utilizzando i contenuti pubblicati dall'ente e avrà servizi attraverso i quali le stesse persone potranno presentare richieste, seguire pratiche e pagare.

Nomi, luoghi e dati sono inventati.

L'architettura no.

L'idea alla base del progetto è abbastanza semplice: se devo costruire una demo della Pubblica Amministrazione, voglio che sia finta soltanto dove deve necessariamente esserlo.

Non mi interessa disegnare un pulsante “Entra con SPID” che apre una falsa schermata di autenticazione, così come non mi interessa simulare un pagamento cambiando una scritta da “da pagare” a “pagato”. Allo stesso modo, non voglio realizzare un sito che assomigli soltanto vagamente a quello di un Comune.

Paperopoli prova invece a mettere insieme, nello stesso ambiente, i diversi pezzi di un servizio pubblico digitale, usando come riferimento ciò che la PA italiana ha già definito: il Codice dell'Amministrazione Digitale, le Linee guida di design, il Modello Comuni di Designers Italia, il Piano Triennale per l'informatica nella PA, i sistemi nazionali di identità digitale e i contratti delle piattaforme come pagoPA.

Non è quindi il tentativo di inventare un mio modello di Comune digitale. È quasi il contrario: provare a vedere cosa succede quando quei modelli vengono presi sul serio e fatti lavorare insieme, non soltanto citati nei documenti di progetto.

Le Linee guida di design per i siti e i servizi digitali della PA, emanate nell'ambito del CAD, richiamano principi come accessibilità, usabilità, chiarezza, affidabilità, semplicità, qualità e interoperabilità. Il Modello Comuni di Designers Italia traduce parte di questi principi in architettura dell'informazione, componenti, template e flussi pensati specificamente per i servizi comunali.

Il Piano Triennale 2024-2026, nell'aggiornamento 2026, allarga ulteriormente il quadro introducendo o ribadendo concetti come digital e mobile first, cloud first, API-first, digital identity only, user-centric, once only, openness e protezione dei dati by design. Non sono parole che ho aggiunto a posteriori per descrivere Paperopoli: sono il riferimento con cui provo a decidere come devono comunicare i suoi pezzi e quali vincoli debbano rispettare.

Un solo posto dove nasce l'informazione

Il primo pezzo è il portale, perché è lì che l'informazione viene prodotta, organizzata e resa disponibile ai cittadini.

Paperopoli utilizza un'architettura dei contenuti basata sul Modello Comuni. Il CMS gestisce servizi, uffici, scadenze, costi, requisiti e gli altri contenuti che una redazione comunale pubblica normalmente sul sito. Da questi stessi contenuti nasce anche la conoscenza utilizzata dall'assistente.

Questo punto per me è fondamentale. Se la redazione modifica sul sito la scadenza di un tributo, non dovrebbe esistere una seconda procedura nella quale qualcuno deve ricordarsi di aggiornare anche “i dati dell'intelligenza artificiale”. Quando la stessa informazione viene mantenuta in due archivi diversi, prima o poi gli archivi divergono, anche se all'inizio la duplicazione sembra innocua.

Paperopoli parte quindi dal principio opposto: la redazione scrive una volta sola e gli altri componenti utilizzano quella fonte.

Il portale espone i contenuti pubblicati attraverso un contratto HTTP. Un adattatore li trasforma in un corpus strutturato e il server MCP li rende disponibili agli assistenti.

In forma semplificata:

Ogni campo valorizzato di una scheda servizio può diventare un passaggio citabile: “Come fare”, “Cosa serve”, “Scadenze”, “Costi” e così via. Ogni passaggio porta con sé un identificativo, una versione e un hash, così da rendere possibile non soltanto il recupero dell'informazione, ma anche la sua identificazione e verifica.

Sul database utilizzato dalla demo questo produce attualmente 44 aree e 333 passaggi. La redazione, però, non deve conoscere niente di tutto questo: continua semplicemente a pubblicare il sito, mentre la trasformazione e l'esposizione dei contenuti vengono gestite dagli strati tecnici sottostanti.

Anche il confine tecnico è intenzionale. Il server MCP non conosce il database del portale e non gli interessa se dietro ci siano SQLite, SQL Server, PostgreSQL o un CMS completamente diverso. Il corpus parla il linguaggio del dominio, non quello delle mie tabelle.

Una scadenza è una scadenza qualunque sia la piattaforma che la conserva, così come un costo rimane un costo e una modalità di accesso a un servizio mantiene la propria natura anche se il sito viene rifatto in PHP. L'adattatore serve proprio a questo: separare il modello informativo dall'implementazione concreta del CMS.

È una scelta coerente anche con un principio più generale del Piano Triennale: sistemi interoperabili per progettazione, API-first e componenti che non abbiano bisogno di conoscere l'implementazione interna degli altri sistemi. In questo modo ogni parte può evolvere senza costringere tutte le altre a conoscere i dettagli con cui è stata realizzata.

L'assistente non è la fonte

Quando il cittadino fa una domanda, l'assistente di Paperopoli non cerca la risposta dentro un enorme prompt che contiene regolamenti, tariffe e scadenze. Il prompt stabilisce il comportamento dell'assistente, mentre i contenuti arrivano dal Comune.

Il server MCP espone gli strumenti attraverso cui il modello recupera i passaggi pertinenti e costruisce la risposta sulla base di quelli. Il modello può cambiare, così come possono cambiare il fornitore o la tecnologia utilizzata per interrogarlo, ma la fonte rimane la stessa.

È una distinzione che considero importante anche al di là dell'intelligenza artificiale: il dato appartiene all'ente, non al fornitore dell'assistente che in quel momento lo sta utilizzando. L'assistente dovrebbe quindi essere considerato un componente di accesso e interpretazione, non il luogo nel quale l'informazione viene conservata o certificata.

Nel corpus entrano inoltre soltanto contenuti pubblicati. Una bozza presente nel CMS non deve poter diventare accidentalmente una risposta al cittadino, perché lo stato editoriale dell'informazione è parte del suo significato e non un dettaglio secondario.

E non tutto viene ridotto a testo. Una tariffa è un importo, una scadenza è una data, possibilmente associata a un periodo di validità, e il fatto che un servizio sia prenotabile può essere rappresentato come un valore strutturato. Quando l'informazione esiste in questa forma, il corpus la conserva. Non provo a dedurla dalla prosa attraverso espressioni regolari o altre euristiche per poi chiamarla “dato certificato”.

Se un'informazione non esiste nella sorgente, il limite deve rimanere visibile. Non è compito dell'assistente colmare automaticamente ogni lacuna, soprattutto quando il risultato potrebbe sembrare più preciso di quanto sia realmente.

Vale anche per il tempo. Un'informazione può essere autentica, correttamente versionata e avere un hash perfettamente valido, ma essere comunque vecchia. Una scadenza del 30 aprile senza anno è un ottimo esempio: la provenienza è certa, ma l'utilità per il cittadino è molto meno evidente.

Anche gli errori devono essere semanticamente chiari. Se il corpus non è ancora disponibile, il tool restituisce un errore e non una lista vuota. Una lista vuota potrebbe essere interpretata dal modello come “questa informazione non esiste” e trasformarsi in una risposta sbagliata data con grande sicurezza.

Sono poche righe di codice, ma nei servizi pubblici poche righe di codice possono essere la differenza tra uno stato tecnico e un'affermazione rivolta a un cittadino. Per questo anche i casi anomali devono essere progettati con la stessa attenzione riservata ai percorsi normali.

Identità digitale, non una schermata che le somiglia

Paperopoli non si ferma alla parte informativa, perché per utilizzare un servizio personale bisogna sapere chi è il cittadino e bisogna farlo attraverso un meccanismo di identità che non sia soltanto una rappresentazione grafica.

Il progetto include quindi un Relying Party OpenID Connect Federation in profilo SPID/CIE scritto in .NET. Il flusso implementa authorization code con PKCE, request object firmato, autenticazione private_key_jwt, UserInfo cifrata, refresh, logout, risoluzione della catena di fiducia e registrazione nella federazione.

L'ambiente di prova utilizza le immagini Docker ufficiali AgID per il Trust Anchor e l'OpenID Provider CIE, e il flusso viene verificato end-to-end contro questa infrastruttura. In questo modo l'integrazione non viene rappresentata soltanto attraverso una schermata di login, ma viene esercitata lungo il percorso tecnico previsto dall'ambiente di test.

Questo non significa che Paperopoli sia collegato alla federazione SPID/CIE di produzione. Non lo è. Il codice implementa il profilo e viene provato contro l'infrastruttura di test, ma non è mai stato collaudato contro un gestore SPID reale. Sarebbe quindi scorretto scrivere diversamente o presentarlo come un'integrazione pronta per l'esercizio.

Anche qui la distinzione è voluta. Il Piano Triennale parla di digital identity only: l'identità digitale non dovrebbe essere un accessorio inserito alla fine nell'interfaccia, ma uno dei componenti su cui costruire il servizio fin dall'inizio.

Dopo l'autenticazione, il cittadino viene trasferito all'area dei servizi attraverso un handoff SSO firmato. È da quel momento che comincia la parte che considero più interessante per Paperopoli, perché l'identità acquista valore soltanto quando consente di svolgere un'attività concreta.

Dopo il login devono esserci servizi veri

Autenticare un cittadino per mostrargli il suo nome in alto a destra non serve a molto. L'obiettivo di Paperopoli è arrivare a servizi completi: iniziare una richiesta, inserire i dati necessari, allegare documenti quando servono, inviarla, seguirne lo stato e, dove previsto, effettuare un pagamento.

Anche questa parte non sarà progettata partendo da schermate inventate liberamente. Designers Italia mette a disposizione un modello specifico per i servizi digitali comunali, costruito studiando le principali interazioni tra cittadino ed ente: servizi nei quali si completa un adempimento, si presenta una richiesta o si riceve una prestazione. Il modello comprende flussi, prototipi, componenti e template da utilizzare come riferimento.

L'idea è usare quella grammatica anche a Paperopoli, non per riprodurre meccanicamente ogni elemento, ma per costruire servizi riconoscibili, coerenti e comprensibili per chi li utilizza.

I primi casi saranno volutamente normali: TARI, certificati e richieste che un Comune gestisce ogni giorno. Proprio perché non voglio dimostrare che si possa costruire una demo spettacolare, voglio vedere se si riesce a costruire bene la parte meno spettacolare della trasformazione digitale: un cittadino che entra, trova quello che gli serve, presenta una richiesta e arriva alla fine senza dover capire come è organizzato internamente l'ente.

Qui entra anche un altro principio del Piano Triennale: once only. Quando il Comune conosce già un'informazione e può legittimamente riutilizzarla, l'architettura dovrebbe essere pensata per non chiederla inutilmente di nuovo al cittadino. Questo non significa soltanto precompilare un campo, ma progettare il servizio in modo che il cittadino non debba ripetere informazioni già disponibili e utilizzabili.

Paperopoli è il posto in cui questi principi possono diventare codice e, proprio per questo, essere messi alla prova. La loro validità non viene dimostrata dichiarandoli, ma osservando cosa succede quando devono sostenere un flusso completo.

E se il servizio deve essere pagato?

Qui entra un altro progetto: PagoPaDevKit.

PagoPaDevKit è un progetto open source indipendente che ho costruito per poter sviluppare e testare localmente integrazioni pagoPA senza collegarsi al Nodo reale e senza movimentare denaro. Non è un clone grafico del Checkout e non vuole simulare il pagamento limitandosi all'interfaccia: riproduce invece le superfici attraversate da un Ente Creditore, utilizzando come riferimento i contratti OpenAPI e WSDL ufficiali, tra cui GPD Debt Positions v3, i servizi SOAP nodeForPsp e paForNode, le ricevute, i flussi di rendicontazione, il FlussoRiversamento e ApiConfig.

L'obiettivo è che Paperopoli utilizzi questa infrastruttura come base per i propri servizi a pagamento. Quando, per esempio, un servizio genera una posizione debitoria, non voglio che il codice inserisca semplicemente una riga nella tabella Pagamenti della demo. Voglio che attraversi lo stesso tipo di contratto che attraverserebbe un Ente Creditore.

La posizione viene quindi creata e pubblicata attraverso GPD, il cittadino può entrare nel flusso di Checkout, il Nodo e l'Ente Creditore si scambiano le chiamate previste, il pagamento produce una ricevuta e la rendicontazione segue il proprio flusso. PagoPaDevKit implementa già questo ciclo nell'ambiente locale, compreso il recupero delle ricevute e la gestione dei flussi di rendicontazione.

Naturalmente non è pagoPA. Non si collega alla piattaforma reale, non muove denaro e non è destinato alla produzione: è un ambiente di sviluppo indipendente. Ma è proprio questa separazione a renderlo utile a Paperopoli.

Posso costruire un servizio comunale completo senza fingere che un pagamento sia avvenuto e senza avere bisogno di una piattaforma reale. Il codice applicativo viene sviluppato contro contratti modellati su quelli ufficiali, mentre l'infrastruttura locale si occupa di impersonare le controparti necessarie.

Quando Paperopoli mostrerà una posizione TARI da pagare, quindi, il percorso non dovrà essere:

clic → schermata finta → pagamento riuscito.

Dovrà essere un vero flusso applicativo all'interno dell'ambiente dimostrativo, con una posizione che nasce, viene gestita, produce un esito e può essere collegata agli stati successivi della pratica.

Per me è una differenza sostanziale, perché consente di verificare non soltanto l'aspetto del servizio, ma anche il comportamento dei componenti che lo rendono possibile.

Un Comune che si lascia controllare

Paperopoli non vuole soltanto dichiarare di utilizzare il Modello Comuni: vuole anche poter verificare quanto effettivamente lo rispetta.

Nel progetto è integrato quindi anche pa-website-validator-ng. Il portale può avviare una scansione e mostrare i risultati prodotti dal validator, così da rendere visibili non soltanto le conformità, ma anche le aree nelle quali il progetto si discosta dal modello.

Non tutti i controlli devono necessariamente passare. Esiste una pagina chiamata “Deviazioni dichiarate” che raccoglie ciò che Paperopoli non rispetta e spiega perché. Alcune deviazioni dipendono da scelte deliberate della demo, mentre altre derivano dal fatto molto semplice che Paperopoli non esiste.

Un Comune immaginario non può avere un vero dominio istituzionale e non può depositare presso AgID la propria dichiarazione di accessibilità. Non provo a nasconderlo, perché anche questo fa parte della descrizione corretta dell'ambiente.

Se l'obiettivo è costruire un sistema basato su fonti e comportamenti verificabili, la stessa regola deve valere per il progetto. Dire cosa non c'è è importante quasi quanto mostrare quello che c'è, soprattutto quando si vuole che una demo possa essere letta come un laboratorio e non come una promessa implicita di conformità.

Non una nuova architettura della PA

La cosa che voglio evitare più di tutte è presentare Paperopoli come “il mio modello di Comune digitale”. Non lo è, e non vuole esserlo.

Il punto è proprio utilizzare quello che esiste già. Il CAD dà il quadro, mentre le Linee guida di design stabiliscono principi e regole per siti e servizi digitali della PA. Designers Italia offre per i Comuni un modello costruito sui bisogni dei cittadini, con architettura dell'informazione, interfacce, codice e modelli di servizio.

Il Piano Triennale indica la direzione architetturale attraverso concetti come API-first, identità digitale, centralità dell'utente, once only, apertura, interoperabilità e protezione dei dati fin dalla progettazione. L'aggiornamento 2026 ribadisce inoltre interoperabilità, semplificazione, misurabilità dei risultati e user centricity dei servizi pubblici digitali.

SPID e CIE hanno i propri protocolli e le proprie regole, mentre pagoPA ha i propri contratti. Paperopoli prova a stare dentro questi binari, senza sostituirli con un'architettura inventata appositamente per la demo.

Non sempre ci riuscirà. Quando non ci riesce, però, la deviazione deve poter essere individuata, descritta e, se possibile, motivata. Per questo preferisco definirlo un laboratorio piuttosto che un prodotto: un luogo nel quale le regole esistenti vengono messe in relazione e sottoposte a verifica pratica.

A cosa serve allora Paperopoli?

Serve a rendere visibile l'architettura, soprattutto quella parte che nei diagrammi tende a scomparire.

In un diagramma tutto è facile: il cittadino accede con SPID, il servizio recupera i dati, viene generata una posizione pagoPA, l'utente paga, il sistema aggiorna la pratica e l'assistente lo aiuta quando serve. Sono sei rettangoli e qualche freccia.

Quando provi a costruirli, però, ogni freccia diventa un contratto. Bisogna chiedersi chi possiede il dato, chi lo aggiorna, come si sa che è pubblicato e come si distingue una bozza. Bisogna decidere come rappresentare una scadenza, come autenticare davvero il cittadino e come trasferire quell'identità a un altro servizio. Occorre inoltre capire come nasce una posizione debitoria, come se ne riceve l'esito e come si dimostra che il sito costruito rispetta davvero il modello che si dichiara di aver seguito.

Paperopoli serve a questo: trasformare quelle frecce in qualcosa che gira, che può essere osservato e che, quando non funziona, permette di capire dove si trova il problema.

Per chi lavora in un Comune può essere un modo per vedere concretamente cosa dovrebbe esserci dietro alcune parole che ricorrono continuamente nei progetti di trasformazione digitale. Per chi sviluppa può diventare un ambiente nel quale provare integrazioni senza dover sostituire ogni piattaforma nazionale con un if (demo). Per me è soprattutto un modo di mettere alla prova un'idea molto semplice: non abbiamo bisogno di inventare ogni volta come dovrebbe funzionare la PA digitale.

Gran parte delle regole, dei modelli e dei contratti esiste già. La parte difficile è farli lavorare insieme, rispettando i confini di ciascuno e rendendo esplicite le responsabilità che nei progetti teorici restano spesso implicite.

Paperopoli prova a farlo in un posto dove si può sperimentare, sbagliare, cambiare codice e ricominciare senza coinvolgere un cittadino reale.

 Il Comune è finto, i cittadini sono finti e i soldi sono finti, ma il modo in cui sto cercando di far comunicare questi pezzi è deliberatamente il meno finto possibile.

👉 Paperopoli: https://paperopoli.derrigo.it/
👉 Codice: https://github.com/fderrigo/DuckburgSmartCity
👉 PagoPaDevKit: https://github.com/fderrigo/PagoPaDevKit