social-app/.trellis/spec/frontend/index.md

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	Module boundaries and placement rules
Component Guidelines	Widget composition, shared components, design system usage
Hook Guidelines (Bloc/Cubit State Flows)	Flutter state flow conventions using Bloc/Cubit
Type Safety	DTO parsing, API boundary typing, protocol alignment
Quality Guidelines	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.