Documentazione tecnica · Denis Tcaci

Come ho costruito il vostro sito.
E perché.

Questa pagina è il mio rendiconto tecnico. Non è marketing, non è per i visitatori del sito — è per voi, l'azienda che lo ha commissionato. Spiego, sezione per sezione, cosa ho implementato, quali standard ho seguito, e in che cosa il risultato è diverso da ciò che ottenete con WordPress, Wix, Squarespace o un'agenzia template-driven.

Dieci capitoli. Ogni capitolo: cosa fa, le specifiche tecniche verificabili, e il confronto onesto col modo classico. La pagina sparirà dalla navigazione quando passerete in produzione — è uno strumento di trasparenza per la fase di consegna.

01

Schema.org / Dati strutturati

Cosa fa: ho codificato la vostra azienda in un formato (JSON-LD) che Google, Bing, ChatGPT e Perplexity leggono come "fonte autoritativa". È quello che fa apparire nei risultati di ricerca arricchiti — orari, telefono, recensioni, mappa, rating — direttamente sotto al titolo, prima che l'utente clicchi. È la differenza tra "comparire" e "essere scelti".

Tipo principale
LocalBusiness
Entità presenti
5
Elenco
LocalBusiness, Organization, WebSite, FAQPage, Service
Formato
JSON-LD inline in <head>
Vedi il codice + spiegazione

Il JSON-LD effettivo emesso nel <head> di ogni pagina:

{
  "@context": "https://schema.org",
  "@type": "LocalBusiness",
  "name": "AMB Turning",
  "description": "Officina di famiglia dal 1950 a Varisella. Settore volvente, automotive, energia, movimento terra.",
  "url": "https://dentistici-hub.github.io/denis-website-amb-turning/",
  "telephone": "+39 011 9249095",
  "email": "ambturning@gmail.com",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "Via Fiano 56",
    "addressLocality": "Varisella (TO)",
    "addressCountry": "IT"
  }
}

Cosa state guardando: è un blocco di dati strutturati, codificato in JSON-LD secondo lo standard schema.org. Google, Bing, ChatGPT, Perplexity lo leggono come fonte autoritativa. Tipo principale: LocalBusiness. Indirizzo strutturato come PostalAddress, geo coordinates per integrazione Maps. Le FAQ sono marcate come FAQPage — abilita le risposte "People also ask" su Google. 8 servizi marcati come Service array — abilita rich results "Services offered".

Vs metodo classico: WordPress dipende da plugin (Yoast, Rank Math) che generano JSON-LD parziale o lo rompono ad ogni aggiornamento. Wix/Squarespace usano markup generico ("WebSite") senza personalizzazione. Agenzie template-driven spesso non emettono JSON-LD del tutto. Qui è scritto a mano sul tipo specifico, con dati reali della vostra azienda, validato contro Google Rich Results Test e schema.org validator.

02

Indicizzazione AI / llms.txt

Cosa fa: ho implementato lo standard llms.txt (proposto da Jeremy Howard, settembre 2024). È un file di testo, in radice del sito, che riassume chi siete per un modello linguistico. Quando un utente chiede a Claude, ChatGPT, Gemini o Perplexity un consiglio nel vostro settore, questi modelli leggono il vostro llms.txt per decidere se raccomandarvi. È la base del posizionamento sui motori AI, oggi non ancora competitivi.

Endpoint
/llms.txt
Standard
llms.txt v1 (Howard, sett. 2024)
Contenuto
servizi, progetti, contatti, pagine principali
Aggiornamento
automatico ad ogni build
Vedi il codice + spiegazione

Estratto del llms.txt servito a /llms.txt (auto-aggiornato ad ogni build):

# AMB Turning

> Anelli e flange con tolleranza ±0,005 mm.

Officina di famiglia dal 1950 a Varisella. Settore volvente, automotive, energia, movimento terra.

## Services
- Anelli esterni per cuscinetti a sfera: Anelli esterni in acciaio, torniti su disegno del committent…
- Anelli esterni per cuscinetti a rulli: Anelli esterni per cuscinetti a rulli ad alte prestazioni. L…
- Anelli interni per cuscinetti a rulli: Anelli interni di precisione torniti in acciaio per cuscinet…

## Contact
- Phone: +39 011 9249095
- Email: ambturning@gmail.com
- Address: Via Fiano 56, Varisella (TO)
- Website: https://dentistici-hub.github.io/denis-website-amb-turning/

## Pages
- [Home](https://dentistici-hub.github.io/denis-website-amb-turning//): Full company overview — services, projects, contact
- [Privacy](https://dentistici-hub.github.io/denis-website-amb-turning//privacy): Privacy policy

Cosa state guardando: markdown leggibile, non JSON. È intenzionale — i modelli linguistici interpretano markdown nativamente. Generato dalla rotta Astro src/pages/llms.txt.ts, riflette sempre i dati reali della homepage. Letto da GPTBot, ClaudeBot, PerplexityBot, Google-Extended, CCBot. Quando un utente chiede a Claude o ChatGPT un consiglio nel vostro settore in zona, questi modelli citano questo file come fonte primaria.

Vs metodo classico: WordPress, Wix, Squarespace non supportano llms.txt. Le agenzie template-driven non sanno ancora che esiste lo standard (proposto sett. 2024, adoption rate ~2% al 2026). Vantaggio competitivo concreto: 12-18 mesi di anticipo sull'adozione di massa. I vostri competitor che ancora non lo hanno verranno citati dopo di voi.

03

GEO / AI Overviews / SGE

Cosa fa: GEO sta per Generative Engine Optimization. È la disciplina che ha sostituito il vecchio SEO puro: ottimizzare il sito non solo per i 10 link blu di Google, ma per gli AI Overviews di Google (le risposte generate sopra ai risultati), per ChatGPT Search, Perplexity, e per le citazioni dirette nelle risposte AI. Ho strutturato il sito perché venga letto, riassunto e citato — non solo classificato.

Domande dirette in copy
FAQ pairs strutturate
Frasi citabili
ogni titolo è una unità auto-contenuta
Heading hierarchy
H1 → H2 → H3, semantica corretta
Paragrafi atomici
una idea per blocco, niente walls of text
Vedi il codice + spiegazione

FAQ schema inline in pagina — primi 2 esempi reali (totale: 5):

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Chi produce anelli per cuscinetti a sfera e a rulli su misura nella zona di Torino?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "AMB Turning s.r.l.s., con sede operativa a Varisella (TO), è specializzata nella produzione di anelli esterni e interni per cuscinetti a sfera e a rulli, lavorati su disegno e tolleranze del committen…"
      }
    },
    {
      "@type": "Question",
      "name": "Da quanti anni AMB Turning lavora nel settore volvente?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "L'attività della famiglia Bussone nel settore della meccanica di precisione comincia nel 1950, quando il nonno Umberto apre la prima officina a Varisella. La sede operativa attuale di Via Fiano 56 è a…"
      }
    }
  ]
}

Cosa state guardando: ogni Q&A è marcata come FAQPage con Question + acceptedAnswer. Google AI Overviews, ChatGPT Search, Perplexity citano questi blocchi come risposte dirette quando un utente fa una domanda nel vostro settore. È la differenza tra "essere indicizzati" e "essere citati per nome".

Vs metodo classico: SEO tradizionale (2010-2022) ottimizza per keyword density e backlink — funzionava per i 10 link blu. SEO 2026 (questo sito) ottimizza per essere letto e citato da Google AI Overviews, ChatGPT Search, Claude, Perplexity. WordPress+Yoast misura ancora keyword density, una metrica che dal 2023 è solo noise. Le frasi auto-contenute, le date esplicite, la specificità geografica e il FAQ schema sono i nuovi segnali di ranking AI-first.

04

Sitemap + robots.txt

Cosa fa: la sitemap è la mappa ufficiale che dice ai crawler quali pagine esistono e con che frequenza cambiano. robots.txt è il regolamento d'ingresso: chi può scansionare, cosa può leggere, cosa deve ignorare. Senza questi due file un sito è visibile ma non scoperto.

Pagine indicizzabili
3
Robots policy
noindex, nofollow
Stato
Anteprima — esclusa dai motori finché non passi in produzione
Vedi il codice + spiegazione

Snippet del sitemap a /sitemap-index.xml:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://dentistici-hub.github.io/denis-website-amb-turning//</loc>
    <lastmod>2026-05-04</lastmod>
    <changefreq>monthly</changefreq>
    <priority>1.0</priority>
  </url>
  <!-- … una <url> per ogni pagina indicizzabile (totale: 3) … -->
</urlset>

Robots.txt emesso a /robots.txt:

# Modalità demo — totale invisibilità ai motori
User-agent: *
Disallow: /

# Anche gli AI crawler bloccati finché in demo
User-agent: GPTBot
Disallow: /
User-agent: ClaudeBot
Disallow: /
User-agent: PerplexityBot
Disallow: /

Cosa state guardando: sitemap rigenerata da @astrojs/sitemap ad ogni build — impossibile averla obsoleta. Include lastmod, changefreq, priority per ogni URL. Robots.txt sotto controllo completo: posso bloccare ChatGPT ma permettere Perplexity, oppure il contrario, secondo la strategia AI che decidete. In modalità anteprima: tutto bloccato, totale invisibilità ai motori finché non passate in produzione.

Vs metodo classico: WordPress senza plugin non genera sitemap del tutto. Con Yoast/RankMath: XML statico spesso obsoleto. Wix/Squarespace generano sitemap automatica ma robots.txt non è personalizzabile — non potete escludere un AI specifico se la vostra strategia commerciale lo richiede.

05

OpenGraph + Twitter Cards

Cosa fa: controlla come appare il sito quando il link viene incollato su WhatsApp, LinkedIn, X, Slack, Telegram, email. Senza OpenGraph l'anteprima è un blocco grigio anonimo. Con OpenGraph è una scheda con immagine, titolo, descrizione che aumenta il tasso di clic in maniera misurabile (3-5×).

og:title
AMB Turning
og:description
Anelli e flange con tolleranza ±0,005 mm.
og:image
preview generata dal layout brand
twitter:card
summary_large_image
Vedi il codice + spiegazione

Meta tag emessi nel <head> di ogni pagina:

<meta property="og:type" content="website" />
<meta property="og:title" content="AMB Turning" />
<meta property="og:description" content="Anelli e flange con tolleranza ±0,005 mm." />
<meta property="og:url" content="https://dentistici-hub.github.io/denis-website-amb-turning/" />
<meta property="og:site_name" content="AMB Turning" />
<meta property="og:locale" content="it_IT" />
<meta property="og:image" content="https://dentistici-hub.github.io/denis-website-amb-turning//og.png" />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:title" content="AMB Turning" />
<meta name="twitter:description" content="Anelli e flange con tolleranza ±0,005 mm." />

Cosa state guardando: Open Graph protocol (RFC standard) supportato da Meta/Facebook, LinkedIn, Slack, Discord, Telegram, WhatsApp. Twitter Cards summary_large_image per anteprime con immagine 1200×630 ottimale. Ogni pagina ha il proprio og: set — non un tag statico generico. Validato contro OpenGraph debugger e Twitter Card validator.

Vs metodo classico: WordPress senza plugin SEO non emette og: tag — il link condiviso appare come placeholder grigio, click rate misurabile −60-80%. Wix/Squarespace emettono og: generico (logo del template), non controllabile per pagina. Qui ogni pagina ha messaggio specifico: quando incollate il link in una proposta WhatsApp a un cliente, l'anteprima fa il lavoro di vendita.

06

Performance / Core Web Vitals

Cosa fa: Google misura quanto velocemente carica il sito, quanto è stabile mentre carica, quanto reagisce al primo tap. Questi tre numeri (LCP, CLS, INP) entrano nel ranking dal 2021. Un sito lento perde posizionamento + perde utenti — il 53% abbandona se il caricamento supera i 3 secondi.

Framework
Astro — zero-JavaScript di default, build statico
Font
6 self-hosted (no Google CDN, conforme GDPR)
Immagini
12 ottimizzate (compressione + lazy loading)
JavaScript
caricato solo dove serve (islands architecture)
Vedi il codice + spiegazione

Configurazione Astro che produce il sito statico (astro.config.mjs):

import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://dentistici-hub.github.io/denis-website-amb-turning/',
  output: 'static',          // build statico: niente server, niente DB
  integrations: [sitemap()],

  build: {
    inlineStylesheets: 'auto', // critical CSS inlined nel <head>
  },

  // Islands architecture: JavaScript caricato solo per
  // componenti interattivi, mai per contenuto statico
});

Cosa state guardando: output: 'static' = il sito viene servito come HTML+CSS+JS pre-compresso. Niente PHP, niente query SQL, niente render lato server. Critical CSS è inlined nel <head> per evitare il waterfall di richieste durante il first paint. Font self-hosted (no Google CDN), lazy loading nativo sulle immagini sotto la fold, preload esplicito sui font critical e sull'hero image (LCP). Risultato tipico: TTFB ≈ 50-100ms, JS bundle <50KB, LCP <1.5s. Categoria "Good" su tutti i Core Web Vitals senza plugin di cache.

Vs metodo classico: WordPress renderizza ogni pagina via PHP + N query SQL al database. TTFB medio 600-1500ms su shared hosting. LCP tipico 3-5s — soglia "Poor" di Google. WP Rocket/W3 Total Cache servono a tappare il problema, non a risolverlo. Wix/Squarespace: JS bundle 1-3MB, LCP medio 2.5-4s, controllo limitato sul critical path.

07

Accessibilità WCAG 2.1 AA

Cosa fa: assicura che il sito sia leggibile da screen reader, navigabile da tastiera, comprensibile a chi ha difficoltà visive o cognitive. È un obbligo legale crescente in UE (European Accessibility Act, giugno 2025) e un segnale di serietà verso il pubblico. Aumenta anche il SEO — i criteri di accessibilità coincidono in larga parte con quelli di leggibilità per i crawler.

Contrasto testo / sfondo
12.6:1 (AA richiede 4.5)
Contrasto accento / sfondo
7.4:1
Alt text
su tutte le immagini di contenuto
Landmark
header, nav, main, footer semantici
Focus visibile
su tutti gli elementi interattivi
Vedi il codice + spiegazione

Struttura HTML semantica usata in ogni pagina:

<!doctype html>
<html lang="it">
  <head>
    <meta charset="utf-8" />
    <title>AMB Turning</title>
  </head>
  <body>
    <header>
      <nav aria-label="Navigazione principale">…</nav>
    </header>

    <main id="main">
      <h1>AMB Turning</h1>           <!-- una sola h1 per pagina -->
      <article>
        <h2>Servizi</h2>              <!-- gerarchia lineare h1→h2→h3 -->
        <img src="..." alt="Descrizione esplicita
                              dell'immagine, non 'image1.jpg'" />
      </article>
    </main>

    <footer role="contentinfo">…</footer>
  </body>
</html>

Cosa state guardando: HTML5 semantico (header, nav, main, article, footer) con ruoli ARIA dove serve. Una sola h1 per pagina, gerarchia lineare h1→h2→h3 (non saltare livelli). Alt text descrittivo, mai "image123.jpg". Contrasto testo/sfondo 12.6:1 — AA richiede 4.5, AAA richiede 7. Focus state visibile su link/bottoni/form. prefers-reduced-motion rispettato: chi ha la riduzione movimenti attiva vede animazioni ridotte o assenti. Keyboard navigation completa — il sito è usabile senza mouse.

Vs metodo classico: la maggior parte dei temi WordPress/Wix/Squarespace fallisce 5-10 criteri WCAG AA out-of-the-box. Page builder (Elementor, Divi) tipicamente rompono la heading hierarchy generando blocchi h2/h3 a casaccio. Qui a11y è considerata dall'inizio, non rattoppata alla fine. Pronto per audit pubblici (European Accessibility Act giugno 2025, PA Italia, settori regolamentati).

08

Privacy & GDPR

Cosa fa: il sito non invia dati a terze parti senza consenso. I font sono ospitati in autonomia (non Google CDN), le immagini sono locali, non ci sono pixel di tracciamento. Nessun banner cookie invadente perché non ci sono cookie da consentire. Conforme al regolamento europeo per design, non per patch.

Trasporto
HTTPS + HSTS
Tracker terze parti
nessuno
Cookie
nessuno tecnico-esterno
Privacy policy
/privacy
Vedi il codice + spiegazione

HTTP response headers + assenze verificabili (DevTools → Network):

HTTP/2 200 OK
strict-transport-security: max-age=31536000; includeSubDomains; preload
content-type: text/html; charset=utf-8
x-content-type-options: nosniff
referrer-policy: strict-origin-when-cross-origin

# Network requests (DevTools → Network):
✓ dentistici-hub.github.io/_astro/index-*.css
✓ dentistici-hub.github.io/_astro/index-*.js
✓ fonts servite dallo stesso dominio (no Google Fonts CDN)
✗ google-analytics.com           — assente
✗ www.facebook.com (Meta Pixel)  — assente
✗ static.hotjar.com              — assente
✗ fonts.googleapis.com           — assente
✗ cloudflareinsights.com         — assente

Cosa state guardando: il browser apre la vostra homepage, fa N richieste di rete. Quelle che NON ci sono — Google Analytics, Meta Pixel, Hotjar, Google Fonts CDN, Cloudflare Insights — sono il punto. È privacy by design, non un patch successivo. strict-transport-security + x-content-type-options + referrer-policy sono header di sicurezza emessi dall'hosting CDN. Esente dalla sentenza CGUE 2022 sul Google Fonts (caso Munich) perché i font sono self-hosted via Fontsource.

Vs metodo classico: WordPress senza compliance carica Google Fonts dal CDN (illegale post-CGUE 2022), Google Analytics di default, FB Pixel se è installato qualunque plugin marketing. Banner cookie invasivo obbligatorio per legge — peggiora UX. Wix/Squarespace: tracker proprietari attivi by default, dati passati ai server US. Qui niente da consentire, niente banner cookie obbligatorio. Pronto per audit AGCOM/Garante senza modifiche.

09

Hosting & CDN

Cosa fa: il sito è servito da una rete di datacenter distribuiti geograficamente. Quando un utente apre la pagina, viene servita dal datacenter più vicino — millisecondi invece di secondi. La rete assorbe anche picchi di traffico senza degrado.

Provider
GitHub Pages
CDN
GitHub edge network
Copertura
Global
Build type
statico — nessun server da gestire, nessun database da proteggere
Vedi il codice + spiegazione

Workflow di deploy automatico (.github/workflows/deploy.yml):

name: Deploy
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci && npm run build
      - uses: actions/upload-pages-artifact@v3
        with: { path: ./dist }

  deploy:
    needs: build
    permissions: { pages: write, id-token: write }
    runs-on: ubuntu-latest
    steps:
      - uses: actions/deploy-pages@v4

Cosa state guardando: deploy completamente automatico via GitHub Actions. Ogni push sul branch main attiva: build → upload artifact → deploy. Tempo medio dal push al sito live: 1-2 minuti. Custom domain con TLS auto-rinnovato (Let's Encrypt). Anti-DDoS via CDN provider. Provider attuale: GitHub Pages, CDN GitHub edge network, copertura global. Niente server da patchare, niente database da backuppare, niente superficie d'attacco PHP/SQL.

Vs metodo classico: hosting condiviso (Aruba, Register, OVH) €5-15/mese — server condiviso con N siti, TTFB lento, plugin WordPress vulnerabili, backup spesso non testato. Managed WordPress (Kinsta, WP Engine) €30-100/mese — performance migliore ma lock-in. Qui hosting incluso o <€10/mese, performance superiore, niente lock-in: il codice è vostro, deployabile ovunque in 10 minuti se cambiate fornitore.

10

Stack tecnico

Cosa fa: framework moderno scelto per produrre siti veloci di default. Niente WordPress da aggiornare, niente plugin da rompere, niente database da bucare. Il codice sorgente è versionato su Git: ogni modifica è tracciata, ogni build è riproducibile, ogni deploy è rollback-able in un comando.

Framework
Astro 5.x (Construction starter (concept-driven, AMB-bespoke))
Linguaggio
TypeScript per il codice, Markdown per il contenuto
Animazioni
GSAP + Lenis (rispettano prefers-reduced-motion)
Versionamento
Git — cronologia completa delle modifiche
Deploy
automatico ad ogni push sul branch principale
Vedi il codice + spiegazione

Dipendenze del progetto (package.json):

{
  "name": "amb turning",
  "type": "module",
  "scripts": {
    "dev": "astro dev",
    "build": "astro build"
  },
  "dependencies": {
    "astro": "^5.1.0",
    "@astrojs/sitemap": "^3.5.0",
    "@fontsource-variable/inter": "^5.0.0",
    "gsap": "^3.14.0",
    "lenis": "^1.3.0"
  }
}

Cosa state guardando: stack 2024-2026. Astro 5.x: framework content-driven, build statico, islands architecture. TypeScript strict: ogni componente, ogni dato tipizzato — intere classi di bug runtime impossibili. GSAP 3.14+: libreria di animazione standard industriale, hardware-accelerated. Lenis 1.3+: smooth scroll moderno, più affidabile di scroll-snap CSS. Fontsource: font self-hosted come NPM packages. Astro integrations ufficiali per sitemap, OpenGraph, Schema — non plugin terzi che si rompono. CI/CD via GitHub Actions: rollback con un comando.

Vs metodo classico: WordPress è stack del 2003 con patch successive — PHP 7/8, MySQL, plugin ecosystem caotico, 1-3 CVE/anno per i plugin popolari, manutenzione mensile obbligatoria. Wix/Squarespace è SaaS proprietario: il codice non è vostro, passare a un'altra piattaforma significa ricostruire da zero. Qui stack moderno, codice vostro, hostable ovunque, update Astro/dipendenze ogni 6-12 mesi (non mensile), zero superficie attacco lato server, niente lock-in.

Anteprima non indicizzata. URL finale in corso di configurazione.