# 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](./directory-structure.md) | Module organization and file layout | Filled |
| [State Management](./state-management.md) | BLoC/Cubit, repository pattern, DI | Filled |
| [Error Handling](./error-handling.md) | ApiProblem, error parsing, l10n mapping | Filled |
| [Quality Guidelines](./quality-guidelines.md) | Code standards, forbidden patterns | Filled |
| [Logging Guidelines](./logging-guidelines.md) | 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**.