E-commerce custom vs WooCommerce: analisi tecnica e guida alla riscrittura

Analisi dell'architettura e strategia di riscrittura per una piattaforma e-commerce personalizzata

Premessa: cosa questo rapporto può e non può affermare

Questo rapporto distingue tre categorie di conclusioni:

• Fatti osservati: SPA React/Vite, API REST, Cloudflare, variabili di hydration (window.__INITIAL_DATA__, ecc.), endpoint e schemi emersi dalla ricognizione.
• Inferenze tecniche: come dati e moduli backend potrebbero coordinarsi.
• Raccomandazioni: architettura per una nuova base di codice, senza affermare che questa sia la struttura attuale del backend.

Non è possibile determinare con certezza se il backend utilizzi Node, PHP o Python solo dai nomi degli endpoint REST e dalla struttura JSON delle risposte. Per un fingerprinting più affidabile servirebbero header HTTP aggiuntivi, nomi dei cookie, formati degli errori, comportamento CORS/preflight, stack trace da un ambiente di staging o l'accesso al manifest di deployment.

1. Architettura operativa attuale

1.1 Visione d'insieme

Il sito segue un modello a tre livelli:

1. Cloudflare/CDN e reverse proxy: riceve le richieste, serve gli asset statici con hash e inoltra le richieste dinamiche all'origine.
2. SPA React buildata con Vite: responsabile del rendering dell'interfaccia, della gestione delle route e dello stato lato browser.
3. Backend REST dedicato: fornisce catalogo, CMS, configurazione del negozio e funzionalità di business come coupon, PayPal, contatti, newsletter, recensioni e tracking.

Non si tratta di WooCommerce, Shopify o WordPress headless. Il motivo tecnico è la superficie dell'API, lo schema dei prodotti, le impostazioni e il flusso di pagamento, che hanno tutti una forma di dominio progettata ad hoc, diversa dalle convenzioni predefinite di REST namespace e risorse di quelle piattaforme.

Cloudflare non prova quale stack sia utilizzato all'origine: può nascondere gli header del server, mettere in cache l'app-shell/gli asset statici e fare da proxy a Node, PHP, Python o a più servizi diversi.

1.2 Flusso del primo caricamento

Quando un utente apre /, /shop, /product/<slug> o una qualsiasi altra route del frontend, il server restituisce sempre lo stesso app-shell con id="root", gli script /assets/index-<hash>.js e, potenzialmente, dati bootstrap in window.__INITIAL_DATA__, window.__RC_HP, window.__RC_LAYOUT.

Il flusso più probabile è:

1. Il browser riceve l'HTML dell'app-shell.
2. Il browser scarica i file JS/CSS con hash del contenuto; questi file possono essere memorizzati nella cache a lungo perché il nome cambia a ogni build.
3. React si inizializza su #root e il router legge location.pathname per selezionare il componente della pagina.
4. La pagina recupera i dati bootstrap già incorporati, oppure chiama l'API REST se questi dati mancano o sono scaduti.
5. React costruisce il DOM e collega gli event handler.
6. I successivi cambi di route interna utilizzano la History API, senza ricaricare l'intero documento; cambiano solo i componenti e i dati necessari.

Punto da chiarire: l'esistenza delle variabili window.__... non è sufficiente a dimostrare che il sito abbia un vero SSR. Se l'HTML contiene solo JSON e un root vuoto, si tratta di bootstrap/preload per CSR, non di HTML con prodotto renderizzato lato server. Il SSR esiste solo quando il contenuto del prodotto (titolo, prezzo, link, metadati) è già presente nell'HTML prima che venga eseguito JavaScript.

Il fatto che ogni route restituisca lo stesso app-shell crea un'esperienza di navigazione SPA veloce dopo il primo caricamento, ma l'origine deve gestire correttamente il fallback senza trasformare URL inesistenti in risposte HTTP 200. Se /product/non-esiste restituisce anch'esso l'app-shell con codice 200 e React mostra solo un "non trovato", il crawler potrebbe interpretarlo come un soft 404. Google richiede che le route CSR gestiscano correttamente gli stati di errore o utilizzino noindex per evitare i soft 404 .

1.3 Flusso dei dati del catalogo

Gli endpoint indicano che il frontend non contiene un catalogo fisso nel bundle:

• GET /api/products?limit=500&active=1

  : recupera l'elenco dei prodotti in vendita.

• GET /api/products?q=...

  : utilizzato per la ricerca.

• GET /api/products/<slug>

  : recupera il dettaglio del prodotto.

• GET /api/products/categories

  : recupera la tassonomia.

Questo approccio separa il deploy del frontend dalle modifiche al catalogo: modificare prezzo, immagine o stock nel database non obbliga a un rebuild di Vite. È un chiaro vantaggio rispetto all'hard-coding dei prodotti in React.

Tuttavia, limit=500 è un'indicazione che l'API è ottimizzata per un catalogo di dimensioni ridotte, piuttosto che per una paginazione a lungo termine. Con 16 prodotti, caricare tutto in una volta può essere semplice e veloce; con migliaia di SKU, il payload, il tempo di query, la memoria del browser e la gestione dell'invalidazione della cache aumenterebbero inutilmente. Una nuova base di codice dovrebbe usare la paginazione cursore, la proiezione dei campi e un endpoint separato per la ricerca/filtri.

Lo schema prodotto attuale mostra alcuni segni di essere "product-centric" piuttosto che "variant-centric":

• stock si trova a livello di prodotto, mentre variants esiste già.
• sizes, colors, genders sono array del prodotto e potrebbero essere duplicati nelle varianti.
• I dati includono sia XXL che 2XL, sia

  ink navy

  che

  Ink Navy

  .
• image e images potrebbero avere ruoli sovrapposti.
• type, isbn sembrano campi generici o riutilizzati da un altro dominio.

Il motivo per cui questo è un problema tecnico: la giacenza e lo SKU reali appartengono alle combinazioni di varianti (ad esempio, Black/M e Black/L devono essere gestiti separatamente); le stringhe delle opzioni non normalizzate rendono filtri, analisi e mappatura delle immagini per colore instabili. Una riscrittura dovrebbe normalizzare i valori delle opzioni, gli SKU e l'inventario a livello di variante.

1.4 Builder della homepage

section_order combinato con un oggetto di attivazione/disattivazione suggerisce che la homepage è una composizione controllata dal CMS, non un ordine di componenti totalmente hard-coded.

Un renderer plausibile funzionerebbe così:

1. /api/homepage restituisce la configurazione delle sezioni.
2. Il frontend scorre section_order.
3. Ogni chiave come hero, trustbar, catshowcase, promo, products viene mappata a un componente React.
4. Il renderer controlla l'interruttore (toggle) prima di montare il componente.
5. Il componente legge il payload corrispondente (immagine, copy, CTA, riferimenti a prodotti o scadenza dell'offerta).

Punti di forza: il marketing può cambiare l'ordine e mostrare/nascondere blocchi senza un rilascio del frontend. Il motivo è che l'ordine risiede nei dati, mentre il frontend fornisce solo un registro di componenti.

Punti di debolezza: attualmente esistono sia ann che announcement, indice di un alias di chiave o di una migrazione dello schema non pulita. Se section_order, l'interruttore e il payload sono tre strutture separate, possono andare in disallineamento: una chiave presente nell'ordine ma senza payload, un interruttore con nome diverso, o un payload esistente ma non renderizzato.

Una nuova base di codice dovrebbe utilizzare un unico elenco di blocchi, in cui ogni blocco ha id, kind, enabled, position, payload, schema_version. In questo modo si mantengono ordine, stato e dati nello stesso aggregato, riducendo gli errori di sincronizzazione.

1.5 Layout builder e impostazioni

/api/layout molto probabilmente contiene la configurazione di header/footer/navigazione, mentre /api/public/settings contiene branding e policy del negozio. Separare il layout dalla homepage è sensato, poiché header e footer vengono usati su ogni route, mentre la composizione della homepage si applica solo alla pagina principale.

L'elenco delle impostazioni suggerisce che una tabella chiave-valore o un config JSON sta controllando:

• marchio e colori;
• logo/favicon;
• informazioni aziendali;
• commissioni e soglie per la spedizione gratuita;
• finestre di gestione e transito;
• provider di pagamento e PayPal client ID;
• link social, metodi di pagamento, navigazione e annunci;
• campagna saldi per capispalla.

Vantaggi: gestione flessibile; aggiungere una chiave non richiede migrazioni se si usa un formato chiave-valore/JSON.

Svantaggi: il puro chiave-valore manca di type safety, foreign key e validazione incrociata tra campi. Ad esempio, standard_handling_min non dovrebbe essere maggiore di standard_handling_max; paypal_sandbox dovrebbe essere booleano; gli URL dei social necessitano di validazione. Una nuova base di codice dovrebbe usare la validazione dello schema e separare la configurazione pubblica da quella segreta/interna.

tax_id, l'indirizzo legale, l'email operativa o altre informazioni non necessarie per lo storefront non dovrebbero essere restituite in blocco tramite le impostazioni pubbliche. Il PayPal client ID può essere pubblico, ma il client secret deve assolutamente rimanere solo lato server. Il motivo è che il browser e qualsiasi variabile window.__... possono essere letti dall'utente.

1.6 Coupon e checkout PayPal

Il flusso di pagamento più probabile:

1. Il client invia il carrello e il coupon al server.
2. Il server carica i prodotti/varianti correnti dal database, verifica l'attività, lo stock e le promozioni.
3. Il server calcola autonomamente subtotale, sconto, spedizione, tasse e totale finale.
4. /api/paypal/create-order crea un ordine su PayPal con le credenziali lato server e salva la relazione con il checkout interno.
5. Il client apre il flusso di approvazione PayPal.
6. /api/paypal/capture cattura l'ordine dopo l'approvazione.
7. Il server verifica importo/valuta/stato, crea l'ordine ufficiale, registra il tentativo di pagamento e decrementa/riserva l'inventario.
8. Il webhook PayPal riconcilia gli stati asincroni o le richieste interrotte.

Il server non deve mai fidarsi di price, discount, shipping o total inviati dal browser. Il motivo è che l'utente potrebbe modificare la richiesta; il server deve ricalcolare tutto a partire da SKU, regole promozionali e metodo di spedizione.

I due endpoint create/capture sono la strada giusta, ma la qualità effettiva dipende da:

• Idempotency key: per evitare che un doppio click o un retry creino/catturino l'ordine due volte.
• Transazioni/lock: per evitare overselling.
• Salvataggio del tentativo di pagamento prima di chiamare il provider.
• Verifica della firma del webhook.
• Controllo di valuta e importo.
• Macchina a stati del checkout chiara.
• Job di riconciliazione: per i casi in cui PayPal completa l'operazione ma la risposta non arriva al sito.

1.7 Recensioni, newsletter, contatti e tracking

Questi endpoint trasformano il backend in una vera applicazione di e-commerce, non solo in un'API per il catalogo.

• Recensioni: necessitano di stati (in attesa/approvata/rifiutata), antispam, rate limiting e verifica dell'acquirente se è prevista l'etichetta "acquisto verificato".

  POST /api/reviews/<id>

  è un nome di route sospetto se viene usato per creare una recensione; una nuova base di codice dovrebbe usare una semantica delle risorse più chiara.
• Newsletter: necessita di normalizzazione dell'email, vincolo di unicità, double opt-in (a seconda della normativa), soppressione/unsubscribe e divieto di loggare l'email in chiaro.
• Contatti: necessita di CAPTCHA o protezione bot, rate limiting, coda per l'invio delle mail e nessuna dipendenza diretta della richiesta HTTP dal provider di posta.
• Tracciamento ordini: non dovrebbe permettere la ricerca tramite un numero d'ordine breve. Dovrebbe richiedere un token di tracciamento firmato o una coppia riferimento ordine + email/CAP, con rate limiting. Il motivo è che un endpoint pubblico è vulnerabile a enumerazione, esponendo dati personali e cronologia acquisti.

1.8 Analytics/tracking

POST /api/track

L'endpoint di tracking non deve accettare JSON arbitrario e salvarlo all'infinito. Dovrebbe avere una whitelist di nomi/proprietà di eventi, limitare la dimensione, rimuovere o fare hash dei dati personali e inviare i dati tramite una coda. Il motivo è che l'ingestion di eventi è una superficie di abuso che può gonfiare inutilmente il database/log.

1.9 Stack backend possibile

Node.js con Express/Fastify/NestJS

È la possibilità più probabile, dato che il frontend React/Vite spesso si accompagna all'ecosistema TypeScript, alla serializzazione JSON e al middleware REST di Node. Anche l'inserimento da parte del server di window.__INITIAL_DATA__ nell'HTML è facile da realizzare con un template o un middleware.

Tuttavia, questa è solo una correlazione di ecosistema, non una prova. Route REST come /api/products/<slug> e campi in snake_case non sono esclusivi di Node.

PHP con Laravel/Symfony o framework leggero

PHP è ancora del tutto possibile. Laravel rende facile fornire controller REST, migrazioni del database, code, mail, validazione e può restituire l'app-shell di Vite da una route catch-all. Anche Cloudflare può nascondere completamente header come X-Powered-By o cookie.

Python con FastAPI/Flask/Django

Anche Python è possibile, poiché FastAPI/Flask rendono facile creare API REST JSON, mentre Django ha un ORM/admin potente. La build di Vite può essere servita da Nginx o da un'origine statica, indipendentemente dal backend Python.

Conclusione sul fingerprint

Non ci sono prove sufficienti per determinare il linguaggio backend. Gli indizi che potrebbero essere raccolti legittimamente (dal proprietario del sistema) includono: file di deployment, process manager, lockfile, immagine del container, header della risposta non filtrati da Cloudflare, prefisso dei cookie, OpenAPI generato, formato degli errori e driver del database. Non si dovrebbe dedurre lo stack solo dai nomi degli URL e trattarlo come una conclusione.

1.10 Punti di forza tecnici

• UI indipendente dalla piattaforma: React non è vincolato dal tema PHP o dal ciclo di vita delle pagine di Woo; il motivo è che l'intero livello di visualizzazione risiede in un albero di componenti separato.
• Ottima cache degli asset statici: l'hash di Vite permette

  Cache-Control: immutable

  ; un nuovo deploy genera un nuovo filename senza dover fare flush di tutti gli asset.
• CMS sufficiente per il marchio: il builder di homepage/layout si concentra proprio sui blocchi che il negozio utilizza, senza tirare dentro un page-builder generico.
• Dominio API chiaro: catalogo, contenuti e operazioni possono servire web, app o admin diversi.
• Meno plugin: si riduce la catena di dipendenze di temi/plugin e i conflitti di hook.
• Navigazione veloce dopo il primo caricamento: la SPA recupera solo i dati e cambia i componenti, invece di ricaricare l'intero documento.

1.11 Punti di debolezza e rischi

• Il primo caricamento dipende da JS: l'app-shell non contiene l'HTML del prodotto; bisogna attendere download, parsing, esecuzione e chiamata API. Su reti/dispositivi lenti il contenuto appare in ritardo.
• Waterfall API: se impostazioni, homepage, layout e prodotti vengono chiamati in sequenza, il LCP si allunga. Servono bootstrap aggregato, fetch parallelo o server rendering.
• SEO/status code: l'app-shell catch-all genera facilmente title/canonical identici e soft 404; anche i crawler social potrebbero non eseguire JS.
• Invalidazione cache complessa: catalogo, homepage, layout e impostazioni hanno TTL diversi; una cache troppo lunga fa apparire prezzi/stock/promozioni vecchi, una cache troppo corta sovraccarica l'origine.
• Logica di business autocostruita: coupon, stato ordini, tasse, resi, inventario, webhook e admin devono essere tutti testati; non esiste un ecosistema già pronto come Woo.
• Modello dati non normalizzato: array di colori/taglie e stock a livello di prodotto rendono difficile l'espansione a un inventario per SKU.
• Superficie di sicurezza: contatti, recensioni, newsletter, tracking e pagamento sono tutti endpoint di mutazione pubblici che necessitano di validazione/rate limiting/idempotenza.
• Bus factor: se solo una persona conosce il backend custom e il builder, il costo di passaggio di consegne è maggiore di una installazione Woo standard.

2. Confronto diretto con WooCommerce

2.1 Una SPA custom è "più figa" di Woo?

Non si può concludere solo dal fatto che usi React/Vite e un'API dedicata. "Custom" dà un maggiore controllo, ma non significa automaticamente più veloce, migliore per la SEO, più sicuro o più economico. La qualità dipende dal modello dati, dalla strategia di rendering, dalla cache, dall'osservabilità, dai test e dal processo di pagamento.

Con un catalogo di soli 16 prodotti, un'architettura distribuita custom può essere un vantaggio per il marchio, ma potrebbe anche essere un over-engineering se il team è piccolo e le esigenze principali sono la gestione di ordini, coupon, spedizioni, resi, tasse e reportistica.

2.2 Velocità di caricamento

Custom SPA

• Può essere molto veloce nelle navigazioni successive, poiché JS/CSS sono in cache e cambiano solo i dati.
• Gli asset statici possono essere distribuiti su una CDN globale.
• Tuttavia, la prima vista può essere lenta a causa del bootstrap di JS e del waterfall API; un app-shell piccolo non garantisce un buon LCP se l'immagine hero/del prodotto e il testo appaiono solo dopo il fetch.
• Una singola richiesta products?limit=500 diventa un collo di bottiglia quando il catalogo cresce.

WooCommerce tradizionale

• Restituisce l'HTML del prodotto/categoria direttamente dal server, quindi il contenuto appare senza attendere il bootstrap di React.
• Full-page cache, CDN, object cache e ottimizzazione delle immagini possono rendere un negozio piccolo molto veloce.
• Plugin pesanti, temi con molto JS, query al database senza indici e worker PHP con poche risorse possono causare un TTFB elevato.
• Carrello, account e checkout sono contenuti personalizzati, quindi più difficili da mettere in full-page cache rispetto alle landing page.

Conclusione: il custom ha un potenziale di performance più alto se si utilizzano correttamente SSR/SSG, cache e ottimizzazione del bundle; Woo ha una baseline più semplice. Non bisogna confrontare i nomi delle tecnologie. Bisogna confrontare i Core Web Vitals reali al p75 su mobile, il TTFB dell'origine/CDN, il JS trasferito, la latenza dell'API e il tasso di errore.

2.3 Personalizzazione dell'UI e builder

Il custom con React vince chiaramente quando l'esperienza del marchio richiede animazioni, blocchi editoriali, campagne specifiche o comportamenti dei componenti diversi dal tema di un negozio standard. Il motivo è che il team di sviluppo controlla markup, stato, transizioni di route e design system.

Anche il builder di homepage/layout scritto su misura può essere più snello di un page-builder plugin, perché contiene solo 10-15 tipi di blocco approvati. Il payload è più piccolo e l'editor ha meno opzioni sbagliate.

Woo vince per time-to-market e back-office. L'editor di prodotto, la gestione degli ordini, coupon, resi, integrazione tasse/spedizioni e il marketplace delle estensioni sono già pronti. Per ottenere una personalizzazione equivalente, bisogna costruire UX admin, validazione, audit e migrazioni, non solo lo storefront.

2.4 SEO

Il WooCommerce tradizionale ha un vantaggio predefinito, poiché l'HTML di prodotto/categoria e i metadati sono renderizzati lato server. Una SPA renderizzata lato client (pure CSR) non significa automaticamente "non indicizzabile": Google può eseguire JavaScript, ma il contenuto dipende comunque dalla coda di rendering, dalla disponibilità dell'API, dalla semantica delle route e dai link interni.

I rischi reali di una SPA pura includono:

• L'HTML iniziale manca di nome del prodotto, descrizione e dati strutturati.
• title/canonical/Open Graph vengono aggiornati dopo il JS, quindi i bot dei social potrebbero non vederli.
• Un catch-all che restituisce 200 per URL errati.
• API bloccata, timeout o errore di hydration che fanno vedere al crawler una pagina vuota.
• Paginazione/filtri che creano URL non canonicali.
• Link creati con click handler invece di

  <a href>

  : più difficili da crawlare.

Google considera il dynamic rendering (in base allo user-agent) un workaround, non una soluzione a lungo termine; la raccomandazione è SSR, static rendering o hydration appropriata . Quindi una nuova base di codice non dovrebbe limitarsi ad aggiungere un servizio "render-only-for-bots".

I modi corretti per risolvere:

1. SSG/ISR per pagine prodotto, categoria, contenuti e homepage: l'HTML ha il contenuto immediatamente.
2. SSR per le route che necessitano di dati basati sulla richiesta.
3. CSR solo per cart drawer, personalizzazione e interazioni post-caricamento.
4. Generare metadati, canonical e JSON-LD (Product/Breadcrumb/Organization) lato server.
5. Restituire 404/410 reali per risorse inesistenti.
6. Avere XML sitemap, policy robots, paginazione e redirect per slug cambiati.
7. Testare con HTML renderizzato, Search Console e un crawler senza JS.

2.5 Manutenzione

Custom

Bisogna mantenere frontend, backend, database, admin, contratto API, integrazione pagamenti, job email, cache e deployment. Un cambiamento di campo può influenzare molti client. Servono contract test, migrazioni backward-compatible e osservabilità.

In cambio, si ha solo il codice necessario; non si devono gestire conflitti tra decine di plugin. Il team possiede l'intera roadmap e può eliminare codice legacy.

WooCommerce

Il core dell'e-commerce e l'admin vengono mantenuti dalla community/vendor, ma bisogna aggiornare WordPress core, Woo, tema e plugin. Ogni aggiornamento richiede test in staging, perché hook, template overrides e compatibilità dei plugin possono cambiare.

Conclusione: Woo sposta il costo dal "costruire il dominio" alla "gestione dell'ecosistema"; il custom sposta il costo dalle licenze dei plugin/compatibilità al payroll engineering e all'operatività.

2.6 Costi di hosting

Un WooCommerce piccolo può girare su un unico managed WordPress host, database e CDN, risultando semplice in termini di fatture e operatività. Una SPA custom ha un frontend statico molto economico, ma l'intero sistema necessita comunque di compute per l'API, database, object storage, email, code, log e backup.

Quindi il custom non è automaticamente più economico. A basso traffico, il costo delle persone e il numero di servizi sono spesso maggiori del costo del compute. Ad alto traffico in lettura, lo static/edge rendering dell'headless può ridurre significativamente il carico sull'origine.

2.7 Scalabilità

Il custom separa il frontend dal backend, quindi è possibile scalare CDN, API di lettura, worker e database in modo indipendente. Questo è un vantaggio se il traffico di una campagna aumenta improvvisamente o se ci sono molti canali che usano la stessa API di e-commerce.

Ma scalare il checkout non significa solo aggiungere server. Le transazioni del database, la riserva dell'inventario, l'idempotenza dei pagamenti, l'ordinamento dei webhook e la coerenza della cache sono la parte difficile.

Woo può servire volumi considerevoli con un buon hosting, cache, ottimizzazione del database e pochi plugin. I colli di bottiglia sono spesso le richieste dinamiche, le query/tabelle meta, gli hook dei plugin e i worker PHP. Con 16 prodotti, non ci sono prove che la scala attuale richieda microservizi custom.

2.8 Dipendenza da plugin e vendor

Woo dipende più dai plugin se ogni funzionalità è assemblata da estensioni; il rischio riguarda licenze, cadenza di aggiornamento, plugin abbandonati e conflitti di hook.

Il custom riduce la dipendenza dai plugin WordPress ma non elimina le dipendenze: si dipende comunque dal framework, dai pacchetti npm, dal cloud/CDN, dall'SDK PayPal, dal provider email e dal team di sviluppo. È un cambiamento nel tipo di dipendenza, non la loro eliminazione.

2.9 Tabella decisionale

2.10 Raccomandazione

• Se l'obiettivo è un lancio rapido, il team è piccolo, i processi di e-commerce sono standard e non serve un'esperienza utente troppo personalizzata: usa WooCommerce tradizionale con un tema leggero, pochi plugin, hosting gestito e una buona cache.
• Se l'obiettivo è possedere l'esperienza del marchio, avere un builder personalizzato, integrarsi con molti canali e il team ha competenze backend/pagamenti: continua sulla strada del custom, ma sostituisci la SPA pura con un framework SSR/SSG/ISR.
• Non è consigliato fare "headless Woo" solo per sembrare moderni, se si devono comunque gestire sia WordPress che il frontend senza una chiara necessità di UI/canali. Combina entrambi i costi.

Per questo sito specifico, la strada più ragionevole è mantenere l'approccio custom all'e-commerce ma riscrivere lo storefront con un rendering ibrido, non copiare la SPA attuale e non passare necessariamente a Woo. Il motivo è che il builder e l'UI del marchio sono già competenze chiave; ciò che va migliorato sono il rendering, il modello dati, la correttezza del checkout e l'operatività.

3. Strategia di riscrittura come nuovo progetto

3.1 Principi

La nuova base di codice dovrebbe riutilizzare i requisiti di business e i dati a cui il proprietario ha diritto, ma non copiare bundle decompilati, struttura dei moduli, nomi di symbol privati o implementazioni passate.

Si possono riutilizzare le idee universali:

• catalogo/categoria/dettaglio prodotto;
• homepage a blocchi;
• layout con header/footer/nav;
• coupon, newsletter, contatti, recensioni, tracking;
• flusso PayPal create/approve/capture;
• fasce di spedizione e impostazioni del negozio.

Si devono fare da capo:

• naming delle route e formato delle risposte;
• modello database per varianti/inventario;
• registry dei componenti e schema del builder;
• strategia di rendering;
• macchina a stati del checkout;
• invalidazione della cache;
• sicurezza, osservabilità e suite di test.

3.2 Stack proposto

Storefront

• Next.js App Router + React + TypeScript per avere server components, SSR, static generation/ISR e componenti client nelle aree interattive.
• Zod per la validazione del contratto ai boundary.
• TanStack Query solo per lo stato lato server che necessita di refresh lato client, senza rifetchare dati già renderizzati se non necessario.
• CSS Modules/Tailwind o un design-token system; scegliere uno standard e limitare il runtime CSS-in-JS.
• Ottimizzazione delle immagini tramite CDN/object storage con larghezza/formato espliciti.

Next.js non è l'unica scelta; Remix o un framework SSR equivalente sono altrettanto validi. Il criterio importante è avere HTML renderizzato lato server, status code corretti, cache controllata e meno JS client possibile, non il nome del framework.

Backend

• NestJS con Fastify adapter + TypeScript, oppure Fastify modulare se il team vuole meno astrazione.
• PostgreSQL come source of truth.
• Drizzle ORM o Prisma per migrazioni e query type-safe; le transazioni di pagamento/inventario richiedono comunque progettazione manuale.
• Redis solo se strettamente necessario per cache, lock distribuiti o rate-limiting; non introdurre Redis dal primo giorno se una singola istanza e il traffico ridotto sono sufficienti.
• BullMQ/coda equivalente per email, retry di webhook, analytics e riconciliazione.
• Object storage compatibile con S3 per i media; il database memorizza solo metadati/chiave.
• OpenTelemetry + log strutturati + error tracking per tracciare richieste, checkout e tentativi di pagamento.

Deployment

• Storefront dietro una CDN/edge cache.
• API in esecuzione in un container/servizio separato.
• PostgreSQL gestito con point-in-time recovery.
• Object storage separato dal filesystem del container.
• Preview/staging con PayPal sandbox e database separato.
• Segreti tramite secret manager, non nel repository.

Modello dati (variazioni principali)

• SKU e inventory a livello di variante: ogni variante ha id, sku, price, stock, image (o riferimento a media), sort_order e array option_values.
• Option values normalizzati e condivisi: tabella ProductOptionValue con id, option_type_id (colore, taglia, ecc.), value normalizzato (es. "Navy" non "ink navy"), label per visualizzazione e swatch_media_id.
• Immagine del prodotto non duplicata: tabella ProductMedia con id, product_id, variant_id (opzionale), url, sort_order, alt_text.
• Builder dei blocchi unificato: tabella PageBlock con id, page_id (o page_type + page_slug), kind, enabled, position, payload (JSON con validazione contro lo schema block_schema_version).
• Settings tipizzate: tabella StoreSetting con key, value (JSONB), type (string, number, boolean, url), group (public, internal, secret), description e version.

Roadmap di riscrittura (macro-fasi)

1. Progettazione e prototipo (Settimane 1-2)

   • Definire il contratto API (OpenAPI 3.1) e validarlo con il proprietario del business.
   • Scegliere lo stack e impostare il monorepo.
   • Creare il database schema (migration iniziale).
   • Prototipo della pagina prodotto con dati mock in SSR.

2. Core catalog (Settimane 3-5)

   • API CRUD per prodotti, varianti, categorie e media.
   • Storefront: listing, dettaglio, filtri (con paginazione cursore).
   • Integrazione immagini con CDN.
   • SEO base: sitemap, metadati, JSON-LD.

3. Builder e layout (Settimane 6-7)

   • Sistema a blocchi unificato.
   • API per homepage e layout.
   • Storefront: renderer dei blocchi con SSR.
   • Admin base per gestire l'ordine dei blocchi.

4. Checkout e pagamenti (Settimane 8-10)

   • Macchina a stati del carrello e checkout (lato server).
   • Integrazione PayPal (create/capture/webhook).
   • Coupon e sconti.
   • Calcolo tasse e spedizione.
   • Idempotenza e gestione degli errori.
   • Test di carrello, coupon e pagamento.

5. Funzionalità extra e messa in sicurezza (Settimane 11-12)

   • Recensioni (con moderazione).
   • Newsletter (double opt-in).
   • Contatti (con CAPTCHA).
   • Tracciamento ordini (con token).
   • Rate limiting, validazione, logging strutturato.

6. Test, SEO e lancio (Settimana 13+)

   • Test di carico, test di sicurezza.
   • Audit SEO (Google Search Console, Lighthouse, rendered HTML).
   • Deploy di staging e UAT.
   • Migrazione dati (da sistema legacy).
   • Soft launch e monitoraggio.

Checklist di sicurezza per il nuovo checkout

• Tutti i calcoli di prezzo, sconto, tasse e spedizione sono fatti ESCLUSIVAMENTE lato server, mai fidandosi del client.
• Idempotency key obbligatoria per create-order e capture.
• Verifica della firma del webhook PayPal prima di processarlo.
• Controllo che l'importo catturato corrisponda a quello creato (con una piccola tolleranza per arrotondamenti).
• Transazione di database per capture: aggiornamento ordine + decremento stock + registrazione pagamento, tutto o niente.
• Lock ottimistico o pessimistico per evitare overselling sullo stesso SKU.
• Job di riconciliazione notturno per ordini in stato "pagato su PayPal ma non confermato sul sito".
• Log di ogni tentativo di pagamento con ID univoco, timestamp e stato.
• Rate limiting su tutti gli endpoint di creazione/cattura ordine.

Conclusione

Il sito attuale mostra una solida architettura custom con React e API REST, ma soffre di debolezze tipiche delle SPA pure per l'e-commerce: SEO rischiosa, primo caricamento lento, modello dati non normalizzato e superficie di sicurezza estesa. WooCommerce è un'alternativa valida per progetti più semplici, ma non è una soluzione universalmente superiore.

La strategia di riscrittura proposta mantiene il controllo sull'esperienza del marchio e sul builder, ma risolve i problemi strutturali adottando un rendering SSR/ISG, un modello dati normalizzato e un checkout più robusto. La roadmap presentata fornisce una guida pratica per trasformare l'attuale SPA in una piattaforma moderna, performante e SEO-friendly senza perdere i vantaggi del custom.

Fonti:

Google Search Central - Dynamic Rendering as a workaround
Google Search Central - Understand JavaScript SEO Basics
Digital Codex - JavaScript SEO
Fuel Online - JavaScript SEO Guide 2026
Incremys - JavaScript SEO 2026
The Growth Terminal - JavaScript Rendering SEO in 2026
Google Webmasters Support - Dynamic JavaScript rendering
Search Engine Land - Google no longer recommends dynamic rendering