Krow-workspace/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

KROW Workforce is a workforce management platform monorepo containing Flutter mobile apps, a React web dashboard, and Firebase backend services.

Repository Structure

apps/mobile/          # Flutter monorepo (Melos workspace)
  apps/staff/         # Staff mobile app
  apps/client/        # Client (business) mobile app
  packages/
    design_system/    # Shared UI tokens & components
    core/             # Cross-cutting concerns (mixins, extensions)
    core_localization/# i18n via Slang
    domain/           # Pure Dart entities & failures
    data_connect/     # Firebase Data Connect adapter (connectors)
    features/staff/   # Staff feature packages
    features/client/  # Client feature packages
apps/web/             # React/Vite web dashboard (TypeScript, Tailwind, Redux Toolkit)
backend/
  dataconnect/        # Firebase Data Connect GraphQL schemas
  core-api/           # Core business logic service
  cloud-functions/    # Serverless functions

Common Commands

All commands use the root Makefile (composed from makefiles/*.mk). Run make help for the full list.

Mobile (Flutter)

make mobile-install                          # Bootstrap Melos workspace + generate SDK
make mobile-staff-dev-android                # Run staff app (add DEVICE=android)
make mobile-client-dev-android               # Run client app
make mobile-analyze                          # Lint (flutter analyze)
make mobile-test                             # Run tests
make test-e2e                                # Maestro E2E tests (both apps)

Single-package operations via Melos:

cd apps/mobile
melos run gen:l10n                           # Generate localization (Slang)
melos run gen:build                          # Run build_runner
melos run analyze:all                        # Analyze all packages
melos run test:all                           # Test all packages

Web (React/Vite)

make web-install        # npm install
make web-dev            # Start dev server
make web-build          # Production build
make web-lint           # ESLint
make web-test           # Vitest

Backend (Data Connect)

make dataconnect-generate-sdk [ENV=dev]      # Generate SDK
make dataconnect-deploy [ENV=dev]            # Deploy schemas
make dataconnect-sync-full [ENV=dev]         # Deploy + migrate + generate

Mobile Architecture

Clean Architecture with strict inward dependency flow:

Presentation (Pages, BLoCs, Widgets)
  → Application (Use Cases)
    → Domain (Entities, Repository Interfaces, Failures)
      ← Data (Repository Implementations, Connectors)

Key Patterns

• State management: Flutter BLoC/Cubit. Register BLoCs with i.add() (transient), never i.addSingleton(). Use BlocProvider.value() for shared BLoCs.
• DI & Routing: Flutter Modular. Safe navigation via safeNavigate(), safePush(), popSafe(). Never use Navigator.push() directly.
• Error handling in BLoCs: Use BlocErrorHandler mixin with _safeEmit() to prevent StateError on disposed BLoCs.
• Backend access: All Data Connect calls go through the data_connect package's Connectors. Use _service.run(() => connector.<query>().execute()) for automatic auth/token management.
• Session management: SessionHandlerMixin + SessionListener widget. Initialized in main.dart with role-based config.
• Localization: All user-facing strings via context.strings.<key> from core_localization. Error messages via ErrorTranslator.
• Design system: Use tokens from UiColors, UiTypography, UiConstants. Never hardcode colors, fonts, or spacing.

Feature Package Structure

New features go in apps/mobile/packages/features/<app>/<feature>/:

lib/src/
  domain/repositories/    # Abstract interface classes
  data/repositories_impl/ # Implementations using data_connect
  application/            # Use cases (business logic)
  presentation/
    blocs/                # BLoCs/Cubits
    pages/                # Pages (prefer StatelessWidget)
    widgets/              # Reusable widgets

Critical Rules

• Features must not import other features directly
• Business logic belongs in Use Cases, never in BLoCs or widgets
• Firebase packages (firebase_auth, firebase_data_connect) belong only in data_connect
• Don't add 3rd-party packages without checking packages/core first
• Generated code directories are excluded from analysis: **/dataconnect_generated/**, **/*.g.dart, **/*.freezed.dart

Code Generation

• Slang (i18n): Input lib/src/l10n/*.i18n.json → Output strings.g.dart
• build_runner: Various generated files (.g.dart, .freezed.dart)
• Firebase Data Connect: Auto-generated SDK in packages/data_connect/lib/src/dataconnect_generated/

Naming Conventions (Dart)

Type	Convention	Example
Files	snake_case	user_profile_page.dart
Classes	PascalCase	UserProfilePage
Interfaces	suffix Interface	AuthRepositoryInterface
Implementations	suffix Impl	AuthRepositoryImpl

Key Documentation

• docs/MOBILE/00-agent-development-rules.md — Non-negotiable architecture rules
• docs/MOBILE/01-architecture-principles.md — Clean architecture details
• docs/MOBILE/02-design-system-usage.md — Design system token usage
• docs/MOBILE/03-data-connect-connectors-pattern.md — Backend integration pattern
• docs/MOBILE/05-release-process.md — Release quick reference
• docs/RELEASE/mobile-releases.md — Complete release guide

Skills & Sub-Agents

The project has 4 specialized skills in .claude/skills/ that provide deep domain knowledge. Invoke them when working in their domains — they contain detailed rules, patterns, and code examples beyond what's in this file.

krow-mobile-architecture

When to use: Architecting new mobile features, debugging state management or BLoC lifecycle issues, preventing prop drilling, managing session state, implementing Data Connect connector repositories, setting up feature modules and DI, refactoring to Clean Architecture.

What it covers: Full Clean Architecture implementation, package dependency graph, Data Connect service & session management (SessionHandlerMixin, SessionListener), connector pattern for reusable backend queries, BLoC lifecycle safety (singleton registration, BlocProvider.value(), BlocErrorHandler mixin with _safeEmit()), feature isolation rules, typed navigation with safe extensions, session store pattern.

krow-mobile-development-rules

When to use: Creating new mobile features/packages, implementing BLoCs/Use Cases/Repositories, integrating with Firebase Data Connect, migrating from prototypes, reviewing code compliance, setting up navigation flows.

What it covers: Non-negotiable enforcement rules — file creation & package structure with exact path conventions, naming conventions, zero-tolerance logic placement boundaries (business rules → Use Cases only, state → BLoCs only, data transformation → Repositories), localization integration (all strings via core_localization, BLoCs emit failures not strings), Data Connect repository pattern with _service.run(), prototype migration rules, error handling pattern (domain failures → ErrorTranslator), enforcement checklist.

krow-mobile-design-system

When to use: Implementing any UI in mobile features, migrating POC/prototype designs to production, creating themed widgets, reviewing UI code for design system compliance, matching colors/typography from designs, adding icons/spacing/layout.

What it covers: Immutable design token rules — all colors from UiColors (zero hex codes), all typography from UiTypography (zero custom TextStyle), all spacing/radius/elevation from UiConstants (zero magic numbers), all icons from UiIcons (zero direct library imports). POC → Production workflow (structure → architecture → design system integration), color/typography matching tables, extension policy for adding new tokens, review checklist.

krow-mobile-release

When to use: Preparing mobile releases, updating CHANGELOGs, triggering GitHub Actions release workflows, creating hotfix branches, understanding versioning strategy, setting up APK signing, troubleshooting release failures.

What it covers: Versioning strategy (v{major}.{minor}.{patch}-{milestone}), CHANGELOG management (Keep a Changelog format, writing guidelines), Git tagging (krow-withus-<app>-mobile/<env>-vX.Y.Z), GitHub Actions workflows (Product Release, Product Hotfix), APK signing setup (24 GitHub Secrets), step-by-step release process for dev/stage/prod, hotfix procedures, release cadence, troubleshooting guide, helper scripts.

CI/CD

• .github/workflows/mobile-ci.yml — Mobile build & test on PR
• .github/workflows/product-release.yml — Automated versioning, tags, APK builds
• .github/workflows/web-quality.yml — Web linting & tests