feat: add KROW mobile release process documentation and CLAUDE.md for project guidance

2026-03-07 01:46:03 -05:00
parent 972fc28150
commit 9782462a66
12 changed files with 140 additions and 4086 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,140 @@
+# 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
+
+## 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