project-structure-and-packages

Project structure & packages

The layout is a feedback loop, not decoration: structure exists so that "what imports Flutter?", "what has no test?", and "does this feature reach into another?" are answerable by grep and ls, not by trust. Default to one Flutter package (the app), organised feature-first under lib/features/ over a shared foundation. Reach for a second, pure-Dart package only when a body of logic earns the isolation. A pubspec.yaml is the audit artifact — a package cannot import what it does not declare, so the dependency list is the layer boundary.

This skill OWNS the physical directory tree (D1). Other skills reference it rather than drawing their own.

Read the reference for the task at hand:

• references/single-package-layout.md — the default one-package feature-first tree, the shared-foundation folders, placement-by-failure, the deliberately-absent list.
• references/layering-and-dependencies.md — the downward-only DAG, feature isolation, pubspec-as-audit, the compile-firewall insight.
• references/workspace-and-packages.md — when (and how) to extract a pure-Dart package: barrel-over-src, resolution: workspace, naming the core generically.

Run scripts/check_structure.sh and scripts/check_import_boundaries.sh before a PR. The purity check auto-detects only pure roots named *_core; a pure package with a plain generic name (money, scheduling) must be passed explicitly, e.g. PURE_DIR=packages/money scripts/check_import_boundaries.sh.

Non-negotiable rules

1. Single package by default. A small-to-medium app is one Flutter package; its pubspec.lock is committed (it is an app, not a library). Do not add packages/, Melos, or a Dart workspace until a body of pure logic genuinely earns isolation (see references/workspace-and-packages.md). Multiplying packages before there is anything to multiply buys nothing and costs days.
2. Feature-first inside lib/features/, over a shared foundation. Each screen/surface is a folder under lib/features/<feature>/ (presentation/ + <feature>_notifier.dart; optional application/, domain/, rarely data/). The cross-cutting foundation splits by technical role at the top level — core/ (pure), data/ (repositories + DB), services/ (side-effect ports), routing/, theme/, l10n/ — because those files serve every feature. main.dart is a thin entry that calls bootstrap(); bootstrap.dart is the composition root; app.dart builds MaterialApp.router.
3. No grab-bags, no unnamed nesting. There is no hard depth cap — feature-first naturally nests (features/orders/presentation/). The rule is that every folder has a named responsibility: no utils//helpers//common//misc/, no grab-bag shared/. core/ is the SANCTIONED pure-foundation home, not a junk drawer.
4. Place a class in the layer whose failure it owns. Talks to the DB → data/. Talks to a platform channel → services/native/. A pure value type / calculator / the Clock seam → core/ (or a feature's domain/ if truly feature-local). Everything else → the feature that renders it. This is a deterministic rule, not taste.
5. pubspec.yaml is the audit artifact — declare the audit-minimal dependency set. An unused dependency is a review reject: it muddies the claim the manifest makes. The narrowest dep list keeps each layer boundary provable by reading one file.
6. Dependencies point one way, downward only; features never import features. features → services/data → core. No lower layer imports an upper one; no shared code imports the composition root. A feature folder NEVER imports another feature folder — share via core/data/services or navigate by route (see navigation-and-routing). A cycle is a design defect: the analyzer resolves the whole graph in one context, so an upward or cross-feature import is an error, not a runtime surprise.
7. A pure-Dart core depends on meta only — the missing Flutter import is a compile firewall. In-app, lib/core/ holds only pure foundation (value objects, Result/Failure, the Clock seam, calculators) and reads no wall clock. Time comes from package:clock's Clock (ambient clock, or a Clock param), never DateTime.now(), never a bespoke ClockService — see service-boundary-and-native. When such logic is extracted to a package, the empty-of-Flutter manifest makes a stray Widget or DateTime.now() a build error.
8. One public barrel over a private lib/src/ — for PACKAGES only. A shared package exposes exactly one library lib/<package>.dart that exports the stable surface; everything else lives under lib/src/, which no other package may import. The app package uses neither barrels nor lib/src/: it has no external importers, and barrels add analyzer cost plus circular-import risk for zero benefit.
9. No junk-drawer folders. No utils/, helpers/, common/, misc/, or a grab-bag shared/. A helper either lives beside the type it serves (a same-file extension) or is a named service/value type with a real home. core/ is explicitly NOT a junk drawer — it is the named pure-foundation layer.
10. Tests mirror lib/ 1:1. test/data/order_repository_test.dart for lib/data/order_repository.dart. "What has no test?" then reduces to a diff of two ls outputs. Cross-cutting assertions that belong to no single file get their own folder (test/policy/); shared fakes go in test/support/.
11. One primary declaration per file; filename = that declaration in snake_case. order_repository.dart holds OrderRepository. The one exception: a sealed hierarchy lives in a single file, because that file is the closed set the compiler enforces.
12. Package imports everywhere; never mix with relative. always_use_package_imports. Mixing package: and relative paths lets the same member resolve two ways, producing two distinct runtime types. Package imports also survive file moves and are greppable.