Monorepo vs polyrepo: mantenere sincronizzati web, mobile e backend

Il problema reale: distribuire modifiche su tre codebase

I team non discutono di monorepo vs polyrepo per una questione di filosofia Git. Discutono perché una piccola modifica prodotto si trasforma in tre cambi separati su web, mobile e backend, e qualcosa si rompe lungo il percorso.

Quello che si rompe prima raramente è l’interfaccia utente. Di solito è la colla invisibile: un contratto API modificato senza un aggiornamento corrispondente, una libreria condivisa aggiornata in un posto ma non nell’altro, o la pipeline di build che all’improvviso richiede un nuovo step. Quando una parte viene rilasciata prima delle altre, gli utenti lo percepiscono come bug tipo “il pulsante c’è sul web ma l’app mobile dice non supportato” o “l’app resta in caricamento perché la risposta del backend è cambiata”.

Web, mobile e backend corrono anche su orologi di rilascio diversi. Web può rilasciare molte volte al giorno. Il backend può rilasciare spesso, ma con rollout attenti. Mobile è il più lento perché la revisione sugli store e gli aggiornamenti utenti aggiungono un ritardo reale. Una modifica “semplice” come rinominare un campo può costringerti a pianificare attorno alla corsia più lenta, anche se solo una schermata ne ha bisogno.

Probabilmente stai pagando una tassa di coordinamento dei repository se questo succede spesso:

• Le breaking change sulle API vengono scoperte dopo il merge.
• L’allineamento delle versioni dipende da promemoria manuali e fogli di calcolo.
• Una feature richiede più pull request coordinate che restano in attesa l’una dell’altra.
• La CI è lenta perché costruisce e testa molto più di quanto la modifica influenzi.
• I rollback sembrano rischiosi perché non è chiaro quale commit corrisponda a quale release.

La dimensione del team e la maturità del prodotto cambiano la risposta giusta. All’inizio, la maggior parte dei team vince rendendo economica la coordinazione e alta la visibilità, anche se le cose sono un po’ disordinate. Con la crescita, i confini iniziano a contare, ma solo se le interfacce sono stabili e la proprietà è chiara.

Se ogni modifica significativa deve atterrare in tre posti, pagherai quella tassa in un modo o nell’altro. La strategia dei repo riguarda per lo più come vuoi pagarla.

Monorepo e polyrepo in parole semplici

Un repository è solo dove vive il tuo codice, insieme alla sua storia. Quando hai web, mobile e backend, la scelta è semplice: tenere tutto insieme o dividerlo.

Un monorepo è un repository che contiene più app e spesso codice condiviso. Web, iOS/Android, servizi backend e librerie condivise stanno fianco a fianco.

Un polyrepo è l’opposto: ogni app (e a volte ogni servizio) ha il proprio repository. Il codice condiviso di solito diventa un pacchetto separato, o i team copiano pezzi piccoli quando serve.

Nel quotidiano, i monorepo spesso danno questa sensazione: condividere codice è facile, le modifiche cross-app possono essere in una sola pull request e le regole sono coerenti. Il compromesso è sociale: la proprietà può diventare sfocata a meno che non si fissino confini chiari, e i controlli a livello di repo possono sembrare restrittivi.

I polyrepo danno spesso questa sensazione: ogni team può muoversi in autonomia, i repository restano focalizzati e il controllo degli accessi può essere più semplice. Il compromesso è la coordinazione: condividere codice richiede pianificazione e le modifiche cross-app spesso diventano più pull request con timing attento.

Molti team finiscono con un ibrido: app in repo separati, contratti condivisi in un unico posto; o un monorepo con confini forti così che ogni team rimane per lo più nella propria area.

Se usi una piattaforma che genera backend, web e mobile da una sola fonte di verità, riduci il drift perché contratti e logica vivono insieme. AppMaster (appmaster.io), per esempio, genera backend pronti per la produzione, web e app native da un unico modello. Questo non elimina le realtà delle release (mobile rimane più lento), ma può eliminare gran parte dell’overhead “abbiamo aggiornato tutti e tre i posti?”.

Gestione delle dipendenze: tenere al sicuro il codice condiviso

Il codice condiviso è dove i team perdono tempo, indipendentemente dalla disposizione dei repo. Una piccola modifica in una libreria condivisa o in un contratto API può rompere build web, release mobile e deploy backend in modi diversi.

Quando condividi librerie (componenti UI, regole di validazione, helper di auth), scegli tra avere una versione per tutti o più versioni nel tempo.

• Una versione è più semplice e evita sorprese tipo “funziona nel mio branch”.
• Più versioni permettono ai team di muoversi al proprio ritmo, ma creano confusione e rendono più difficili le patch di sicurezza.

Client API e schemi meritano cura extra. Gli aggiornamenti manuali sono lenti e soggetti a errori. Un pattern migliore è trattare lo schema API come fonte di verità e generare i client da esso, poi o inserirli nel repository o generarli in CI. L’obiettivo è fallire velocemente: se il backend aggiunge un campo obbligatorio, il client mobile dovrebbe rompersi in build, non tre giorni dopo in QA.

Le breaking change si diffondono quando il comportamento cambia senza una via di compatibilità. Preferisci prima cambi additivi (nuovi campi, nuovi endpoint), poi depreca. Se devi rompere qualcosa, usa endpoint versionati o una finestra di compatibilità breve.

Esempio concreto: il backend rinomina status in state. Se il web si aggiorna oggi ma il mobile non può spedire per una settimana, il backend deve accettare entrambi i campi per quella settimana o distribuire un adapter che mappi il campo vecchio a quello nuovo.

Alcune regole che rendono gli aggiornamenti di dipendenze noiosi (in senso buono):

• Aggiorna con una cadenza. Aggiornamenti settimanali piccoli battono quelli trimestrali grandi.
• Richiedi approvazione esplicita per le breaking change, più una breve nota di migrazione.
• Automatizza i controlli: aggiornamenti di dipendenze, rigenerazione dei client e test di contratto di base.
• Definisci “fatto” come “web, mobile e backend buildano correttamente”, non “il mio repo passa”.

Il codice generato può ridurre il drift, ma non sostituisce la disciplina. Serve ancora un contratto unico, deprecazioni chiare e aggiornamenti prevedibili.

Coordinamento delle release: allineare web, mobile e backend

Il coordinamento delle release è dove la strategia dei repo smette di essere teorica. Se il backend cambia il nome di un campo API, il web di solito si può aggiornare e rilasciare lo stesso giorno. Le app mobile sono diverse: la revisione sugli store e i tempi di aggiornamento degli utenti possono trasformare una piccola discrepanza in una settimana di ticket di supporto.

L’obiettivo pratico è semplice: un’azione utente dovrebbe funzionare indipendentemente da quale parte si aggiorna per prima. Questo significa pianificare per versioni miste, non assumere una sincronizzazione perfetta.

Pattern di versioning che i team usano davvero

La maggior parte dei team si stabilizza su uno di questi approcci:

1. Un unico treno di release condiviso: web, mobile e backend vengono rilasciati come un’unità versione.

2. Versioni per servizio con regole di compatibilità: ogni app/servizio ha la sua versione, e il backend supporta un intervallo definito di versioni client.

Un treno di release condiviso sembra ordinato, ma spesso si rompe con i ritardi mobile. Le versioni per servizio sono più caotiche sulla carta, ma rispecchiano la realtà. Se scegli per-servizio, scrivi una regola e applicala: quali versioni del backend devono supportare quali versioni mobile e per quanto tempo.

I ritardi mobile cambiano anche come gestisci i hotfix. I fix backend possono uscire subito; gli hotfix mobile potrebbero non raggiungere gli utenti per giorni. Preferisci fix lato server che mantengano funzionanti le vecchie build mobile. Quando devi cambiare il client, usa feature flag e evita di rimuovere campi vecchi finché non sai che la maggior parte degli utenti si è aggiornata.

Esempio: aggiungi “istruzioni di consegna” al flusso d’ordine. Il backend aggiunge un nuovo campo opzionale, il web lo mostra subito, e il mobile lo mostra nel prossimo sprint. Se il backend accetta richieste vecchie e mantiene il campo opzionale, tutto continua a funzionare mentre il mobile si aggiorna.

Chi possiede il calendario delle release

La coordinazione fallisce quando “tutti lo possiedono” e quindi nessuno lo fa. Il proprietario può essere un tech lead, un release manager o un product manager con forte supporto tecnico. Il suo lavoro è prevenire sorprese mantenendo le aspettative di rilascio visibili e coerenti.

Non serve un processo complesso. Serve qualche abitudine ripetibile: un calendario di release semplice con cutoff e freeze window, un rapido controllo cross-team prima che le API cambino, e un piano chiaro per cosa succede quando mobile è in ritardo (bloccare il backend o mantenere la compatibilità).

Se il tuo workflow genera web, mobile e backend insieme da un unico modello, hai comunque bisogno di un owner delle release. Avrai di solito meno momenti “abbiamo aggiornato tutti e tre i posti?”, ma non sfuggirai ai tempi del mobile.

Tenere sotto controllo i tempi di CI

La CI rallenta per le stesse ragioni in entrambi gli approcci: ricostrui troppo, reinstalli le dipendenze ripetutamente e esegui ogni test su ogni cambiamento.

I colpevoli comuni includono build complete su piccole modifiche, cache mancanti, suite di test che eseguono tutto e job seriali che potrebbero girare in parallelo.

Inizia con miglioramenti che aiutano ovunque:

• Metti in cache download delle dipendenze e output di build.
• Esegui lint, unit test e build in parallelo dove possibile.
• Separa controlli veloci (ogni commit) da controlli più lenti (main branch, nightly o pre-release).

Tattiche per monorepo che aiutano

I monorepo diventano pesanti quando ogni commit attiva una pipeline “build the world”. La soluzione è costruire e testare solo ciò che è influenzato dalla modifica.

Usa filtri per percorso e un approccio affected-only: se hai cambiato codice UI mobile, non ricostruire le immagini backend. Se hai toccato una libreria condivisa, costruisci e testa solo le app che ne dipendono. Molti team formalizzano questo con un semplice grafo di dipendenze così la CI può decidere invece di indovinare.

Tattiche per polyrepo che prevengono il drift

I polyrepo possono essere veloci perché ogni repo è più piccolo, ma spesso sprecano tempo tramite duplicazione e tool incoerenti.

Mantieni un set condiviso di template CI (stessi step, stesse cache, stesse convenzioni) così ogni repo non reinventa la pipeline. Blocca le versioni degli strumenti (runtime, tool di build, linters) per evitare il problema “funziona in un repo ma non in un altro”. Se i download delle dipendenze sono un collo di bottiglia, configura cache condivise o mirror interni così ogni repo non scarica il mondo da zero.

Esempio concreto: una feature aggiunge un nuovo campo “status”. Backend cambia, web lo mostra, mobile lo mostra. In un monorepo, la CI dovrebbe eseguire i test backend più solo le parti web e mobile che dipendono dal client API. In un setup polyrepo, ogni repo dovrebbe eseguire i propri controlli rapidi e una pipeline di integrazione separata può validare che le tre release siano ancora allineate.

Se esporti codice sorgente ed esegui la tua CI, vale la stessa regola: costruisci solo ciò che è cambiato, riusa le cache aggressivamente e riserva i controlli lenti per quando aggiungono valore reale.

Passo dopo passo: scegliere una strategia di repo che si adatti al tuo team

La decisione diventa più facile quando parti dal lavoro quotidiano invece che dall’ideologia.

1) Scrivi cosa deve cambiare insieme

Scegli 5–10 feature recenti e annota cosa ha dovuto muoversi in lockstep. Segna se ciascuna ha toccato schermate UI, endpoint API, tabelle dati, regole di autenticazione o validazione condivisa. Se la maggior parte delle feature richiede cambi coordinati in tutte e tre le aree, una disposizione spezzata sarà dolorosa a meno che il tuo processo di rilascio non sia molto disciplinato.

2) Traccia il codice e le decisioni condivise

Il codice condiviso non sono solo librerie. Sono anche contratti (schemi API), pattern UI e regole di business. Annota dove vivono oggi, chi li modifica e come vengono approvati i cambiamenti. Se i pezzi condivisi sono copiati tra repository, è un segno che hai bisogno di controllo più stretto, sia tramite monorepo sia tramite regole di versioning rigorose.

3) Definisci confini e proprietari

Decidi quali sono le unità (app, servizi, librerie), poi assegna un owner a ciascuna unità. I confini contano più della disposizione dei repo. Senza owner, un monorepo diventa rumoroso. Senza owner, un polyrepo diventa disconnesso.

Se vuoi una checklist semplice, punta a: un repository o una cartella per ogni servizio/app deployabile, un posto per i contratti condivisi, un posto per i componenti UI veramente condivisi, una regola chiara su dove vive la logica di business e un owner documentato per ciascuno.

4) Scegli un modello di release che puoi seguire

Se i rilasci mobile ritardano rispetto ai backend, ti serve un piano di compatibilità (API versionate, campi backward-compatible o una finestra di supporto definita). Se tutto deve rilasciare insieme, un release train può funzionare, ma aumenta la coordinazione.

Mantieni noiose le regole di branching: branch a vita breve, merge piccoli e una strada chiara per gli hotfix.

5) Progetta la CI attorno ai cambi comuni

Non progettare la CI per il caso peggiore fin dal primo giorno. Progettala per ciò che le persone fanno ogni giorno.

Se la maggior parte dei commit tocca solo la UI web, esegui per default lint e unit test web e lasci i test end-to-end completi su programma o prima delle release. Se la maggior parte degli incidenti deriva dal drift delle API, investi prima in test di contratto e generazione client.

Esempio: una feature che tocca web, mobile e backend

Immagina un piccolo team che costruisce tre cose insieme: un portale clienti (web), un’app sul campo (mobile) e un’API (backend). Arriva una richiesta: aggiungere un nuovo campo “Service status” ai job e mostrarlo ovunque.

La modifica sembra piccola, ma è un test di coordinazione. Il backend aggiunge il campo e aggiorna validazione e risposte. Il web lo mostra e aggiorna i filtri. Il mobile deve mostrarlo offline, sincronizzarlo e gestire i casi limite.

Ora il problema reale: il cambio API è breaking. Il nome del campo cambia da status a service_status, e i client vecchi vanno in crash se non lo gestiscono.

Cosa cambia con un monorepo

Qui un monorepo spesso sembra più calmo. Backend, web e mobile possono atterrare in una singola pull request (o un set coordinato di commit). La CI può eseguire i test interessati e puoi taggare una release che include tutti e tre gli aggiornamenti.

Il rischio principale è sociale, non tecnico: un unico repo facilita il merge rapido di una breaking change, quindi le regole di review devono essere forti.

Cosa cambia con un polyrepo

Con repository separati, ogni app vive sul proprio calendario. Il backend potrebbe rilasciare per primo e web e mobile correranno per aggiornarsi. Se le release mobile richiedono revisione sullo store, il “fix” può richiedere giorni anche se la modifica al codice è piccola.

I team risolvono di solito con più struttura: endpoint versionati, risposte backward-compatible, windows di deprecazione più lunghe e passi di rollout più chiari. Funziona, ma è lavoro continuo.

Se decidi basandoti sui dati, guarda gli ultimi mesi:

• Se gli incidenti spesso nascono da versioni non allineate, favorisci una coordinazione più stretta.
• Se i rilasci sono frequenti e sensibili al tempo (soprattutto mobile), evita breaking change o centralizzale.
• Se i team sono indipendenti e raramente toccano la stessa feature, l’overhead del polyrepo può valerne la pena.

Errori comuni e trappole da evitare

La maggior parte dei team non fallisce perché ha scelto la struttura “sbagliata” dei repository. Fallisce perché le abitudini quotidiane aggiungono attrito finché ogni cambiamento sembra rischioso.

Il codice condiviso diventa una discarica

Una libreria condivisa è allettante: helper, tipi, pezzi UI, workaround “temporanei”. Presto diventa il posto dove il codice vecchio si nasconde e nessuno sa cosa sia sicuro cambiare.

Mantieni il codice condiviso piccolo e rigoroso. “Condiviso” dovrebbe significare usato da molti team, rivisto con cura e cambiato con intenzione.

Accoppiamento stretto tramite assunzioni nascoste

Anche in repo separati, i sistemi possono essere fortemente accoppiati. L’accoppiamento si sposta nelle assunzioni: formati data, valori enum, regole di permessi e “questo campo è sempre presente”.

Esempio: mobile tratta status = 2 come “Approved”, web come “Confirmed”, il backend cambia l’ordine degli enum e tutto si rompe in modo che sembra casuale.

Previeni questo documentando i contratti (cosa significano i campi, quali valori sono permessi) e trattandoli come regole di prodotto, non come trivia.

Proprietà poco chiara

Quando tutti possono cambiare tutto, le review diventano superficiali e gli errori passano. Quando nessuno possiede un’area, i bug restano settimane.

Definisci owner per web, mobile, backend e moduli condivisi. L’ownership non blocca i contributi; assicura che i cambiamenti abbiano gli occhi giusti.

CI che cresce senza potatura

La CI spesso inizia piccola, poi ogni incidente aggiunge un nuovo job “per sicurezza”. Mesi dopo è lenta e costosa e la gente la evita.

Una regola semplice aiuta: ogni job CI ha uno scopo chiaro e un owner, e va rimosso se smette di catturare problemi reali.

Segnali d’allarme per una pulizia: test duplicati tra job, job che restano rossi per giorni, “cambi rapidi” che impiegano più tempo a verificare che a buildare e pipeline che attivano build mobile su cambiamenti solo backend.

Coordinamento delle release basato sulla conoscenza tribale

Se le release dipendono da una persona che si ricorda l’ordine giusto e i trucchi segreti, rilascerai più lentamente e romperai più cose.

Documenta i passi di release, rendili ripetibili e automatizza i controlli noiosi. Anche se il tuo tooling genera backend e client coerenti, hai comunque bisogno di regole di rilascio chiare.

Controlli rapidi prima di impegnarsi in monorepo o polyrepo

Prima di riorganizzare repository, verifica come il tuo team rilascia oggi. L’obiettivo non è una struttura perfetta, ma meno sorprese quando una modifica tocca web, mobile e backend.

Fatti cinque domande:

• Indipendenza di rilascio: puoi rilasciare una correzione backend senza forzare un aggiornamento mobile lo stesso giorno?
• Regole di cambiamento API: avete un contratto scritto per le deprecazioni e per quanto tempo il comportamento vecchio resta supportato?
• Disciplina sul codice condiviso: le librerie condivise (componenti UI, client API, regole di business) sono riviste e versionate coerentemente?
• CI che esegue ciò che conta: la CI può capire cosa è cambiato ed eseguire build/test solo per le parti interessate?
• Una vista unica delle release: c’è un posto dove vedere cosa sta uscendo su web, mobile e backend, con owner e date?

Esempio semplice: si aggiunge un campo “address” al checkout. Se il backend rilascia prima, la vecchia app mobile dovrebbe comunque funzionare. Questo di solito significa che l’API accetta sia payload vecchi sia nuovi per un periodo e gli update client sono opzionali, non obbligatori.

Passi successivi: ridurre il lavoro di coordinamento e rilasciare con fiducia

L’obiettivo non è la struttura di repo “giusta”. È avere meno handoff, meno sorprese e meno momenti “aspetta, quale versione è live?”.

Scrivi un breve decision record: perché hai scelto l’approccio attuale, cosa ti aspetti che migliori e quali compromessi accetti. Riesamina la decisione ogni 6–12 mesi, o prima se cambia la dimensione del team o la cadenza di rilascio.

Prima di spostare file, scegli la modifica più piccola che elimina il dolore reale:

• Aggiungi e segui regole di versioning per i pacchetti condivisi.
• Definisci i contratti API e applicali con test di contratto in CI.
• Concorda una checklist di release unica per web, mobile e backend.
• Usa ambienti di preview per le modifiche che toccano più parti.
• Imposta budget di tempo per la CI (esempio: controlli PR sotto 15 minuti).

Se l’accoppiamento cross-codebase è il vero collo di bottiglia, ridurre il numero di posti che devono cambiare può contare più della disposizione dei repo. Alcuni team lo fanno spostando più logica e modellazione dei dati in una singola fonte di verità.

Se vuoi esplorare quell’approccio, AppMaster (appmaster.io) è costruito per generare servizi backend, app web e native con modelli di dati e logica di business condivisi. Un modo a basso rischio per valutarlo è costruire prima un piccolo strumento interno, poi decidere in base a quanto lavoro di coordinamento rimuove.

La strada sicura è volutamente noiosa: documenta la decisione, riduci l’accoppiamento, automatizza i controlli e cambia la struttura dei repo solo quando i numeri dimostrano che aiuterà.