Come Ho Costruito AgencyPilot: Stack, Architettura e Lezioni da 50+ Siti WordPress

Gestire siti WordPress per conto terzi è un mestiere che ti insegna una cosa sola: i problemi arrivano sempre alle 2 di notte. Dopo 15 anni a costruire e mantenere siti WordPress per la Pubblica Amministrazione italiana, agenzie e PMI, ho deciso di risolvere il problema alla radice. Ho costruito AgencyPilot.

Questo non è un tutorial generico. È la storia di come un freelance con troppi clienti ha trasformato i propri script interni in un SaaS che oggi gestisce oltre 50 siti WordPress da un’unica dashboard. Con i numeri veri, gli errori veri, e le decisioni tecniche che hanno funzionato (e quelle che no).

TL;DR — Il Riassunto per Chi Ha Fretta

AgencyPilot è un SaaS per la gestione multi-sito WordPress costruito con Next.js 15 per il frontend, FastAPI (Python) per il backend, PostgreSQL come database, e Claude API per i report automatici. Il progetto è nato da script Bash che usavo per gestire i siti dei miei clienti. Oggi include monitoraggio uptime, security scanning, aggiornamenti automatici con rollback, report AI-powered per i clienti, e un portale white-label. L’intero percorso da script a SaaS ha richiesto 14 mesi.

Il Problema: Gestire 30+ Siti WordPress con Foglio Excel e SSH

Nel 2024 gestivo 34 siti WordPress. La mia “dashboard” era un foglio Google con 12 colonne: URL, versione WP, ultimo backup, ultimo aggiornamento, contatto cliente, scadenza hosting. Lo aggiornavo a mano. Ogni lunedì mattina, 2 ore per controllare che tutto fosse a posto.

Il workflow era questo:

1. SSH su ogni server (4 server diversi, 34 siti)
2. Controllare la versione di WordPress e dei plugin
3. Verificare che i backup cron fossero partiti
4. Scansionare i log per errori 500 o tentativi di brute force
5. Aggiornare il foglio Google

Due ore. Ogni settimana. E quando un aggiornamento rompeva qualcosa (succede più spesso di quanto pensi), la mia giornata saltava.

Ho provato ManageWP e MainWP. ManageWP funziona, ma il modello di pricing per-sito diventa insostenibile sopra i 20 siti se vuoi le feature che servono davvero. MainWP è self-hosted e gratuito, ma l’interfaccia è rimasta al 2018 e manca di report automatici per i clienti. Nessuno dei due aveva quello che volevo: un portale dove il cliente vede lo stato del suo sito senza mandarmi un’email.

La Decisione dello Stack: Perché Next.js + FastAPI e Non WordPress

La prima domanda che mi fanno è: “Ma se sei un developer WordPress, perché non hai costruito AgencyPilot su WordPress?”

Risposta breve: perché WordPress non è progettato per essere una dashboard real-time con autenticazione multi-tenant, websocket per alert live, e processing di background jobs pesanti.

Risposta lunga: ci ho provato. Il primo prototipo era un plugin WordPress con custom post type per i “siti gestiti” e una REST API custom (come spiegato nella guida agli endpoint REST API personalizzati). Ha funzionato per 3 mesi. Poi le query sono diventate lente, la gestione dei cron job inaffidabile, e l’autenticazione JWT un incubo da mantenere.

Lo stack finale:

Il punto chiave: WordPress resta al centro dell’ecosistema. Il plugin “Agent Connector” installato su ogni sito gestito espone endpoint autenticati che AgencyPilot interroga. WordPress fa quello che sa fare meglio (gestire contenuti). AgencyPilot fa il resto.

Agent Connector: Il Plugin WordPress che Tiene Tutto Insieme

Il componente più critico di AgencyPilot non è la dashboard. È un plugin WordPress di 847 righe che vive su ogni sito gestito.

L’Agent Connector fa 5 cose:

1. Health check endpoint — risponde a /wp-json/agencypilot/v1/health con versione WP, PHP, plugin attivi, tema, e metriche di performance
2. Security scan — controlla permessi file, presenza di file sospetti in /uploads, headers di sicurezza, e configurazione di wp-config.php
3. Update manager — elenca aggiornamenti disponibili ed esegue aggiornamenti singoli o batch con snapshot pre-update
4. Log collector — invia gli ultimi 100 righi del debug.log e dell’error.log Apache/Nginx
5. Backup verifier — conferma che l’ultimo backup esista, la dimensione sia coerente (variazione <20% dal precedente), e il checksum sia valido

L’autenticazione funziona con API key rotate ogni 30 giorni. Niente JWT, niente OAuth. Una chiave API con HMAC-SHA256 signing per ogni richiesta. Semplice, verificabile, e se viene compromessa il blast radius è un solo sito.

// Esempio semplificato dell'autenticazione Agent Connector
add_filter('rest_pre_dispatch', function($result, $server, $request) {
    if (strpos($request->get_route(), '/agencypilot/') === false) {
        return $result;
    }
    
    $api_key = $request->get_header('X-AgencyPilot-Key');
    $signature = $request->get_header('X-AgencyPilot-Sig');
    $timestamp = $request->get_header('X-AgencyPilot-Ts');
    
    // Verifica timestamp (finestra di 5 minuti)
    if (abs(time() - intval($timestamp)) > 300) {
        return new WP_Error('expired', 'Request expired', ['status' => 401]);
    }
    
    // Verifica HMAC
    $stored_key = get_option('agencypilot_api_key');
    $expected_sig = hash_hmac('sha256', $timestamp . $request->get_route(), $stored_key);
    
    if (!hash_equals($expected_sig, $signature)) {
        return new WP_Error('unauthorized', 'Invalid signature', ['status' => 401]);
    }
    
    return $result;
}, 10, 3);

Un errore che ho fatto all’inizio: usare la stessa API key per tutti i siti di un cliente. Quando uno dei siti è stato migrato su un altro hosting dal cliente (senza avvisarmi), la chiave è finita in un backup pubblico. Ho dovuto rigenerare tutte le chiavi di quel cliente. Da quel giorno, una chiave per sito. Sempre.

Report AI con Claude API: Da 8 Ore a 12 Minuti

La feature che ha convinto i primi 3 clienti a pagare non è il monitoraggio. Sono i report automatici generati con Claude API.

Prima di AgencyPilot, generavo report mensili a mano. Per ogni cliente: screenshot di Google Analytics, note sugli aggiornamenti fatti, problemi risolti, raccomandazioni. Un report = 45 minuti. Con 12 clienti attivi, facevo 8+ ore al mese solo di reportistica.

Adesso AgencyPilot raccoglie automaticamente:

• Uptime del mese (percentuale e minuti di downtime)
• Aggiornamenti eseguiti (WordPress core, plugin, temi) con dettaglio versioni
• Scansioni sicurezza: vulnerabilità trovate e risolte
• Performance: tempo medio di risposta, Core Web Vitals dove disponibili
• Backup: tutti completati, dimensioni, eventuali anomalie

Questi dati vengono passati a Claude API con un prompt strutturato che chiede un report in linguaggio naturale, scritto per un cliente non tecnico. Il report esce in italiano, con tono professionale ma comprensibile.

# Esempio del prompt per Claude API (semplificato)
report_prompt = f"""
Genera un report mensile per il sito {site.domain}.
Periodo: {month_name} {year}.

DATI:
- Uptime: {uptime_pct}% ({downtime_minutes} minuti di downtime)
- Aggiornamenti: {updates_count} completati ({core_updates} core, {plugin_updates} plugin)
- Sicurezza: {vulns_found} vulnerabilità rilevate, {vulns_fixed} risolte
- Backup: {backups_completed}/{backups_expected} completati
- Tempo risposta medio: {avg_response_ms}ms

REGOLE:
- Scrivi in italiano, tono professionale ma accessibile
- Se uptime < 99.5%, spiega il motivo del downtime
- Se ci sono vulnerabilità non risolte, evidenziale come priorità
- Chiudi con 2-3 raccomandazioni specifiche per il mese successivo
- Massimo 400 parole
"""

Il costo? Circa 0.03€ per report con Claude Sonnet. Per 50 siti, meno di 2€ al mese. Il risparmio in ore? Dalle 8 ore manuali a 12 minuti di review dei report generati. Non li mando senza controllarli (Claude a volte enfatizza troppo i problemi minori), ma la review è veloce.

Monitoraggio Uptime: La Feature Che Sembra Semplice (Non Lo È)

Il monitoraggio uptime sembra banale. Fai un ping HTTP ogni minuto, se non risponde manda un alert. Ho pensato la stessa cosa.

I problemi reali:

• Falsi positivi — Un timeout di rete non significa che il sito è down. Ho dovuto implementare un sistema a 3 check: se il primo fallisce, aspetta 30 secondi, riprova da un endpoint diverso, aspetta altri 30 secondi, riprova una terza volta. Solo se tutti e 3 falliscono, scatta l’alert.
• SSL expiry — Alcuni hosting rinnovano il certificato SSL con un ritardo di ore. Il sito risponde 200 ma il browser mostra “non sicuro”. Adesso controllo anche la scadenza SSL e avviso 7 giorni prima.
• Degradazione lenta — Un sito che risponde in 8 secondi è tecnicamente “up” ma praticamente inutilizzabile. Ho aggiunto soglie di performance: se il tempo di risposta supera i 3 secondi per 3 check consecutivi, ricevo un alert di “slow response”.
• WordPress cron failure — wp-cron.php è notoriamente inaffidabile su hosting condivisi. AgencyPilot verifica che i cron job WordPress stiano effettivamente girando controllando i timestamp delle ultime esecuzioni via Agent Connector.

L’architettura del monitoring usa Celery beat per schedulare i check. Ogni sito ha un task Celery dedicato che gira ogni 60 secondi. I risultati finiscono in PostgreSQL con una retention di 90 giorni (poi archiviati in tabelle mensili compresse). I grafici nella dashboard usano questi dati direttamente. Niente servizi di terze parti.

Sicurezza Automatizzata: Scansioni Settimanali e Patch Management

La sicurezza WordPress è il motivo per cui i clienti restano. Non per la dashboard carina. Ma perché sanno che qualcuno controlla i loro siti ogni settimana senza che debbano chiederlo.

Il security scanner di AgencyPilot controlla:

1. Vulnerabilità plugin note — Interroga il database WPScan API per ogni plugin installato. Se un plugin ha una CVE nota, alert immediato.
2. Permessi file — wp-config.php deve essere 440 o 400. /uploads non deve avere file .php. .htaccess non deve essere scrivibile dal web server.
3. Headers di sicurezza — Verifica la presenza di X-Content-Type-Options, X-Frame-Options, Strict-Transport-Security, Content-Security-Policy.
4. Utenti admin — Controlla che non esista un utente “admin” (il target #1 di brute force) e che tutti gli admin abbiano 2FA attivo.
5. File integrity — Confronta i checksum dei file core WordPress con quelli ufficiali. Se qualcosa non corrisponde, potrebbe essere un’iniezione.

Un caso reale: a Novembre 2025, il plugin “Contact Form 7” ha avuto una vulnerabilità critica (CVE-2024-7924, arbitrary file upload). AgencyPilot ha rilevato la vulnerabilità su 23 dei 47 siti gestiti entro 2 ore dalla pubblicazione della CVE. Ho aggiornato tutti e 23 i siti in batch dalla dashboard in 4 minuti. Senza AgencyPilot, li avrei scoperti al prossimo giro di controlli manuali. Forse dopo 3 giorni. Forse dopo che qualcuno li aveva già sfruttati.

Gli Errori: Cosa Non Ha Funzionato

Non tutto è andato liscio. Tre errori grossi che ho fatto:

Errore 1: Multi-tenant dal giorno uno. Ho costruito l’architettura multi-tenant con row-level security di PostgreSQL fin dal primo commit. Peccato che per i primi 6 mesi avessi un solo utente: me stesso. Ho speso 3 settimane a implementare isolamento tenant, permessi granulari, e billing per-tenant prima di avere un singolo cliente pagante. Avrei dovuto partire con un’app single-tenant e aggiungere il multi-tenant dopo il terzo cliente.

Errore 2: Microservizi troppo presto. Il primo design aveva 4 servizi separati: auth service, monitoring service, security scanner, report generator. Ognuno con il suo database. La complessità operativa era assurda per un progetto gestito da una persona sola. Ho consolidato tutto in un monolite FastAPI con moduli separati. La codebase è diventata 60% più piccola e il deploy da 20 minuti a 3.

Errore 3: UI prima della logica. Ho speso un mese a disegnare la dashboard in Figma prima di validare che il backend funzionasse. Quando ho iniziato a implementare, ho scoperto che metà delle view che avevo disegnato non avevano senso con i dati reali disponibili. Adesso lavoro al contrario: prima i dati, poi l’interfaccia che li mostra.

I Numeri: Quanto Costa e Quanto Rende

Trasparenza totale, perché se fai build in public e nascondi i numeri stai solo facendo marketing.

I ricavi attuali non li condivido ancora (troppo presto, il prodotto è in beta privata). Quello che posso dire: il tempo risparmiato giustifica il costo dell’infrastruttura già solo per il mio uso interno. Prima spendevo 8+ ore al mese in reportistica e 8+ ore in monitoraggio manuale. Sono 16 ore al mese che adesso uso per sviluppare feature o acquisire clienti.

A 50€/ora (la mia tariffa per consulenza WordPress), 16 ore = 800€/mese di tempo recuperato. Contro 43€ di infrastruttura. Il ROI non ha bisogno di spiegazioni.

Lo Stack di Sviluppo: Come Lavoro Ogni Giorno

Per chi è curioso del workflow quotidiano:

• Editor: VS Code con Claude Code integrato. Lo uso per refactoring, test generation, e code review automatica.
• Version control: Git su GitHub, conventional commits in italiano (sì, in italiano. I miei repo, le mie regole).
• CI/CD: GitHub Actions. Push su main → test → build → deploy automatico su VPS via SSH.
• Testing: pytest per il backend FastAPI (copertura al 73%), Playwright per i test E2E della dashboard.
• Monitoring produzione: Sentry per gli errori, logging strutturato con structlog, metriche custom in PostgreSQL.

Un dettaglio che fa la differenza: uso Claude Code per generare i test. Non per scrivere la business logic (quella la scrivo io), ma per creare test case che coprono edge case a cui non avrei pensato. Esempio: “scrivi test per l’endpoint di health check quando il sito risponde 200 ma con body vuoto”. Claude genera il test, io lo rivedo e lo aggiungo. La copertura è salita dal 41% al 73% in due mesi con questo metodo.

Cosa Ho Imparato: 5 Lezioni dal Costruire un SaaS da Solo

1. Parti dal tuo problema. AgencyPilot esiste perché io avevo bisogno di AgencyPilot. Non ho fatto ricerche di mercato. Non ho intervistato 50 potenziali clienti. Ho costruito lo strumento che mi serviva e poi ho scoperto che serviva anche ad altri.
2. Monolite prima, microservizi mai (probabilmente). Per un team di 1-3 persone, i microservizi sono overhead puro. Un monolite ben strutturato con moduli chiari scala fino a molto più di quanto pensi.
3. Il plugin è il prodotto. La dashboard è bella, ma il valore reale è nel plugin Agent Connector che raccoglie i dati. Senza dati affidabili, la dashboard più bella del mondo è inutile.
4. Automatizza i report dal giorno uno. I clienti non vedono il monitoraggio. Non vedono le scansioni di sicurezza. Vedono il report mensile che dice “il tuo sito è protetto, aggiornato, e veloce”. Quello è il valore percepito.
5. Build in public funziona, ma serve costanza. Condividere il percorso su X mi ha portato i primi beta tester. Non virale, non migliaia di follower. Ma 3 persone che hanno detto “lo voglio provare” dopo aver letto un thread sulla sicurezza WordPress.

FAQ — Domande Frequenti

AgencyPilot funziona con qualsiasi hosting WordPress?

Sì, a patto che l’hosting supporti le REST API di WordPress (la maggior parte li supporta). L’Agent Connector richiede PHP 7.4+ e WordPress 5.8+. Hosting testati: Hetzner, DigitalOcean, SiteGround, Aruba, Register.it, OVH.

Posso usare AgencyPilot per siti non WordPress?

No. AgencyPilot è costruito specificamente per WordPress. Il monitoraggio uptime funziona con qualsiasi URL, ma le feature di security scanning, aggiornamenti, e report richiedono il plugin Agent Connector su WordPress.

Quanto costa AgencyPilot?

AgencyPilot è attualmente in beta privata. Il pricing non è stato ancora definito pubblicamente. Se gestisci 10+ siti WordPress e vuoi provarlo, contattami su X (@JuanAuriti) o via il form su agencypilot.it.

I report AI sono accurati?

I report sono generati da Claude API basandosi sui dati reali raccolti dall’Agent Connector. I dati sono sempre accurati. La narrazione in linguaggio naturale viene revisionata prima dell’invio al cliente. Nella nostra esperienza, circa il 95% dei report non richiede modifiche.

Come gestite la sicurezza dei dati dei siti gestiti?

L’Agent Connector non trasmette contenuti del sito, credenziali utente, o dati sensibili. Raccoglie solo metadati tecnici: versioni software, stato dei plugin, metriche di performance, log di errore. La comunicazione è cifrata con TLS 1.3 e autenticata con HMAC-SHA256. Ogni sito ha la propria API key isolata.