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

Skills

• The project has 4 specialized skills in .claude/skills/ that provide deep domain knowledge. Invoke them and other global skills that you have when working in their domains.

Sub-Agents

• The project has 4 sub-agents in .claude/sub-agents/ that can be invoked for specific tasks. Invoke them and other global sub-agents that you have when working in their domains.

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