Architettura
Clean Architecture in Flutter: principi e implementazione
Guida completa alla Clean Architecture in Flutter: dalla regola delle dipendenze ai layer Domain, Data e Presentation, con struttura cartelle e best practice.

In questo articolo
- Introduzione: perché l'architettura conta
- Cos'è la Clean Architecture
- La regola delle dipendenze
- I layer nella Clean Architecture (versione Flutter)
- Struttura delle cartelle
- Use Cases: il ponte tra UI e Domain
- Repository Pattern
- Dependency Injection
- Integrazione con Riverpod e BLoC
- Quando usare la Clean Architecture
- Quando evitarla (o semplificarla)
- Conclusione
Introduzione: perché l'architettura conta
Quando un'app Flutter cresce oltre il proof-of-concept, la domanda architetturale si fa pressante: come organizzare il codice in modo che resti manutenibile, testabile e scalabile? La risposta più citata è la Clean Architecture, introdotta da Robert C. Martin (Uncle Bob) nel 2012 e adattata da migliaia di team al mondo Flutter.
Questo articolo ti guida attraverso i principi, i layer, l'implementazione pratica in Flutter e quando ha senso adottarla — o quando invece può essere overkill.
Cos'è la Clean Architecture
La Clean Architecture è un approccio di progettazione software che separa l'applicazione in cerchi concentrici: i cerchi interni contengono la logica di business (le politiche), quelli esterni i dettagli implementativi (database, UI, framework). L'obiettivo è rendere il sistema indipendente da framework, database, UI e qualsiasi agenzia esterna.
I benefici dichiarati
- Indipendenza dal framework: puoi sostituire Flutter con un altro framework senza stravolgere la logica.
- Indipendenza dal database: swap tra SQLite, Firestore, API REST senza toccare le regole di business.
- Indipendenza dalla UI: la stessa logica può servire mobile, web, CLI.
- Testabilità: la business logic è testabile senza UI, DB o web server.
La regola delle dipendenze
Il cuore della Clean Architecture è la Dependency Rule: le dipendenze del codice possono puntare solo verso l'interno. Nessun cerchio interno può conoscere nulla di ciò che sta in un cerchio esterno. In altre parole, il Domain non deve importare Flutter, http, sqlite o qualsiasi package di infrastruttura. Solo il contrario è ammesso: i layer esterni dipendono da quelli interni, mai il contrario.
Questo si ottiene grazie al principio di Dependency Inversion: il dominio definisce interfacce (abstract repository, porte), e i layer esterni le implementano. Così il flusso di controllo va dalla UI verso il dominio, ma le dipendenze del codice vanno dalla UI verso il dominio — tramite le interfacce.
I layer nella Clean Architecture (versione Flutter)
In Flutter si usano tipicamente tre layer principali, che mappano i cerchi di Uncle Bob:
Domain Layer (centro)
È il cuore dell'applicazione. Contiene solo codice Dart puro, nessuna dipendenza da Flutter o da package esterni (http, firebase, ecc.).
- Entities: oggetti di business, le regole aziendali più generali. Es:
User,Product,Order. - Repository (abstract): interfacce che dichiarano come ottenere/salvare i dati. Es:
abstract class UserRepository { Future<User> getUser(String id); } - Use Cases: casi d'uso dell'applicazione. Ogni use case incapsula una singola operazione (es. GetUserProfile, CreateOrder). Chiamano i repository e orchestrano il flusso dati.
Data Layer (esterno al Domain)
Implementa le interfacce definite nel Domain e gestisce fonti dati esterne.
- Models: DTO e mapping da/verso JSON, API, database. Possono estendere o convertire le Entity.
- Data Sources: Remote (chiamate HTTP) e Local (SQLite, Hive, SharedPreferences).
- Repository Implementations: classi concrete che implementano i repository del Domain, coordinando data sources e mapping.
Presentation Layer (più esterno)
Gestisce UI e stato visuale. Usa Use Cases (o Controller/Bloc che a loro volta usano Use Cases), non i repository direttamente.
- Widgets / Screens: l'interfaccia utente.
- State management: BLoC, Cubit, Riverpod, Provider, ChangeNotifier — a scelta. La logica di presentazione comunica con i Use Cases.
Struttura delle cartelle
Una struttura tipica in Flutter:
lib/
├── core/ # errori, costanti, utils condivisi
├── data/
│ ├── datasources/ # remote, local
│ ├── models/
│ └── repositories/ # implementazioni
├── domain/
│ ├── entities/
│ ├── repositories/ # interfacce abstract
│ └── usecases/
├── presentation/
│ ├── bloc/ # o cubit, provider, ecc.
│ ├── screens/
│ └── widgets/
└── main.dartPuoi organizzare per tipo (tutti i repository insieme) o per feature (cartella auth/ con entities, usecases, repository, UI di quell'area). La guida ufficiale Flutter (Compass app) propone un mix: data/domain per tipo, presentation per feature.
Use Cases: il ponte tra UI e Domain
I Use Cases incapsulano una singola azione di business. Esempio: GetUserProfile riceve un UserRepository (iniettato), chiama repository.getUser(id) e ritorna il risultato. La UI (o un Bloc/Riverpod) invoca il Use Case, non il repository direttamente. Così:
- La logica di business resta riutilizzabile e testabile.
- Puoi cambiare l'implementazione del repository senza toccare la presentation.
- Ogni Use Case ha una responsabilità chiara (Single Responsibility).
Repository Pattern
Il Repository astrae l'origine dei dati. Il Domain definisce abstract class ProductRepository con metodi come getProducts(), addProduct(Product p). La Data Layer implementa ProductRepositoryImpl che può usare API REST, Firestore, cache locale — il Domain non lo sa. Questo permette di cambiare backend, aggiungere caching o mockare in test senza modificare il dominio.
Dependency Injection
Per rispettare la Dependency Rule, i Use Cases e i Controller ricevono i repository (e altre dipendenze) dall'esterno, tipicamente in main.dart o in un modulo di setup. In Flutter si usano spesso GetIt, Riverpod o Provider per iniettare le implementazioni concrete. Il Domain espone solo interfacce; il wiring avviene nello strato più esterno.
Integrazione con Riverpod e BLoC
Clean Architecture non prescrive un particolare state manager. Puoi usare Riverpod definendo provider che dipendono dai Use Cases; o BLoC con Cubit che riceve Use Cases nel costruttore. La Presentation Layer resta separata: i widget leggono lo stato da Bloc/Riverpod, che a loro volta chiamano Use Cases. Il flusso è: UI → Bloc/Provider → Use Case → Repository (interface) → Repository Impl → Data Source.
Quando usare la Clean Architecture
- App complesse con molte feature, team multipli, previsione di crescita.
- Logica di business non banale che deve essere testata in isolamento.
- Piattaforme multiple (mobile + web + backend) che condividono la stessa logica.
- Frequenti cambi di backend (API, database, cache) senza riscrivere l'app.
Quando evitarla (o semplificarla)
Per app piccole, proof-of-concept o progetti senza previsione di scala, la Clean Architecture completa può essere overkill. Troppi layer e file per poche schermate creano complessità inutile. In questi casi è più pragmatico:
- Organizzare per cartelle base (screens, models, services/widgets).
- Usare BLoC o Riverpod con repository semplificati, senza necessariamente un layer Domain dedicato.
- Introduire Use Cases e separazione rigida solo quando il progetto cresce e la manutenibilità diventa un problema.
Conclusione
La Clean Architecture in Flutter offre un modello solido per app scalabili e manutenibili: Domain puro, Data che implementa le interfacce, Presentation che usa Use Cases. La chiave è la Dependency Rule e l'uso coerente di interfacce e dependency injection.
Non è obbligatoria per ogni progetto: per app piccole può essere eccessiva. L'importante è applicare i principi in modo proporzionato — separazione delle responsabilità, testabilità, indipendenza dai dettagli — e adattarli al contesto. Come ricorda la documentazione Flutter: "Regardless of how you answer these questions, the principles in this guide will help you write scalable Flutter apps."
Sulla gestione dello stato, confronta Riverpod e BLoC. Per il rilascio in produzione, vedi ambienti, flavor e rilasci in Flutter.

Articoli correlati

Gestione dello stato
Riverpod vs BLoC: cos'è, vantaggi e differenze
15 febbraio 2026 · 7 min di lettura

DevOps e rilasci
Ambienti, flavor e rilasci Flutter: setup enterprise
15 febbraio 2026 · 6 min di lettura

Sicurezza
Sicurezza in Flutter: token, storage e protezione dati
15 febbraio 2026 · 5 min di lettura
Hai un progetto in mente?
Raccontami obiettivi e tempi: ti rispondo con una proposta concreta, una roadmap e una stima economica.