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

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.
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
```
.
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.
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.
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.
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.
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.
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.
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.
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/
```
.
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.
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.

Default single-package tree

├── analysis_options.yaml   # the lint safety net (see lint-and-style-config)
├── pubspec.yaml            # pubspec.lock is COMMITTED — this is an app
├── lib/
│   ├── main.dart           # thin entry: runs bootstrap(). Nothing else.
│   ├── bootstrap.dart      # composition root: build infra, override providers, error net, runApp (see app-startup-and-bootstrap)
│   ├── app.dart            # MaterialApp.router, theme wiring, ProviderScope child
│   ├── core/               # PURE foundation, NO Flutter: value objects, Result/Failure, Clock seam, calculators
│   ├── data/               # shared data layer: Drift db, DAOs, repositories, row→model mappers
│   ├── services/           # injectable side-effect ports + impls; native/ quarantines MethodChannel
│   │   └── native/
│   ├── routing/            # the single go_router config, typed routes, guards (see navigation-and-routing)
│   ├── theme/              # ThemeExtension token sets, ColorScheme (see design-system-structure)
│   ├── l10n/               # generated AppLocalizations + ARB (see i18n-rtl-l10n)
│   └── features/           # BY FEATURE — one folder per surface
│       └── orders/
│           ├── presentation/
│           │   ├── orders_screen.dart
│           │   ├── orders_notifier.dart   # the ViewModel: a Riverpod Notifier (see state-management-riverpod)
│           │   └── widgets/
│           │       └── order_tile.dart
│           ├── application/               # OPTIONAL: use-cases spanning repositories
│           └── domain/                    # OPTIONAL: feature-local models
├── test/                   # mirrors lib/ 1:1
└── integration_test/       # only what unit/widget tests cannot reach

A feature's

data/

folder is usually ABSENT — features read the shared repositories in

lib/data/

. See

references/single-package-layout.md

for the full tree and the deliberately-absent list.

Placement decision procedure

dart

// Q: where does OrderRepository go?  A: it owns DB failure → lib/data/
class OrderRepository {
  OrderRepository(this._db);
  final AppDatabase _db;

  // Rows never escape this class; the UI is owed a value type, not a raw row.
  Future<List<Order>> loadAll() async {
    final rows = await _db.selectOrders();          // package:drift confined here
    return rows.map(Order.fromRow).toList();
  }
}

dart

// Q: where does PaymentChannel go?  A: it constructs a MethodChannel → lib/services/native/
// One `grep -rn MethodChannel lib/` outside services/native/ is a review failure.
class PaymentChannel {
  static const _channel = MethodChannel('app/payment');
  Future<bool> canPay() async => await _channel.invokeMethod('canPay') ?? false;
}

A widget or model reused by 2+ features moves DOWN to
```
lib/core/
```
(pure) or
```
lib/data/
```
, or up to a named shared-widget home — never into one feature's folder that another then imports.
A new surface gets its own folder under
```
lib/features/
```
even for a single file — consistency beats saving a line. Register its route into
```
routing/
```
(see
```
scaffold-feature-module
```
,
```
navigation-and-routing
```
).
Read platform/accessibility state (
```
MediaQuery.textScalerOf
```
) in the widget at build time, not via a helper file or a provider —
```
MediaQuery
```
is already reactive. App state via Riverpod; platform state via
```
BuildContext
```
. See
```
accessibility-as-code
```
.

When to extract a package (multi-package / workspace)

Extract a pure-Dart package the moment a body of logic satisfies all of: it is genuinely UI-free, it is worth testing headlessly in milliseconds, and the "imports no Flutter" guarantee is worth making a build error. Typical: money/units math, entities, deterministic algorithms. Below that bar it stays in

lib/core/

yaml

# packages/domain_core/pubspec.yaml — the manifest IS the purity audit
name: domain_core          # a GENERIC name — never the brand, so a rename never churns the core
publish_to: none
resolution: workspace       # member of the root workspace (modern successor to path:/overrides)
environment:
  sdk: ^3.6.0
dependencies:
  meta: ^1.15.0            # the ONLY dependency. No flutter, no dart:io, no dart:ui, no clock.
dev_dependencies:
  test: ^1.25.0            # plain `dart test` — NOT flutter_test

The root

pubspec.yaml

lists members under

workspace:

; there is one committed

pubspec.lock

at the root. The public barrel

lib/domain_core.dart

exports the stable surface; internals stay under

lib/src/

. Full ritual, dependency matrix, and gates in

references/workspace-and-packages.md

When multi-package (workspace) only. Everything in this section —
packages/
,
resolution: workspace
, barrels,
lib/src/
— applies solely once you have decided to split. A single-package app does none of it.

Anti-patterns

Splitting the shared foundation feature-first (
```
orders/
```
,
```
settings/
```
each with their own DB + repositories). The entity graph is shared; keep repositories/DB in
```
lib/data/
```
and pure types in
```
lib/core/
```
. Feature-first applies inside
```
lib/features/
```
, not to the data graph.
One feature folder importing another feature folder. It couples two surfaces that should meet only via
```
core
```
/
```
data
```
/
```
services
```
or a route. Lift the shared piece down, or navigate.
utils/
,
helpers/
,
common/
,
misc/
, or a grab-bag
shared/
. A junk drawer; every candidate belongs beside its owner or as a named type. (
```
core/
```
is fine — it is the named pure-foundation layer.)
Barrels or
lib/src/
in the single app package. No external importer justifies them; they add analyzer cost and circular-import risk.
```
lib/src/
```
is a PACKAGE convention only.
Constructing a
MethodChannel
inside a widget or repository. It cannot be faked and cannot be found in review. Quarantine it in
```
services/native/
```
.
Adding
flutter
,
dart:io
, or
DateTime.now()
to
lib/core/
or a pure core package. It destroys the compile firewall and the headless test tier; inject the
```
Clock
```
(
```
package:clock
```
) and seed instead.
path:
+
dependency_overrides
instead of
resolution: workspace
. Defeats single-context resolution and hides the version clashes a workspace exists to surface.
Naming the core package after the brand (
```
myapp_core
```
). A future rename churns every import. Name it for what it holds (
```
domain_core
```
,
```
money
```
).
A speculative dependency "for later." An unused edge muddies the audit and is a review reject.
Mixing
package:
and relative imports. Two import paths → two runtime types for one class.

Definition of done

Default is a single Flutter package;
```
pubspec.lock
```
committed; no
```
packages/
```
/Melos/workspace unless a pure body of logic earned it.

Top level is the shared foundation (

core/ data/ services/ routing/ theme/ l10n/

); features live under

lib/features/<feature>/

;

main.dart

only runs

bootstrap()

No feature folder imports another feature folder; sharing happens via
```
core
```
/
```
data
```
/
```
services
```
or a route.
Every class sits in the layer whose failure it owns;
```
MethodChannel
```
only in
```
services/native/
```
; rows never escape
```
data/
```
; pure foundation and the Clock seam in
```
core/
```
.
No
```
utils/
```
/
```
helpers/
```
/
```
common/
```
/
```
misc/
```
/grab-bag-
```
shared/
```
folder anywhere;
```
core/
```
is present as the named pure-foundation layer, not a catch-all.
No
```
lib/src/
```
or barrel in the app package (they are PACKAGE conventions only).
```
test/
```
mirrors
```
lib/
```
1:1; shared fakes in
```
test/support/
```
, cross-cutting checks in
```
test/policy/
```
.
One primary declaration per file, filename = declaration in
```
snake_case
```
(sealed hierarchy the sole exception);
```
always_use_package_imports
```
.
If a package was extracted: it is a
```
resolution: workspace
```
member, generically named, with one public barrel over
```
lib/src/
```
; a pure core declares
```
meta
```
only (no
```
flutter
```
/
```
dart:io
```
/
```
dart:ui
```
/clock); one root
```
pubspec.lock
```
.
Dependency graph points downward only; no cross-package
```
lib/src/
```
import; deps are audit-minimal with no unused edge.

scripts/check_structure.sh

and

scripts/check_import_boundaries.sh

pass.

Related skills

```
flutter-architecture
```
— the layered MVVM this folder shape realises (features-as-folders, foundations-as-packages, single write-path repositories); it keeps layer semantics and references this tree.
```
scaffold-feature-module
```
— the fixed anatomy of one
```
lib/features/<feature>/
```
folder (View + 1:1
```
<feature>_notifier.dart
```
Notifier + scoped providers) and how it registers a route.
```
app-startup-and-bootstrap
```
— owns
```
main.dart
```
/
```
bootstrap.dart
```
, the composition root ordering, and the global error net.
```
navigation-and-routing
```
— owns
```
lib/routing/
```
(go_router config, typed routes, guards) that features register into.
```
naming-conventions
```
— the role suffixes (
```
Screen
```
/
```
Notifier
```
/
```
Repository
```
/
```
Service
```
/
```
Gateway
```
) and the file=primary-declaration rule referenced above.
```
dependency-hygiene
```
— pubspec/lock mechanics, caret ranges, auditing a transitive tree before adding a dep.
```
codegen-and-toolchain
```
— per-package
```
build.yaml
```
scoping and the commit-vs-gitignore decision for generated code.

lint-and-style-config

— the

analysis_options.yaml

that promotes

always_use_package_imports

and silent-failure lints to errors.

```
service-boundary-and-native
```
— the
```
services/native/
```
MethodChannel quarantine, the injectable Service/Gateway ports, and the
```
Clock
```
-via-
```
clockProvider
```
time seam.
```
value-objects-money-and-units
```
— the canonical resident of
```
lib/core/
```
or an extracted pure-Dart core.

References

Dart package layout: https://dart.dev/tools/pub/package-layout
Dart & Flutter workspaces (
```
resolution: workspace
```
): https://dart.dev/tools/pub/workspaces
Effective Dart — libraries & imports: https://dart.dev/effective-dart/usage#libraries
pubspec format: https://dart.dev/tools/pub/pubspec
Flutter architecture recommendations: https://docs.flutter.dev/app-architecture

project-structure-and-packages

NPX Install

Tags

SKILL.md Content