social-app/.trellis/spec/frontend/directory-structure.md

Directory Structure

How frontend (Flutter) code is organized in this repository.

---

Practical Conventions

1. apps/lib/main.dart is the single root entry file.
2. Keep second-level folders fixed to: app/, core/, data/, features/, shared/, l10n/.
3. Put feature business code under features/<feature>/...; keep cross-feature infra/protocol in core/ and shared infra in data/.
4. Shared reusable UI belongs to shared/widgets/**, not duplicated under each feature.

---

Real File Path Examples

• App bootstrap and routing composition:
  • apps/lib/main.dart
  • apps/lib/app/app.dart
  • apps/lib/app/router/app_router.dart
• Shared infrastructure (non-feature business):
  • apps/lib/data/network/api_client.dart
  • apps/lib/data/cache/cache_store.dart
  • apps/lib/core/theme/app_theme.dart
• Feature-bounded implementation:
  • apps/lib/features/todo/data/apis/todo_api.dart
  • apps/lib/features/todo/data/repositories/todo_repository.dart
  • apps/lib/features/auth/presentation/bloc/auth_bloc.dart

---

Placement Checklist (before adding a file)

1. Does this logic belong to exactly one feature flow?
   • Yes -> features/<feature>/...
2. Is it cross-feature protocol/orchestration (auth/session/notification/ui schema)?
   • Yes -> core/**
3. Is it shared storage/network/cache infra?
   • Yes -> data/**
4. Is it reusable widget/presentation helper with no feature business orchestration?
   • Yes -> shared/widgets/** (or shared/forms/**)

---

Anti-patterns (with evidence)

• Creating feature business repositories/models under shared apps/lib/data/**.
  • Existing correct pattern is feature-local repositories under apps/lib/features/**/data/repositories/.
• Letting UI code bypass repositories for consistency-sensitive data flow.
  • Correct references: apps/lib/features/todo/data/repositories/todo_repository.dart, apps/lib/features/messages/data/repositories/inbox_repository.dart.
• Deep redundant nesting without clear ownership.
  • Current tree generally keeps flat-by-concern organization (e.g., data/apis, data/repositories, presentation/screens, presentation/widgets).

---

Uncertainties / Gaps

• Some modules blend domain-specific and infrastructure concerns (for example, notification rewrite boundaries) and rely on AGENTS rules rather than strict automated folder enforcement.
• No script currently validates folder placement rules automatically; enforcement is mostly review + convention.