Come usiamo Sutram per alimentare il nostro stesso sito web

Dogfooding al suo meglio: Sutram serve il proprio blog e la documentazione in sei lingue

La premessa

C'è un detto nel software: se non useresti il tuo stesso prodotto, perché dovrebbe farlo qualcun altro? In Sutram, l'abbiamo preso a cuore. Il nostro sito marketing — quello che stai leggendo proprio ora — è alimentato interamente dall'infrastruttura di contenuti di Sutram.

Ogni articolo del blog, ogni pagina di documentazione, ogni contenuto che vedi qui è archiviato, organizzato e servito da un progetto Sutram. Questa non è una demo. È produzione.

L'architettura

Il sito è costruito con Astro, un moderno generatore di siti statici. Al momento della build, Astro chiama la REST API di Sutram per recuperare tutti i contenuti, li renderizza in HTML statico e li distribuisce su Netlify. Nessuna dipendenza a runtime, nessuna query al database al caricamento della pagina — solo pagine veloci e pre-costruite.

Il flusso dei contenuti si presenta così:

Progetto Sutram
  └── /{lang}/Blog/{year}/{post-slug}/
  │     ├── post.md          (corpo markdown)
  │     └── cover.jpg         (immagine di copertina, opzionale)
  └── /{lang}/Docs/{category}/{doc-slug}/
        └── guide.md          (corpo markdown)

        ↓  Sutram REST API  ↓

Astro (tempo di build)
  → recupera cartelle + tag
  → scarica file markdown
  → converte immagini di copertina in WebP
  → renderizza in HTML statico

        ↓  deploy  ↓

Netlify (CDN)

Sei lingue, una struttura

Il sito supporta sei lingue: inglese, portoghese, spagnolo, francese, tedesco e italiano. Invece di mantenere sistemi di contenuti separati o duplicare gerarchie di cartelle, usiamo una semplice convenzione: la lingua è la radice.

/en/Blog/2026/how-we-use-sutram/
/pt/Blog/2026/como-usamos-o-sutram/
/es/Blog/2026/como-usamos-sutram/

Ogni lingua ha la propria cartella Blog e Docs in Sutram. Il client API mappa i codici lingua agli ID delle cartelle e recupera i contenuti di conseguenza — nessun filtraggio per tag, nessuna logica di routing complessa. Il percorso della cartella è la lingua.

Le stringhe dell'interfaccia del sito (navigazione, pulsanti, etichette) sono gestite separatamente tramite file di traduzione JSON, ma tutti i contenuti sostanziali — gli articoli e le guide che leggi effettivamente — vivono in Sutram.

Metadati come tag

Ogni cartella di contenuti in Sutram porta metadati come tag — semplici coppie chiave-valore associate alla cartella stessa:

Tag	Scopo
`title`	Titolo visualizzato dell'articolo o della guida
`author`	Nome dell'autore dell'articolo
`excerpt`	Breve descrizione per gli elenchi e la SEO
`category`	Categoria del contenuto (es. "Engineering", "Product")
`published_at`	Data di pubblicazione (controlla visibilità e ordinamento)

Questa è una delle funzionalità principali di Sutram: metadati strutturati su qualsiasi cartella, senza schemi rigidi. Il client API legge questi tag per costruire pagine di elenco, filtri per categoria e feed RSS — tutto al momento della build.

Immagini di copertina con ottimizzazione automatica

Gli articoli del blog possono includere un'immagine di copertina come file all'interno della cartella dell'articolo. Durante la build, il client Astro:

Rileva il primo file immagine nella cartella
Lo scarica tramite la Sutram API
Lo converte in formato WebP usando sharp
Lo ridimensiona a 1200x630 (ottimizzato per la condivisione social)
Lo salva nella directory di output statica

Questo significa che gli autori devono solo inserire un'immagine nella cartella Sutram — nessun ridimensionamento manuale, nessuna conversione di formato, nessuna configurazione CDN.

Gestire i contenuti con AI e MCP

Qui la cosa diventa interessante. Non usiamo un'interfaccia CMS tradizionale per scrivere e pubblicare contenuti. Invece, usiamo Claude Code con il Sutram MCP Server.

Il flusso di lavoro:

Scrivere o tradurre un articolo in markdown (spesso con l'aiuto di Claude Code)
Creare la cartella di destinazione in Sutram tramite sutram_create_folder
Impostare i tag dei metadati tramite sutram_set_folder_tags
Caricare il file markdown tramite sutram_request_upload + sutram_confirm_upload
Attivare una build Netlify

Tutto questo avviene dal terminale, in un'unica sessione di conversazione. Nessun browser, nessun campo modulo, nessun copia-incolla. L'agente AI legge il contenuto, crea la struttura delle cartelle, imposta i tag, carica il file e il sito si ricostruisce automaticamente.

Questo stesso articolo è stato scritto, tradotto in portoghese e pubblicato su Sutram usando esattamente questo flusso di lavoro.

Il client API

Il cuore dell'integrazione è un singolo file TypeScript (sutram.ts) che funge da ponte tra Sutram e Astro. Gestisce:

Scoperta dei contenuti — percorre ricorsivamente le cartelle Sutram per trovare i record di contenuto (qualsiasi cartella con un tag title)
Recupero dei markdown — scarica il primo file .md da ogni cartella di contenuto
Elaborazione delle immagini — converte le immagini di copertina in WebP ottimizzato
Fallback con dati fittizi — restituisce contenuti segnaposto quando le credenziali API non sono configurate (per lo sviluppo locale)

Il client è circa 460 righe di TypeScript. Nessun framework, nessun ORM, nessun livello di astrazione — solo chiamate fetch alla Sutram API e sharp per l'elaborazione delle immagini.

Perché è importante

Il dogfooding non è solo una questione di credibilità. Ci costringe a sperimentare le stesse frizioni che affrontano i nostri utenti. Ogni spigolo nell'API, ogni funzionalità mancante, ogni comportamento confuso — lo avvertiamo per primi.

Alcune cose che abbiamo scoperto e migliorato usando Sutram per il nostro stesso sito:

Il rilevamento dei contenuti basato su tag funziona meglio delle convenzioni rigide di denominazione delle cartelle
L'attraversamento ricorsivo delle cartelle è essenziale per gerarchie di contenuti flessibili
L'MCP Server rende la gestione dei contenuti dal terminale non solo possibile, ma preferibile per i team tecnici
Le radici delle cartelle per lingua sono più semplici del filtraggio linguistico basato su tag

I numeri

Metrica	Valore
Lingue supportate	6 (en, pt, es, fr, de, it)
Tipi di contenuto	2 (articoli del blog, documentazione)
Chiamate API per build	~20-30
Tempo di build	< 30 secondi
JavaScript a runtime	0 (HTML statico)
Interfaccia CMS utilizzata	Nessuna (MCP + terminale)

Conclusione

Usare Sutram per alimentare il nostro stesso sito è la dichiarazione più forte che possiamo fare sulla piattaforma. Non è un progetto giocattolo o un proof of concept — è il sistema di produzione che serve ogni pagina che vedi qui.

Se i tuoi contenuti hanno bisogno di struttura, il tuo team ha bisogno di controllo e il tuo flusso di lavoro beneficia dell'automazione — Sutram è stato costruito esattamente per questo. E lo dimostriamo ogni giorno, a partire da questa stessa pagina.