eryao/.trellis/spec/frontend/index.md

Flutter App Development Guidelines

Best practices for Flutter app development in this project.

---

Overview

This directory contains guidelines for Flutter app development. Fill in each file with your project's specific conventions.

---

Guidelines Index

Guide	Description	Status
Directory Structure	Module organization and file layout	Filled
State Management	BLoC/Cubit, repository pattern, DI	Filled
Error Handling	ApiProblem, error parsing, l10n mapping	Filled
Quality Guidelines	Code standards, forbidden patterns	Filled
Logging Guidelines	Structured logging, log levels	Filled

---

How These Guidelines Were Filled

Each guideline file was populated based on:

1. Existing codebase patterns from apps/lib/
2. AGENTS.md rules from apps/AGENTS.md
3. Real code examples from features/auth/, core/logging/, etc.

---

Quick Start

Directory Structure

• Feature modules: features/<feature>/data/ + features/<feature>/presentation/
• Core infrastructure: core/ (cross-feature)
• Shared widgets: shared/widgets/
• Data layer: data/ (infrastructure only, not feature repositories)

State Management

• Pattern: ChangeNotifier + immutable state
• State: Use copyWith pattern
• DI: Singleton blocs/repositories via ServiceLocator

Error Handling

• Format: RFC 7807 (ApiProblem)
• Mapping: Error code → l10n key
• Global: 401 handled via AuthBloc.handleUnauthorized401()

Logging

• Library: Custom Logger class
• Module path: features.<feature>.<component>
• Error: Always log with error, stackTrace, message
• Forbidden: PII, tokens, passwords

Quality

• Colors: Semantic colors from Theme.of(context).colorScheme
• Spacing: Use AppSpacing / AppRadius tokens
• Tests: Unit, widget, integration tests for critical flows

---

Key Principles

Layer Boundaries

1. Presentation → Repository (via interface)
2. Repository → Core/Infrastructure (via DI)
3. Core → Nothing (foundation layer)
4. Shared → Core (for utilities)
5. Feature → Core + Shared (for cross-cutting concerns)

Data Layer Boundary (Must)

• data/ = infrastructure abstractions (cache/network/storage)
• features/<feature>/data/ = feature business repositories/models
• NEVER mix these boundaries

Error Code Contract (Must)

• Single source of truth: docs/protocols/common/http-error-codes.md
• Frontend mapping: Error code → l10n key
• Backend updates → Frontend mapping updates (must stay in sync)

---

Common Anti-Patterns

❌ Do NOT:

1. Hardcode colors (Color(0xFF...), Colors.blue)
2. Hardcode spacing (Padding(padding: EdgeInsets.all(16.0)))
3. Place feature repositories in shared data/
4. Import feature data layer from other features
5. Create new second-level directories under lib/
6. Use print() instead of Logger
7. Log PII/tokens/passwords
8. Catch exceptions without logging

---

Architecture Decision Records

When making architectural decisions, document:

1. Context: What problem are we solving?
2. Decision: What approach did we choose?
3. Consequences: What are the trade-offs?

Add new ADRs to this directory if needed.

---

Language: All documentation should be written in English.