# Frontend Development Guidelines (Flutter App)

> Scope: `apps/**` (Flutter mobile app). This index links to project-grounded guidelines only.

---

## Practical Conventions (Quick Rules)

1. Keep `apps/lib` second-level layout stable: `app/`, `core/`, `data/`, `features/`, `shared/`, `l10n/`.
2. Use feature-bounded modules under `features/<domain>/...` and keep shared infra in `data/` + `core/`.
3. Parse backend errors as RFC7807 (`code`/`params`) and keep mapping synced with protocol docs.
4. Prefer shared UI widgets (`shared/widgets/**`) and design tokens (`AppSpacing`/`AppRadius` + `Theme.colorScheme`).

---

## Repository Evidence (entry files to read first)

- `apps/lib/main.dart` - bootstrap entry (`configureDependencies`, `Env.init`, `runApp`)
- `apps/lib/app/app.dart` - app shell + theme + auth lifecycle orchestration
- `apps/lib/app/di/injection.dart` - DI registration and cross-feature singleton wiring
- `apps/AGENTS.md` - enforced frontend domain rules

## Real File Path Examples

- `apps/lib/main.dart`
- `apps/lib/app/di/injection.dart`
- `apps/lib/data/network/error_code_mapper.dart`

---

## Guidelines Index

| Guide | Focus |
|---|---|
| [Directory Structure](./directory-structure.md) | Module boundaries and placement rules |
| [Component Guidelines](./component-guidelines.md) | Widget composition, shared components, design system usage |
| [Hook Guidelines (Bloc/Cubit State Flows)](./hook-guidelines.md) | Flutter state flow conventions using Bloc/Cubit |
| [Type Safety](./type-safety.md) | DTO parsing, API boundary typing, protocol alignment |
| [Quality Guidelines](./quality-guidelines.md) | Lint/test/logging expectations and review checklist |

---

## Anti-patterns Observed (do not copy)

- Silent/weak failure branches still exist in some paths and should not be expanded:
  - `apps/lib/app/di/injection.dart` (`setRefreshCallback` catch branch returns `false` without logging)
  - `apps/lib/core/chat/ag_ui_service.dart` (malformed SSE payload catch branch intentionally ignores parse error)
- Directly hardcoding API contract assumptions outside protocol docs/mappers leads to drift:
  - Keep `docs/protocols/common/http-error-codes.md` and `apps/lib/data/network/error_code_mapper.dart` synchronized.

---

## Uncertainties / Gaps

- The frontend workflow doc (`.trellis/workflow.md`) still uses the historical filename `hook-guidelines.md`; this index keeps the filename for compatibility while the content is Flutter Bloc/Cubit specific.
- There is no repository-level automated check yet proving every protocol-code change updates all three sides (backend + protocol docs + frontend mapping); this is currently review-driven.