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)
```bash
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:
```bash
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)
```bash
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)
```bash
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