conventions

Documentation Index

Read before writing or modifying any code:

• docs/reference/architecture.md — core folder map, layer patterns, naming, DI, error flow, design system, testing
• docs/explanation/end-goal.md — project vision and guiding principles

Read on demand:

• docs/how-to/contributing.md — contributor workflow and git hooks
• docs/how-to/add-feature-template.md — full folder tree, empty class skeletons, DI wiring, and forbidden-pattern checklist for scaffolding a new feature
• docs/how-to/add-usecase.md — create a use case class and register it in injection_container.dart
• docs/how-to/design-screen-state.md — business-logic naming for events and states, retry context rules, screen rendering pattern; use the jokes feature as the reference
• docs/how-to/review-code.md — when asked to review, audit, or check generated code; run through the full checklist and report ✅/❌ per section
• docs/how-to/change-app-id.md — when asked to change the application ID or bundle identifier; covers Android (build.gradle.kts + MainActivity.kt package path) and iOS (project.pbxproj), with Xcode manual steps and provisioning notes
• docs/how-to/rename-app.md — when asked to rename the app; covers display name, package name, and all files that reference the old name
• docs/how-to/connect-firebase.md — when connecting an app to Firebase; covers checking/installing the Firebase + FlutterFire CLIs, running flutterfire configure, per-app firebase_core, main.dart init, Android Gradle plugin, iOS deployment target (15.0+), and the Xcode GoogleService-Info.plist registration check
• docs/tutorials/solid-principles.md — how SOLID principles are applied across all layers; useful when designing new classes or reviewing layer boundaries
• docs/tutorials/design-patterns-and-concepts.md — design patterns used in this codebase (Singleton, Repository, DTO, Either, Sealed Classes, Strategy, and more)
• docs/explanation/ai-agents.md — per-agent install and usage
• Release workflow — see release.mdc in this rules folder