social-app/apps/AGENTS.md

Apps Domain Rules

This file governs apps/** (Flutter). Keep rules strict, short, and reusable.

Scope & Precedence

• Inherits root AGENTS.md and workspace runtime rules.
• If rules conflict, apply the stricter one.
• Visual language source of truth: apps/rules/visual_design_language.md.

Flutter Directory Contract (Must)

• apps/lib only allows these second-level directories: app/, core/, data/, features/, shared/, l10n/.
• apps/lib/main.dart is the only allowed root entry file.
• Do not add new second-level directories under apps/lib without explicit approval.

Module Responsibilities (Must)

• app/: app bootstrap, DI wiring, global lifecycle orchestration, router composition.
• core/: cross-feature business primitives/protocols/orchestrators (no feature-specific page logic).
• data/: shared infrastructure only (cache/network/storage/adapters), not feature business repositories/models.
• features/: user-facing bounded feature modules with clear product ownership.
• shared/: reusable UI widgets and presentation helpers without feature business orchestration.
• Cross-cutting capabilities (e.g. notification orchestration, UI schema protocol) must live in core/ + shared/, not under features/.

Placement Rules (Must)

• Put code in features/ only when it belongs to one bounded product capability/screen flow.
• Put code in core/ when it is cross-feature protocol, policy, or orchestration that does not belong to one feature.
• Put reusable UI renderers in shared/widgets/; they must not contain feature-only business orchestration.
• In feature data layers, use semantic subfolders: data/apis/, data/repositories/, data/services/, data/models/.
• Avoid deep redundant nesting like models/<same_name>/...; prefer flat by concern.

Shared Data Layer Boundary (Must)

• Do not place feature business repositories/models under apps/lib/data/.
• Feature business repositories/models must live under each feature's data/ tree.
• apps/lib/data/ is only for infrastructure abstractions and implementations (cache/network/storage), reusable by features.

UI Design System (Must)

• Semantic colors: always use Theme.of(context).colorScheme.* (primary, surface, error, etc.). Never hardcode hex or Colors.*.
• Brand palette colors (event presets, avatar colors, Eisenhower matrix quadrants): use Theme.of(context).extension<AppColorPalette>()!.*.
• Spacing / Radius: use AppSpacing / AppRadius from design_tokens.dart. No hardcoded values.
• AppTheme.light / AppTheme.dark provide complete ColorScheme (light + dark). MaterialApp wires them via theme: / darkTheme:.
• If a semantic slot is missing from ColorScheme, add it to AppTheme — do not bypass colorScheme with hardcoded values.

Reuse & Composition (Must)

• Prefer apps/lib/shared/widgets/ before adding new components.
• Extract repeated page structures/components; do not duplicate sibling-page scaffolds.
• Detail page top-right actions must use shared action-menu components.
• Destructive confirmations must use project-consistent shared surfaces.

Interaction & Feedback (Must)

• User feedback: Toast / AppBanner only.
• Loading indicators: AppLoadingIndicator only.
• Form pages should default to keyboard-overlay behavior to avoid full-page layout jumps.

Agent Chat Protocol (Must)

• Agent chat must follow AG-UI over SSE.
• Lifecycle events are mandatory: RUN_STARTED and exactly one of RUN_FINISHED or RUN_ERROR.
• Current default text delivery is finalized TEXT_MESSAGE_END payloads; do not require token-level TEXT_MESSAGE_CONTENT unless backend protocol explicitly enables it.

HTTP Error Parse Contract (Must)

• Frontend must parse backend errors as RFC7807: type/title/status/detail/instance + extension code/params.
• Error code registry single source of truth: docs/protocols/common/http-error-codes.md.
• Frontend mapping must be based on documented code only (code -> l10n key), not inferred from detail text.
• Any new/changed code requires protocol doc update first, then frontend mapping update.
• Unknown code fallback order: status-generic localized message -> safe generic localized message.

High-Risk Modules (Must)

Auth

• AuthBloc is the single source of truth.
• 401 invalidation must go through global callback chain; no feature-level token clearing or direct login navigation.

Home Message Viewport

• Home message auto-scroll/anchor restore must be event-driven.
• Preserve viewport during history prepend and when user is reading above bottom.

Cache / Repository

• Reads/writes that affect consistency must go through repository layer.
• Cache keys and invalidation policy belong to repository, not UI/Bloc.
• Shared cache infrastructure must live under apps/lib/data/cache/; feature modules must not duplicate low-level cache store logic.
• Shared cache infrastructure (apps/lib/data/cache/) must remain domain-agnostic: do not import features/** or business model DTOs there.
• Domain object serialization/deserialization belongs to repository/feature layer via local mappers/codecs; do not centralize feature-specific codecs in shared cache layer.
• Shared cache layer may only encode/decode primitives, collections, and cache metadata wrappers.
• Cache strategy default is SWR + TTL + invalidation/reload.
• Local partial cache patching is allowed only for simple single-entity updates with clear rollback paths; complex cross-list/cross-feature states must invalidate and refetch.
• Feature TTL policy must be defined in each feature repository; do not add centralized feature TTL registries in shared cache infra.
• Runtime cache is hybrid (memory + local persistent) managed by DI singletons; do not create per-screen/per-widget cache store instances.
• Cross-feature data access must go through app-level facade/usecase boundaries; do not import another feature's data implementation directly from UI/Bloc.
• Repository instances should be resolved from DI singletons to reuse cache and avoid per-feature re-creation.

Reminder / Notification Rewrite Boundary

• Reminder/notification data-interaction logic is under rewrite. Do not reintroduce local-notification scheduling/callback execution paths in apps/lib/data/services/.
• During rewrite, keep protocol/orchestration in core/notification/** and reusable rendering in shared/widgets/notification/**.

Testing Policy

• Prioritize tests for model parsing, service logic, and high-regression interaction flows.
• Simple static UI changes may skip tests.
• Auth/Home/Cache changes must include targeted regression tests.