# BuyerKiosk Live Flutter Constitution ## Core Principles ### Clean Architecture & Riverpod Ownership Features map to the established layers (`core/`, `data/`, `domain/`, `presentation/`, `router/`) with stateful logic in Riverpod `AsyncNotifier` providers, domain entities as plain Equatable classes, data models as abstract Freezed classes, and navigation handled by GoRouter auth redirects. Widgets stay declarative; side effects and I/O are owned by providers and services. ### Backend Contract Fidelity & Network Safety All API interactions flow through `api_client.dart` and its interceptors, using POST requests with the API key attached per backend contract. Mappers must normalize string-number responses, honor dev/prod base URLs in `api_constants.dart`, and keep Ably/FCM channel names consistent with constants. Contract changes require updated fixtures and tests before rollout. ### Auth, Permissions, and Secrets Integrity API keys live only in secure storage; a 403 response clears cached keys. Routes and UI must check permission providers (`canAccess`/`isOwner`) before rendering protected screens, with owner-only configuration guarded. Secrets, keys, and tokens are never logged or persisted outside secure storage. ### Testing Discipline for Riverpod & Navigation Follow the Flutter testing pyramid: unit tests for providers, mappers, and utils; widget tests for screens, navigation, and error/loading states; targeted integration tests for auth/installation and other critical user journeys. New or changed providers, mappers, and navigation guards require failing tests before implementation and passing `flutter test` before merge. ### UX Consistency & Resilience UI follows `STYLE_GUIDE.md` for color/typography, uses shared loading/error/empty widgets, and preserves 60fps responsiveness. Real-time features degrade gracefully when Ably/FCM are unavailable, with clear error and retry states. Forms and mutations surface validation errors inline without blocking the main thread. ## Tech Stack & Delivery Constraints - Flutter 3.38.3/Dart 3.10.1 with Riverpod 3.x AsyncNotifier, Freezed 3.x (abstract models), Equatable entities, GoRouter 17.x navigation. - Dio with interceptors is the only HTTP entry point; base URLs and endpoints live in `lib/core/constants/*_constants.dart`. - Push and real-time features use Ably + FCM; channel/type naming must match `push_notification_constants.dart` and `ably_constants.dart`. - Build_runner is required after model/schema changes (`dart run build_runner build --delete-conflicting-outputs`); generated code should be checked in when applicable to the workflow. - Assets and brand usage align with `STYLE_GUIDE.md`; new assets belong under `assets/images/` with references added to `pubspec.yaml`. ## Development Workflow & Quality Gates - New work starts with a feature spec and implementation plan that pass the Constitution Check (architecture fit, API contract impact, auth/permission mapping, UX/error handling, and testing strategy). - User stories must be independently testable and mapped to required permission levels and backend endpoints. - Any network or data change ships with contract fixtures and mapper tests; navigation changes include widget tests for redirects and guards. - PRs document how principles are satisfied, list affected endpoints, and cite test coverage (`flutter test` at minimum). - Deployment readiness requires no critical analyzer issues, passing tests, and documented error/empty/loading states for the touched screens. ## Governance - This constitution supersedes other practice guides for engineering decisions; conflicts resolve in favor of this document. - Amendments require a written rationale, updated Sync Impact Report, and version bump following semantic rules (MAJOR for breaking/removal, MINOR for new principles/sections, PATCH for clarifications). - Reviewers enforce compliance: check architecture fit, contract fidelity, auth/permission protections, UX resilience, and required tests before approval. - Runtime guidance for coding patterns and APIs lives in `CLAUDE.md`, `STYLE_GUIDE.md`, and testing guides; deviations are documented in PRs. **Version**: 1.0.0 | **Ratified**: 2025-12-06 | **Last Amended**: 2025-12-06