How to choose the best folder structure for new Flutter projects?

Hi Flutter Devs. If you have no idea or are confused about how to choose the best folder structure for your new Flutter projects, this is the blog that helps you to give the perfect clarification to yourself.

First of all, this is my 1st blog in my life. So, if you have any suggestions, let me know. I will definitely improve it, and I will give the best from my side for upcoming blogs. Thank you.

What is folder structure?

• In software development and project management, the folder structure is the hierarchical organization of files and folders inside the respective project.

• It helps organize the files and folders logically to make the project easier to understand, manage, and scale.

Why is folder structure important?

• Scalability: our files easily grow from 10 to 100 and from 100 to 1000. It leads us to get confused. Scalability means, if the project size increases, it should not be confused.

• Team Collaboration: The team can easily understand the project, like what the modules and features are, and what the theme of the project is efficiently.

• Readability: Anyone (even new joiners) can see which code is doing what by looking at the folder structure.

• Maintainability: When you revisit your project after 6 months or later, it’s easy to understand your project. (It’s a real point; it happened many times in my initial times. 😅)

• Industry standards: Most companies expect the projects to have a good folder structure. Because it helps to save time and cost and, most importantly, provides faster onboarding.

• Testing: A well-structured project helps to write and organize the test cases.

Ok, now see what the folder structures are mainly using.

Common Folder Structure for Flutter Projects:

1. Layered Architecture (Traditional / Layer-First)

2. Feature-First Architecture

3. Clean Architecture

4. Modular Architecture

5. Atomic design

6. Hybrid (Feature-First + Clean Architecture)

I. Layered folder structure (Traditional / Layer-First):

• In a layered folder structure, all files and folders are organized layer by layer, like business logic in one layer, UIs in one layer, and network calls and local databases in another layer.

• It is one of the beginner-friendly folder structures.

• Best use for MVP’s POC (Proof of Concepts)

• If the project size is increased, it will be harder to manage, and it is hard to scale.

• If needed, start converting it to another folder structure based on your requirement 😊

Example of layered folder structure in Flutter.

/lib
 ├── data/
 │     ├── providers/
 │     ├── models/
 │     └── repositories/
 ├── business/
 │     ├── bloc/
 │     └── cubit/
 ├── presentation/
 │     ├── screens/
 │     └── widgets/
 ├── core/
 │     ├── utils/
 │     └── theme/
 └── main.dart

Note:

• Under the (lib/data/datasource), the actual API calls will happen.

• Under the (lib/data/repositories), data serialization will happen.

• In “Layred Architecture”, there is no seperate “Domain layer” for testing which is “Sepeartion of Concerns“.

• Which menas there is no seperation of concerns.

---

II. Feature-First Architecture

• In feature-first, it should be organized or grouped by feature, not the same file name.

• Recommended for medium-size projects and MVPs (minimum viable products).

• Here, we can find the related files easily, and it's good for team projects.

• But here, UI logic and business logic will mix. So, it’s not very clean that much.

Example of a feature-first folder structure in Flutter.

/lib
 ├── features/
 │     ├── auth/
 │     │     ├── data/
 │     │     |     ├── providers/
 │     │     |     ├── models/
 │     │     |     └── repositories/
 │     │     ├── business/
 │     |     |     ├── bloc/
 │     |     |     └── cubit/
 │     │     └── presentation/
 |     |            ├── screens/
 │     |            └── widgets/
 │     ├── chat/ (same structure)
 │     └── profile/ (same structure)
 ├── common/
 │     ├── widgets/
 │     ├── utils/
 │     └── theme/
 └── main.dart

Note:

• In “Feature-first architecture” also, there is no seperate “Domain layer” for testing which is “Sepeartion of Concerns“.

• Which menas there is no seperation of concerns.

---

III. Clean Architecture

• In clean architecture, we organized the files and folders feature-wise with independent layers like data, business, and presentation.

• This folder structure allows us to separate the business logic from the UI logic, which is called separation of concerns. So, this folder structure gives massive flexibility to scale and test, and it’s easy to maintain as well.

• This is a little bit complex for new bees, but most of the small companies with small project teams are using this kind of folder architecture.

• If your project size is medium or large and you want it to be scalable and testable, I would like to suggest using the clean architecture folder structure.

Example of a clean architecture folder structure in Flutter.

/lib
 ├── features/
 │     ├── auth/
 │     │     ├── data/
 │     │     │     ├── providers/
 │     │     │     ├── models/
 │     │     │     └── repositories/
 │     │     ├── domain/
 │     │     │     ├── entities/
 │     │     │     └── repositories/
 │     │     └── presentation/
 │     │           ├── screens/
 │     │           ├── widgets/
 │     │           └── bloc/
 │     └── chat/ (same structure)
 ├── core/
 │     ├── error/
 │     ├── network/
 │     ├── usecases/
 │     ├── utils/
 │     └── theme/
 └── main.dart

Note:

• Clean Architecture, have a extra feather on its cap which is “Sepeartion of Concerns“.

• Other than that, Its have a “Domain and Data“ layer.

• Its helps us to test the APIs with mocked API responce in locally.

---

IV. Modular Architecture

• In modular architecture, the projects are organized by module.

• Each module is a small individual project (mini-project).

• Each module is a feature or feature-related.

• The modular architecture is for large, heavy projects with huge enterprise-level teams.

• If your project is small or medium, I won’t suggest you choose this folder structure. It’s only for big projects.

• Advanced techniques and knowledge to work on this kind of folder structure. So, it won’t set for new bees. But its not wrong to know. 😊

/lib
 ├── modules/
 │     ├── auth_module/
 │     │     ├── data/
 │     │     │     ├── providers/
 │     │     │     ├── models/
 │     │     │     └── repositories/
 │     │     ├── domain/
 │     │     │     ├── entities/
 │     │     │     └── repositories/
 │     │     └── presentation/
 │     │           ├── screens/
 │     │           ├── widgets/
 │     │           └── bloc/
 │     ├── chat_module/
 │     │     ├── data/
 │     │     │     ├── providers/
 │     │     │     ├── models/
 │     │     │     └── repositories/
 │     │     ├── domain/
 │     │     │     ├── entities/
 │     │     │     └── repositories/
 │     │     └── presentation/
 │     │           ├── screens/
 │     │           ├── widgets/
 │     │           └── bloc/
 │     ├── admin_module/ (same structure)
 ├── shared/
 │     ├── widgets/
 │     ├── utils/
 │     └── network/
 └── main.dart

---

V. Atomic Design

• This is a kind of UI folder structure not for business logic.

• It needs to combine any one of the folder structures.

• More helpful in designing reusable UI widgets.

• If the project contains a richer UI and wants to reuse it, I would like to recommend using this folder structure.

Atomic Design in Simple Words:

/lib
 ├── ui/
 │     ├── atoms/
 │     │     ├── custom_button.dart
 │     │     ├── custom_textfield.dart
 │     │     └── custom_icon.dart
 │
 │     ├── molecules/
 │     │     ├── login_form.dart
 │     │     ├── profile_header.dart
 │     │     └── chat_message_bubble.dart
 │
 │     ├── organisms/
 │     │     ├── chat_list.dart
 │     │     ├── profile_card.dart
 │     │     └── settings_section.dart
 │
 │     ├── templates/
 │     │     ├── login_template.dart
 │     │     ├── register_template.dart
 │     │     ├── profile_template.dart
 │     │     ├── chat_template.dart
 │     │     └── settings_template.dart
 │
 │     └── pages/
 │           ├── login_page.dart
 │           ├── register_page.dart
 │           ├── profile_page.dart
 │           ├── chat_page.dart
 │           └── settings_page.dart
 │
 ├── core/
 │     ├── theme/
 │     ├── utils/
 │     └── constants.dart
 │
 ├── data/
 │     ├── models/
 │     ├── datasources/
 │     └── repositories/
 │
 ├── domain/
 │     ├── entities/
 │     ├── usecases/
 │     └── repositories/
 │
 └── main.dart

Note:

• if your app follows a strict theme-based approach, many "atoms" can be skipped!

---

VI. Hybrid (Clean + Feature + Atomic)

• This is modern practice and a perfect combo for most of us (Including myself)

• It was grouped or organized by feature. + Each feature contains respective UI logic and business logic in a separate manner. + Each UI part has an atomic folder structure for reusable widgets and globally as well.

---

/lib
│
├── core/                         # Core, App-wide utilities, constants, themes, helpers
│    ├── constants/
│    ├── utils/
│    ├── theme/
│    └── network/
│
├── shared/                        # Atomic Design System (Globally shared UI)
│    └── ui/
│         ├── atoms/               # Buttons, Text, Icons
│         ├── molecules/           # Input Fields, ListTiles
│         ├── organisms/           # Cards, Forms, AppBars
│         ├── templates/           # Layouts without data
│         └── pages/               # Highly reusable pages/screens
│
├── features/
│    ├── login/
│    │    ├── data/
│    │    │    ├── datasources/
│    │    │    ├── models/
│    │    │    ├── repositories/
│    │    │    └── login_api_provider.dart
│    │    │
│    │    ├── domain/
│    │    │    ├── entities/
│    │    │    ├── repositories/
│    │    │    └── usecases/
│    │    │
│    │    └── presentation/
│    │         ├── bloc/
│    │         │    ├── login_bloc.dart
│    │         │    ├── login_event.dart
│    │         │    └── login_state.dart
│    │         │
│    │         ├── screens/
│    │         │    ├── login_screen.dart
│    │         │    ├── forgot_password_screen.dart
│    │         │    └── otp_screen.dart
│    │         │
│    │         └── widgets/
│    │              ├── login_form.dart
│    │              ├── password_field.dart
│    │              └── social_login_buttons.dart
│    │
│    ├── profile/
│    │    ├── data/
│    │    │    ├── datasources/
│    │    │    ├── models/
│    │    │    ├── repositories/
│    │    │    └── profile_api_provider.dart
│    │    │
│    │    ├── domain/
│    │    │    ├── entities/
│    │    │    ├── repositories/
│    │    │    └── usecases/
│    │    │
│    │    └── presentation/
│    │         ├── bloc/
│    │         ├── screens/
│    │         └── widgets/
│    │
│    ├── settings/
│    │    ├── data/
│    │    ├── domain/
│    │    └── presentation/
│    │         ├── bloc/
│    │         ├── screens/
│    │         └── widgets/
│
│    └── comment/
│         ├── data/
│         ├── domain/
│         └── presentation/
│              ├── bloc/
│              ├── screens/
│              └── widgets/
│
├── app.dart
├── routes.dart
└── main.dart

---

Decision Flowchart for Picking the Folder Structure:

Are you building a small / prototype app?
   └── Yes --> Layered is enough

Are you building a medium size app alone or small team?
   └── Yes --> Feature-First

Are you building a scalable production app with future in mind?
   └── Yes --> Hybrid (Feature + Clean) is recommended

Are you building a very big app with many independent teams working on features?
   └── Yes --> Modular + Clean

Are you focusing mainly on reusable UI components (like building a design system)?
   └── Yes --> Atomic Design (only for UI)

---

Conclusion:

Ok, my dear Flutter devs, I hope you get some sparks 😃. Even the atomic folder structure is totally brand new for me. So what I planned is I will recreate the WhatsApp UI by using the atomic folder structure. I have more queries about how it will be practical; I will learn more things and eagerly share those things with you. So keep your hands dirty because in the next blog I will share my code flow along with the git repo.

Meanwhile, if you have any doubts, comment to me; I will definitely clear your doubts, and if you learn new things from my blog, hit the like button; it motivates me to write more blogs like this.

Thank you 😊