# CLAUDE.md - Project Context for AI Assistants

This file provides context for Claude Code and other AI assistants working on this codebase.

## Project Overview

**KROW Workforce** is a workforce management platform connecting businesses with temporary/on-demand workers. It consists of:
- **Client App**: For businesses to create orders, manage hubs, handle billing
- **Staff App**: For workers to manage availability, clock in/out, view earnings
- **Web Dashboard**: Admin portal (React/Vite - WIP)
- **Backend**: Firebase Data Connect + PostgreSQL on Cloud SQL

## Monorepo Structure

```
/apps
  /mobile              # Flutter apps (managed by Melos)
    /apps
      /client          # krowwithus_client - Business app
      /staff           # krowwithus_staff - Worker app
      /design_system_viewer
    /packages
      /core            # Base utilities
      /domain          # Business entities, repository interfaces
      /data_connect    # Data layer, Firebase Data Connect SDK
      /design_system   # Shared UI components
      /core_localization # i18n (Slang)
      /features
        /client/*      # Client-specific features
        /staff/*       # Staff-specific features
  /web-dashboard       # React web app (WIP)
/backend
  /dataconnect         # GraphQL schemas, Firebase Data Connect config
  /cloud-functions     # Serverless functions (placeholder)
/internal
  /launchpad           # Internal DevOps portal
  /api-harness         # API testing tool
/makefiles             # Modular Make targets
/docs                  # Project documentation
```

## Key Commands

### Mobile Development
```bash
# Install dependencies
make mobile-install

# Run client app (specify your device ID)
make mobile-client-dev-android DEVICE=<device_id>

# Run staff app
make mobile-staff-dev-android DEVICE=<device_id>

# Find your device ID
flutter devices

# Build APK
make mobile-client-build PLATFORM=apk
make mobile-staff-build PLATFORM=apk

# Code generation (localization + build_runner)
cd apps/mobile && melos run gen:all
```

### Web Development
```bash
make install    # Install web dependencies
make dev        # Run web dev server
```

### Data Connect
```bash
make dataconnect-sync  # Deploy schemas, migrate, regenerate SDK
```

## Architecture Patterns

- **State Management**: BLoC pattern (flutter_bloc)
- **Navigation**: Flutter Modular
- **Architecture**: Clean Architecture (domain/data/presentation layers)
- **Feature Organization**: Each feature is a separate package
- **Value Objects**: Equatable for entity equality

## Code Conventions

- Features go in `/apps/mobile/packages/features/{client|staff}/`
- Shared code goes in `/apps/mobile/packages/{core|domain|data_connect}/`
- UI components go in `/apps/mobile/packages/design_system/`
- GraphQL schemas go in `/backend/dataconnect/schema/`
- Documentation language: **English**

## Important Files

- `apps/mobile/melos.yaml` - Melos workspace config
- `makefiles/mobile.mk` - Mobile Make targets
- `backend/dataconnect/dataconnect.yaml` - Data Connect config
- `firebase.json` - Firebase hosting/emulator config
- `BLOCKERS.md` - Known blockers and deviations

## Branch Protection

- `main` and `dev` branches are protected
- Always create feature branches: `feature/`, `fix/`, `chore/`
- PRs required for merging

## Testing Mobile Apps

1. Connect your Android device or start emulator
2. Run `flutter devices` to get device ID
3. Run `make mobile-client-dev-android DEVICE=<your_device_id>`

## Common Issues

### "No devices found with name 'android'"
The Makefile defaults to device ID `android`. Override with your actual device:
```bash
make mobile-client-dev-android DEVICE=3fb285a7
```

### Dependency resolution issues
```bash
cd apps/mobile && melos clean && melos bootstrap
```

### Code generation out of sync
```bash
cd apps/mobile && melos run gen:all
```