Chiunque abbia integrato un frontend con un backend sa come va a finire.
Sulla carta è un'attività lineare: il backend espone endpoint, il frontend li consuma. Nella pratica è dove si disperde molto tempo di sviluppo. Ci si ritrova a discutere se un campo si chiama userId o user_id, a capire cosa significa esattamente quel 400 che il backend ha appena restituito, a riscrivere a mano i tipi del frontend perché qualcuno ha aggiunto una proprietà nel DTO e nessuno se n'è accorto. Si parte da una stima di tre giorni e si finisce a due settimane, non perché il problema fosse complesso, ma perché ogni piccola incoerenza richiede una chiamata, una mappatura manuale, un fix.
Il problema si moltiplica quando i frontend sono due, uno web ed uno mobile, perché ogni convenzione va ribattuta in linguaggi diversi, da team diversi, con il rischio concreto che web e mobile finiscano per gestire lo stesso errore in due modi differenti. E si moltiplica ancora quando entra in gioco l'AI: gli assistenti di coding moderni sono velocissimi quando il codice ha pattern chiari, ma diventano una fonte di bug quando devono indovinare convenzioni implicite. Se ogni progetto parla un dialetto diverso, l'AI inventa e quello che produce sembra corretto, ma non lo è.
È in questi contesti che il tempo viene investito male: al posto di dedicare tempo e risorse a task importanti si perde tempo nel fare la correzione a quel backend perché non è stato definito uno standard per tutte le tipologie di frontend.
Abbiamo perciò deciso di definire una specifica unica che attraversi tutti i livelli — backend, web, mobile — e implementarla in modo che sia leggibile sia dagli sviluppatori sia dalle AI che lavorano con noi.
Una specifica, tre implementazioni coerenti
Abbiamo definito una specifica unica che vive a tre livelli:
Backend
Ogni risposta segue un formato standardizzato. I successi portano payload e metadati (paginazione, traccia di correlazione, deprecazione). Gli errori seguono RFC 9457 Problem Details for HTTP APIs, lo standard IETF per la rappresentazione strutturata degli errori HTTP: ogni errore ha un type che lo identifica, un title, uno status, un detail leggibile, e campi specifici per il contesto.
React (TypeScript)
Un pacchetto core interno, costruito sopra axios, che applica lo stesso modello: client HTTP configurabile, interceptor di autenticazione, gestione del token centralizzata, helper per query e mutation che fanno unwrap delle risposte e propagano gli errori in modo uniforme e tipizzato. Le liste paginate vengono normalizzate leggendo direttamente i metadati del server.
Flutter (Dart)
Un pacchetto gemello, costruito sopra DIO, con la stessa API pubblica del fratello React. Stesso modello funzionale, stessi nomi dei moduli, stesse strutture dati. Chi passa da web a mobile trova un terreno familiare.
I due pacchetti non condividono lo stesso codice: uno è scritto in TypeScript, l'altro in Dart, ma condividono il design. Ogni decisione viene presa una volta sola e applicata a entrambi.
Modelli generati, non scritti
Una parte centrale del lavoro riguarda i modelli dei dati. Se il backend ha una specifica OpenAPI ben fatta, riscrivere a mano i tipi lato client è autolesionismo: è codice che invecchia in silenzio, che si disallinea ad ogni modifica.
Abbiamo costruito un generatore che, da un singolo openapi.json, produce:
- Su React: tipi TypeScript con schemi Zod corrispondenti, pronti per la validazione runtime
- Su Flutter: classi Dart con annotazioni Freezed, immutabili e serializzabili
La parte intelligente è la selezione mirata con risoluzione automatica delle dipendenze transitive: gli dici quali tipi ti servono e lui scarica tutto ciò che quei tipi referenziano. Niente più output gonfiati con centinaia di entità che il frontend non userà mai. Niente più disallineamenti silenziosi quando il backend cambia.
Un comando ed il modello dati è sincronizzato.
Perché questo accelera anche il lavoro con l'AI
Questa è la parte che troviamo più interessante e che non avremmo potuto raccontare con la stessa forza qualche anno fa.
Gli assistenti AI che usiamo sono potentissimi quando il codice ha pattern chiari. Lo sono molto meno quando devono indovinare convenzioni implicite. Se ogni nostro progetto chiamasse gli errori in modo diverso, l'AI dovrebbe imparare a ogni file il nostro dialetto locale. Spesso sbaglierebbe.
Con una specifica formale e uniforme accade qualcosa di diverso. Quando chiediamo all'AI di scrivere un nuovo endpoint o di consumarne uno esistente, lei trova:
- Tipi TypeScript/Dart espliciti e tipizzati, generati dalla OpenAPI
- Schemi Zod che descrivono cosa è valido e cosa no
- Helper di query e mutation con firme chiare
- Errori in un formato standard IETF che l'AI conosce già
Risultato: il codice che produce è corretto al primo colpo molto più spesso. Non perché l'AI sia “migliore”, ma perché il nostro codebase le dà gli appigli giusti per capirlo. È la stessa ragione per cui un nuovo sviluppatore impara il nostro stack più in fretta: la differenza è che ora questa accelerazione vale anche per il pair programming con un assistente.
In pratica: l'investimento sulla coerenza, fatto per gli umani, paga un dividendo aggiuntivo sull'AI. E nel 2026 questo dividendo non è marginale.
Cosa cambia, concretamente
Lasciamo perdere i numeri perché ogni team li misurerebbe diversamente, ma il pattern lo vediamo chiaramente:
- 1
Un nuovo progetto parte con il data layer già risolto. I primi giorni non si spendono a costruire l'infrastruttura ma a scrivere le prime feature.
- 2
Un nuovo sviluppatore non deve imparare come “parla” il progetto: lo sa già. Impara il dominio, che è dove vogliamo spenda energia mentale.
- 3
Quando il backend cambia un endpoint, basta rigenerare i modelli e il compilatore segnala dove intervenire. Niente mappature manuali che si rompono in silenzio.
- 4
Quando lavoriamo con l'AI, produce codice di qualità con molta più frequenza, perché il pattern è esplicito e ripetuto ovunque.
Vuoi questo livello di coerenza nei tuoi progetti?
Codebaker progetta architetture full-stack pensate per lavorare bene sia con gli sviluppatori sia con gli assistenti AI. Se vuoi capire come applicare questo approccio al tuo prodotto, parliamone.
Contattaci