Flutter Dart project structure and modules

Place code by responsibility so a growing project remains easy to find and change.

Chapter goal: Place code by responsibility so a growing project remains easy to find and change.

Simple explanation

Project structure is a labelled set of drawers. Related code lives together so a developer can find and change it safely.

In Flutter Dart, this chapter is about separating screens, data, business rules, and external services. Start with the idea above. Then connect each symbol to a value or action in the example.

Do not try to remember every symbol. First ask what data the program has, what it does with that data, and what result it creates. Technical words become easier when you connect them to those three questions.

Why this topic is important

Good folders cannot repair unclear responsibilities, but clear modules stop unrelated code from becoming tangled. In Flutter Dart, the syntax may look different from other languages, but the thinking skill transfers: name the data, choose the right operation, and make the next step obvious.

When to use it

Introduce structure when a project has several features, screens, services, or developers.

Example code

// pricing.dart — pure calculation, no UI code
int calculateTotal(int price, int quantity) => price * quantity;

// main.dart — display logic only
void main() {
  final total = calculateTotal(5, 3);
  print('Total: $total');
}

Line-by-line explanation

• // pricing.dart — pure calculation, no UI code — This line supports one focused piece of application logic. Read it together with the block directly around it.
• int calculateTotal(int price, int quantity) => price * quantity; — This stores or updates quantity). The value on the right is worked out first, then saved under that name.
• // main.dart — display logic only — This line supports one focused piece of application logic. Read it together with the block directly around it.
• void main() { — This line supports one focused piece of application logic. Read it together with the block directly around it.
• final total = calculateTotal(5, 3); — This stores or updates total. The value on the right is worked out first, then saved under that name.
• print('Total: $total'); — This is the visible output line. It shows the final value after the earlier work is complete.

What the output means

Total: 15

The output is evidence that the program followed the instructions. If your result is different, read from the first line and write down how each value changes. That is debugging, not failure.

Mistake example

// pricing.dart — pure calculation, no UI code
int calculateTotal(int price, int quantity) => price * quantity;

// main.dart — display logic only
void main() {
  final total = null; // business rules are placed inside UI or entry-point code
  print('Total: $total');
}

This version intentionally shows how business rules are placed inside UI or entry-point code. The changed assignment stores a missing value, or a required line is removed, so later code cannot complete its job safely.

Fixed version

// pricing.dart — pure calculation, no UI code
int calculateTotal(int price, int quantity) => price * quantity;

// main.dart — display logic only
void main() {
  final total = calculateTotal(5, 3);
  print('Total: $total');
}

The corrected version restores the real value or required operation. It fixes the chapter-specific problem: business rules are placed inside UI or entry-point code.

Common mistakes

• Creating many folders before the project needs them.
• Putting business rules inside UI code.
• Allowing every module to import every other module.

Warning: Change one part at a time. If you change many lines together, it becomes harder to learn which change caused the result.

Real use cases

• Organize a feature by screen, model, and service.
• Separate API code from display code.
• Make one module independently testable.

Practice exercise

1. Move one function into its own named file or module.
2. Identify one piece of logic that should not depend on UI code.
3. Explain which file or module owns each responsibility.

Tip: If the exercise feels too large, complete only steps 1 to 3. Small working code teaches more than a large unfinished project.

Mini quiz

1. Match the term to its meaning: "module" versus "responsibility".
2. Choose the correct syntax: which import pattern suggests two unrelated modules are tangled together?
3. Explain a real scenario: why would one giant file slow down a team of three developers?

How to read AI-generated code

Do not copy AI code first. Read it like a detective. Find the data, follow the changes, and locate the final output. Ask AI to explain a line only after you have made your own guess.

• What data goes in?
• What values are stored?
• What calculation or decision happens?
• What is printed, displayed, saved, or returned?
• What can go wrong?
• Can you rename one value and still explain the code?

Flutter reading check

Find the widget tree first. Then find which values can change, where setState is called, which callback handles the button or TextField, and where navigation or async data enters the screen.

Before you move on

• I can explain this topic in my own words.
• I can read the small example without AI.
• I can change the example and predict the new result.
• I can find and fix one simple mistake.
• I can name one real project that uses this idea.

Next topic

Next, learn state management. Before opening it, explain this chapter out loud in under one minute.