From ac3f43466d7176dbe07deb6ee92cf28d2405caf6 Mon Sep 17 00:00:00 2001 From: Achintha Isuru Date: Mon, 9 Mar 2026 13:04:36 -0400 Subject: [PATCH] Revert "chore: remove CLAUDE.md as part of project restructuring" This reverts commit 27048feed82422eba0e71c394f6386b5304c228b. --- CLAUDE.md | 149 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..8b17176f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,149 @@ +# 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.().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.` 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///`: +``` +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