Ci sono lavori che non iniziano davvero nel momento in cui decidi di farli. Iniziano molto prima, in silenzio, mentre stai facendo altro.
Un sito da mettere online. Un bug da risolvere in fretta. Un database che regge per mesi e poi, all’improvviso, ti obbliga a fermarti e capire. Un problema affrontato una volta, poi una seconda, poi una terza, finché smette di essere un caso isolato e diventa un metodo.
In tutti questi lunghi mesi mi è successo questo. Ho scritto codice assistito dagli LLM, lanciato progetti, corretto errori, raffinato soluzioni. Ho accumulato pattern, abitudini, scorciatoie buone e cicatrici ancora migliori. Tutte cose utili, tutte cose vere, tutte cose che funzionavano. Ma esistevano soprattutto in un luogo fragile: la memoria.
Poi arriva la domanda che sembra innocua e invece spalanca una crepa:
«Ma come funziona esattamente questo tuo sistema?»
A quel punto ti accorgi di sapere la risposta, ma di non avere un posto preciso dove mostrarla. E quando una conoscenza vive solo nella testa di chi l’ha costruita, almeno la visione generale ovviamente, non è ancora davvero conoscenza condivisibile. È esperienza, certo. Ma è anche rumore, dispersione, rischio di dover ricominciare da capo ogni volta.
Da lì è nato questo manuale.
Non da un’ambizione editoriale. Non da una strategia. Da una mancanza.
Il problema che non sembrava un problema
Negli ultimi mesi, sempre con l'ausilio di LLM, ho costruito quattro siti. Non quattro esercizi di stile, non quattro prototipi lasciati a metà, ma quattro progetti reali, pubblicati, usati da persone vere.
C’è Runtime Radio, che tiene insieme streaming, podcast, redazione e presenza editoriale. Ci sono DISINTELLIGENZA e FDCA, due progetti di festival con iscrizioni, votazioni, approvazioni e definizione di classifiche e gestione dei partecipanti. E poi c’è SimonePizziWebSite, che è insieme portfolio, blog e laboratorio permanente.
Per molto tempo li ho considerati progetti distinti, e in parte lo sono. Hanno obiettivi diversi, tono diverso, pubblico diverso. Ma sotto la superficie, col passare del tempo, è emersa una verità piuttosto netta: stavano tutti parlando la stessa lingua architetturale.
Una lingua che avevo definito strada facendo. Un pezzo alla volta. Una correzione dopo l’altra. Una lingua fatta di scelte ripetute, di convenzioni consolidate, di errori che avevano smesso di essere errori solo perché erano diventati lezione.
Il punto è che quella lingua esisteva soltanto nella mia testa.
E nella testa non c’è ordine editoriale. Non c’è indice. Non c’è chiarezza. C’è un archivio disordinato che funziona finché sei tu a maneggiarlo. Quando devi trasmetterlo, spiegandolo ad altri o persino a te stesso qualche mese dopo, scopri che non basta più.
Per questo ho scritto un manuale. Per prendere qualcosa che funzionava di fatto e trasformarlo in qualcosa che fosse leggibile, consultabile, riusabile.
La scelta che ha tenuto insieme tutto
C’è una confessione tecnica che posso fare con assoluta serenità: non uso Node.js lato server. Non uso framework PHP. Non ho container. Non ho pipeline CI/CD da brochure enterprise. Non ho una costellazione di servizi cloud in abbonamento che continuano a emettere ricevute mentre dormo.
I miei siti, molto spesso, girano su hosting condivisi da pochi euro al mese.
Eppure sono veloci. Sono sicuri. Sono manutenibili. Soprattutto, sono sotto controllo.
La ragione non è un trucco. È una scelta architetturale. Una scelta precisa, difesa nel tempo, che nel manuale ho chiamato The Thin Stack.
L’idea di fondo è semplice: separare con nettezza ciò che oggi viene spesso tenuto insieme per abitudine, non per necessità.
Da una parte c’è il frontend, cioè il piano della forma, dell’interazione, dell’esperienza visiva. Qui uso React 19, TypeScript, Tailwind. Qui stanno le animazioni, la tipografia, il comportamento dell’interfaccia, la qualità percepita. È il luogo dove l’applicazione prende la sua forma più elegante e contemporanea. Questo strato viene compilato, ottimizzato e servito come asset statico.
Dall’altra parte c’è il backend, cioè il piano dei dati, della logica, della sicurezza. Qui uso PHP nativo e SQLite, oppure MySQL quando il progetto richiede un salto di scala. Nessun framework, nessun ORM, nessuna impalcatura sproporzionata. Solo ciò che serve davvero: PHP, PDO, struttura chiara, responsabilità ben definite.
Tra i due mondi c’è un contratto semplice e leggibile: API REST.
Il frontend non sa nulla del database. Il backend non sa nulla di React. E proprio questa distanza, che potrebbe sembrare una rinuncia, diventa il punto di forza dell’intero sistema.
Il frontend bello, il backend onesto.
Se dovessi riassumere l’intero manuale in una sola frase, forse userei questa.
Per anni lo sviluppo web ha dato per scontato che per avere un’interfaccia moderna bisognasse accettare anche un’infrastruttura sempre più pesante. Io volevo capire se fosse davvero inevitabile. Se fosse possibile avere la qualità visiva e la piacevolezza di sviluppo del mondo React senza rinunciare alla sobrietà, alla leggerezza e al controllo di un backend PHP ben scritto.
La risposta, per quanto mi riguarda, è sì.
Un manuale nato dalle cicatrici
Sarebbe molto elegante raccontare che tutto questo è nato da una visione chiarissima fin dall’inizio. Sarebbe anche falso.
Questo manuale non nasce da una teoria perfetta. Nasce da problemi veri. Da notti complicate. Da passaggi delicati in cui il codice ha smesso di essere un esercizio e si è trasformato in responsabilità.
La notte in cui SQLite ha chiesto conto
A febbraio 2026, Runtime Radio attraversava una fase di crescita importante. Il traffico aumentava da mesi, il sistema reggeva, tutto sembrava sotto controllo. Poi una notte il database ha cominciato a restituire il conto.
Il problema, tecnicamente, era molto preciso. Avevo attivato il WAL mode di SQLite. Sulla carta sembrava la scelta giusta: più performance, migliore gestione delle scritture concorrenti, comportamento moderno. In pratica, dentro il contesto concreto di un hosting condiviso Apache, si è rivelato un azzardo. Il file di lock del WAL rimaneva appeso. Le letture si corrompevano. La stabilità spariva proprio nel momento in cui serviva di più.
Non è stato un problema accademico. È stato un problema reale, con un sito vero da tenere in piedi.
Nel giro di meno di ventiquattr’ore il database è stato migrato a MySQL, senza perdita di dati. Non come dimostrazione teorica di bravura, ma perché non c’era alternativa e bisognava farlo bene, subito.
Nel manuale questa storia non compare come una leggenda retrospettiva ripulita per fare scena. Compare per quello che è stata: una lezione tecnica seria, documentata passo per passo, con i tre script PHP che hanno reso possibile il trasferimento.
La morale non è “SQLite è sbagliato”. Sarebbe una conclusione pigra. La vera lezione è molto più utile: SQLite è una scelta eccellente finché lo scenario resta coerente con i suoi punti di forza. Quando il progetto cambia scala, bisogna avere un’uscita chiara, non improvvisata. Il manuale serve anche a questo.
L’attacco che imitava la normalità
Come se non bastasse, pochi giorni dopo la migrazione è arrivato un secondo colpo. Più sottile, più strano, in un certo senso persino più istruttivo.
Runtime Radio è stato investito da un attacco che non aveva l’aspetto cinematografico del grande assedio digitale. Non c’erano effetti speciali, non c’era teatralità. C’era una cosa peggiore: la somiglianza con il traffico legittimo.
Migliaia di bot ostili simulavano i crawler di Telegram, Facebook e X, cioè quei sistemi che leggono un link quando viene condiviso per generare l’anteprima corretta. Il sito, come molti altri costruiti con questa architettura, intercettava quelle richieste per iniettare i meta tag giusti nell’HTML. Una funzione utilissima, normalmente innocua. In quel caso, però, era diventata il varco.
Ogni richiesta finta provocava una query al database. E quando le richieste diventano mille al secondo, la differenza tra funzione utile e vulnerabilità operativa si assottiglia molto in fretta.
I grafici del traffico hanno iniziato a disegnare pareti verticali.
La risposta è arrivata in tre tempi.
Prima: contenimento immediato, con una priorità molto chiara. Lo streaming audio non doveva fermarsi. Runtime Radio è, prima di tutto, una radio. Tutto il resto può vacillare per qualche ora. Il cuore no.
Seconda fase: una cache precompilata capace di servire i bot da file statici, senza interrogare il database.
Terza fase: un sistema ibrido che distinguesse in modo esplicito tra traffico umano e traffico bot, senza lasciare che il secondo mettesse in ginocchio il primo.
Anche questo è finito dentro il manuale. Non perché faccia scena raccontare un disastro, ma perché la documentazione utile non nasce solo dalle parti che hanno funzionato bene. Nasce soprattutto dai punti in cui il sistema è stato costretto a dimostrare se era davvero progettato per resistere.
E in quella storia c’è anche una cosa che nel mondo tecnico si dimentica spesso: il codice da solo non basta sempre.
C’erano persone. C’erano mani e teste che hanno aiutato a rimettere insieme il quadro.
Carlo Santagostino, Walter Sbano, Peppe Pugliese, Valerio Galano.
La resilienza non è soltanto una qualità dell’architettura. A volte è una qualità della comunità che hai intorno.
Perché renderlo gratuito
Me lo sono chiesto anch’io, più di una volta.
Scrivere questo manuale ha richiesto tempo vero. Non una distrazione del fine settimana. Settimane di lavoro, di revisione, di ripensamenti, di decisioni su cosa meritasse di entrare e cosa invece dovesse restare fuori.
Avrei potuto venderlo. Avrei potuto trasformarlo in un prodotto chiuso, o usarlo come esca per una mailing list, o infilarlo dietro un paywall con qualche formula elegante per far sembrare tutto inevitabile.
Non l’ho fatto.
L’ho lasciato libero per una ragione molto semplice: la conoscenza tecnica vale di più quando circola.
Gran parte di quello che so l’ho imparato leggendo altri. Blog tecnici, documentazioni open source, post scritti da persone che avevano deciso di raccontare un problema e una soluzione senza proteggere gelosamente ogni riga come se fosse una reliquia privata. In un modo o nell’altro, quasi tutti costruiamo su qualcosa che qualcuno ha avuto la generosità di spiegare.
Restituire fa parte del patto.
C’è anche un’altra motivazione, meno nobile forse, ma molto vera: documentare costringe a capire meglio. Alcuni pattern li usavo da anni. Funzionavano. Eppure li ho capiti davvero fino in fondo solo quando mi sono trovato a doverli scrivere con chiarezza, senza scorciatoie mentali, senza appoggiarmi al solito “tanto poi ci penso dopo”.
In questo senso il manuale è anche un promemoria per il mio futuro. Un modo per lasciare tracce leggibili al me stesso che riaprirà un progetto dopo mesi e avrà bisogno di ricordarsi non solo cosa aveva fatto, ma soprattutto perché.
Che cosa c’è dentro, davvero
Il titolo completo del manuale è React + PHP: The Thin Stack — Il protocollo miniCMS per Web App moderne. È la prima edizione, datata marzo 2026.
Dentro ci sono cinque parti e un allegato, distribuiti in diciotto capitoli. Ma al di là del numero, quello che conta è la struttura.
Parte I — La Visione
Qui c’è il Manifesto. È la parte in cui spiego il problema di fondo: da un lato la maturità straordinaria del frontend contemporaneo, dall’altro la sproporzione crescente della complessità infrastrutturale rispetto ai bisogni reali della maggior parte dei siti. È il terreno teorico del libro, ma non nel senso accademico del termine. È il punto in cui si chiarisce da dove nasce la scelta di tenere insieme React e PHP senza farli intralciare a vicenda.
Parte II — L’Architettura
Qui si entra nelle fondamenta. Struttura delle cartelle, logica del deploy, separazione tra sorgenti e runtime, strategia per il database, gestione degli ambienti, dipendenze frontend. È la parte in cui si decide se il progetto sarà ordinato o diventerà una soffitta con luce scarsa nel giro di qualche mese.
Parte III — I Componenti
Questa è la cucina vera e propria. Il backend in PHP, il bridge frontend-backend in TypeScript, la gestione degli identificatori, l’autenticazione, i media, la sanitizzazione, l’editor dei contenuti, il caricamento degli asset. Qui non ci sono slogan. Ci sono i pezzi con cui il sistema funziona ogni giorno.
Parte IV — Il Flusso Operativo
Qui il progetto smette di essere un insieme di mattoni e comincia a comportarsi come un organismo editoriale. Il ciclo di vita dei contenuti, la programmazione reale, le bozze, la pubblicazione, la sicurezza, il prerender SEO, l’RSS, la newsletter. È la parte che riguarda il movimento continuo del sito una volta che è vivo.
Parte V — I Casi Reali
È probabilmente la sezione più sincera di tutte. La migrazione da SQLite a MySQL di Runtime Radio. Il modulo portfolio di SimonePizziWebSite. La logica dei festival DISINTELLIGENZA e FDCA, con iscrizioni, workflow, votazioni e protezioni anti-frode. Non esempi astratti, ma materiale che arriva direttamente da progetti che hanno avuto bisogno di funzionare sul serio.
Allegato — Boilerplate Checklist
Infine c’è una checklist operativa, pensata per accompagnare l’avvio di un nuovo progetto: setup, sicurezza, database, frontend, contenuti, SEO, deploy, e tutte le variazioni necessarie in base al tipo di sito.
Una delle cose a cui tenevo di più era che il manuale potesse essere usato in due modi diversi, senza risultare scomodo in nessuno dei due.
Si può leggere come un libro, dall’inizio alla fine, seguendo il percorso logico. Oppure si può usare come reference, aprendo direttamente il capitolo che serve in quel momento. Per questo ho lavorato molto sui rimandi interni: ogni volta che un pattern dipende da qualcosa spiegato altrove, il collegamento è dichiarato.
Non volevo un testo ornamentale. Volevo uno strumento.
A chi parla questo manuale
La risposta più onesta è: non a tutti.
Non parla a chi vuole un sito pronto in un pomeriggio. Per quel mondo esistono strumenti eccellenti, da WordPress a Webflow, passando per piattaforme che fanno esattamente quello che promettono. Sarebbe assurdo fingere il contrario.
Non parla nemmeno a chi lavora su sistemi enterprise giganteschi, con milioni di utenti simultanei, carichi distribuiti, infrastrutture elastiche e requisiti che appartengono a un’altra categoria di complessità. Esistono architetture più adatte, ed è giusto che esistano.
Questo manuale parla a un’altra zona del web. Una zona meno rumorosa, ma molto più abitata di quanto si dica.
Parla al developer che conosce React e non ha nessuna voglia di dover montare ogni volta un’intera filiera backend solo per avere API pulite, autenticazione, contenuti e un database ordinato.
Parla al freelance che deve consegnare siti belli, rapidi, sicuri e manutenibili a clienti che non hanno budget né bisogno di una macchina infrastrutturale da convention tecnologica.
Parla a chi costruisce per realtà vive e spesso fragili: autori, musicisti, radio, festival, progetti culturali, persone che vogliono una presenza digitale propria, indipendente, governabile.
E forse parla soprattutto a chi continua a pensare che il web possa ancora essere una cosa umana. Non un luogo governato soltanto da piattaforme, abbonamenti, interfacce preconfezionate e dipendenze che si moltiplicano da sole. Ma uno spazio in cui si possa ancora costruire con precisione, con misura, con consapevolezza.
Un web fatto da persone, per persone.
Sì, lo so: detta così rischia quasi di sembrare una frase troppo grande. Ma resta il punto da cui parto.
Perché proprio The Thin Stack
Il titolo non è arrivato subito. Ho valutato opzioni più descrittive, più didascaliche, più “tecniche” nel senso in cui spesso si usa questa parola quando si vuole sembrare seri. Nessuna, però, aveva il suono giusto.
Alcune erano troppo fredde. Altre sembravano nomi di prodotto. Altre ancora spiegavano troppo e quindi non dicevano niente.
The Thin Stack è rimasto perché è esattamente ciò che volevo nominare.
Uno stack sottile.
Non povero. Non sacrificato. Non semplificato per ingenuità. Sottile nel senso migliore del termine: essenziale, calibrato, senza ingombri superflui.
C’è una frase di Saint-Exupéry che nel manuale compare esplicitamente e che qui vale la pena riprendere:
«La perfezione si raggiunge non quando non c’è più niente da aggiungere, ma quando non c’è più niente da togliere.»
Ecco, il senso del titolo sta lì. Non nella ricerca di una presunta purezza minimalista, ma nella volontà di togliere peso inutile fino a lasciare soltanto ciò che serve davvero a far funzionare un sistema in produzione.
Non la soluzione più appariscente. La soluzione più sobria che continua a reggere quando arriva il traffico, quando arriva l’errore, quando arriva il giorno in cui bisogna mettere mano di nuovo al codice.
Dove si trova
Il manuale è disponibile gratuitamente nel repository GitHub dedicato. I contenuti sono presenti in Markdown, leggibili direttamente online capitolo per capitolo, ed esiste anche una versione PDF compilata, impaginata come un vero libro tecnico.
Ovviamente è anche presente nella nostra HUB dei Progetti in questo sito e scaricabile direttamente nella versione PDF
Non ci sono paywall. Non serve lasciare un’email. Non c’è un modulo da compilare per meritarsi il diritto di leggerlo.
Volevo che fosse semplice da raggiungere e semplice da usare. Fine.
Se deciderai di leggerlo e ci troverai un errore, una svista, un passaggio poco chiaro, una soluzione migliorabile, mi farà piacere saperlo. La documentazione, se è viva, non è una lapide. È un oggetto che continua a raffinarsi.
E se ti sarà utile, condividilo.
Non tanto per me. O non solo.
Condividilo per la persona che, magari stasera, si ritrova davanti a un crash in produzione e non ha bisogno di grandi teorie, ma di una traccia concreta, leggibile, onesta. Di qualcuno che abbia già sbattuto contro un problema simile e abbia deciso di raccontarlo bene.
In fondo, questo manuale nasce anche per quello.
Per chi prova a costruire cose vere senza una squadra infinita alle spalle.
Per chi lavora con mezzi normali e pretende comunque risultati seri.
Per chi non ha smesso di credere che un sito ben progettato possa essere, ancora oggi, una piccola forma di indipendenza.
— Simone Pizzi, marzo 2026
P.S. — Il database di Runtime Radio, quello che a febbraio ha ceduto sotto pressione, oggi gira su MySQL ed è stabile. La radio non si è mai fermata. Lo streaming ha continuato a vivere anche durante l’attacco. Alcune architetture non sono immortali. Ma se sono pensate bene, sanno resistere abbastanza da darti il tempo di salvarle.