# 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.