Oceano di Versi

Cos’è

Oceano di Versi è una piattaforma social per iOS dedicata esclusivamente alla poesia. Nasce dall’idea che i versi meritino uno spazio proprio, lontano dal rumore dei social generalisti: un ambiente moderato che incoraggia l’espressione creativa quotidiana e premia la costanza.

L’app è completamente localizzata in sei lingue — italiano, inglese, tedesco, spagnolo, francese e portoghese brasiliano — e pubblicata sull’App Store.

Funzionalità principali

• Doppio feed — uno globale per scoprire nuovi poeti e uno dedicato ai profili seguiti.
• Tag emotivi — ogni poesia è associata a un’emozione (Amore, Malinconia, Gioia, Rabbia, Speranza, Solitudine, Nostalgia, Pace, Passione, Dolore) per esplorare i versi per stato d’animo.
• Editor ricco — composizione con copertina opzionale, salvataggio come bozza e pubblicazione pubblica o privata.
• Interazioni sociali — like, commenti, follow e condivisione tramite deep link con metadati Open Graph per anteprime ricche fuori dall’app.
• Ricerca full-text — utenti e poesie indicizzati con Algolia per trovare subito autori e versi.
• Prompt giornaliero — ogni giorno a mezzanotte (Europe/Rome) Gemini genera una domanda introspettiva in tutte le lingue supportate, mostrata in cima al feed.
• Classifica mensile — +1 punto per ogni giorno con almeno una pubblicazione pubblica, −3 per ogni giornata persa. Il vincitore del mese resta in evidenza nel feed per i primi 7 giorni del mese successivo.
• Moderazione AI — ogni poesia, commento e foto profilo viene analizzato da Gemini 2.5 Flash prima della pubblicazione, con pannello admin per la revisione umana dei contenuti segnalati.
• Segnalazioni e report — sistema integrato di segnalazione utenti e contenuti, con notifica automatica ai moderatori.
• Autenticazione flessibile — login via Email, Google Sign-In e Apple Sign-In.
• Oceano Pro — abbonamento mensile o annuale via StoreKit 2, con bozze illimitate, badge verificato e funzionalità premium.
• Centro notifiche — hub interno per like, commenti, nuovi follower e aggiornamenti di moderazione, con push FCM multilingua.

Architettura

L’app è scritta interamente in SwiftUI (iOS 18.6+) e segue il pattern MVVM con Firestore come fonte di verità unica. Tutti i listener sono in tempo reale, senza polling.

Il backend è composto da 22 Cloud Functions Gen 2 in Node.js 22, deployate su europe-west1, che gestiscono:

• moderazione AI di poesie, commenti e foto profilo;
• invio di notifiche push per like, commenti, follow e nuove pubblicazioni;
• aggiornamento dei punteggi della classifica e chiusura mensile automatica;
• generazione dei prompt giornalieri multilingua;
• sincronizzazione con Algolia per la ricerca full-text;
• propagazione delle modifiche profilo (nome, foto, premium) su tutti i contenuti correlati;
• generazione di metadati Open Graph per la condivisione tramite deep link;
• gestione GDPR-compliant della cancellazione account.

Due ambienti speculari — produzione e staging — permettono test isolati su dispositivi reali grazie a Bundle ID differenti.

Esempi di codice

Feed paginato con Firestore (SwiftUI)

ViewModel reattivo, query Firestore ordinata per timestamp con cursore per la paginazione:

@Published var globalPoesie: [Poesia] = []
private var lastDoc: DocumentSnapshot?

var query = db.collection("poems")
    .order(by: "timestamp", descending: true)
    .limit(to: 10)

if let cursor = lastDoc {
    query = query.start(afterDocument: cursor)
}

Moderazione AI con Gemini (Cloud Function)

Le poesie passano da pendingPoems prima di arrivare su poems: un trigger Firestore chiama Gemini e decide il verdetto.

exports.moderatePendingPoem = onDocumentCreated(
  { document: "pendingPoems/{poemId}", secrets: [GEMINI_API_KEY] },
  async (event) => {
    const verdict = await runGeminiModeration(event.data.data());

    if (verdict === "block") return quarantinePoem(event);
    return promotePoemFromPending(event);
  }
);

Dettagli completi (fail-open, override, foto profilo) nella pipeline di moderazione in fondo alla pagina.

Stack

Layer	Tecnologia
App iOS	SwiftUI, Swift 5, iOS 18.6+
Autenticazione	Firebase Auth (Email, Google, Apple)
Database	Cloud Firestore
Storage	Firebase Storage
Backend	Cloud Functions Gen 2 (Node.js 22)
Ricerca	Algolia
Moderazione AI	Gemini 2.5 Flash
Push	Firebase Cloud Messaging
Abbonamenti	StoreKit 2

Sviluppo con agenti AI

L’intero codice — app iOS, Cloud Functions, regole Firestore, localizzazioni e questa documentazione — è stato scritto in collaborazione con più agenti AI (Claude e Codex). Il ruolo umano è stato: definire requisiti e vincoli, rivedere diff e architettura, decidere tradeoff non ovvi (es. fail-open sulla moderazione, floor a 0 sul punteggio, puntatore stabile per il prompt giornaliero). Gli agenti hanno prodotto implementazioni, test, refactor e documentazione; ogni cambio è passato per review prima del merge.