Files

bwnyasse 9517606e7a feat: add CLAUDE.md and GEMINI.md to provide project context for AI

feat: add bug reports and screenshots to bugs directory
feat(mobile): add device id to mobile makefile commands
fix(mobile): update mobile readme with device id instructions
fix(core_localization): update strings.g.dart with latest generation
chore: add flutter ephemeral files to gitignore

The CLAUDE.md and GEMINI.md files were added to provide AI assistants with the necessary context to understand the project structure, key commands, architecture patterns, and code conventions. This will help them generate more accurate and relevant code and documentation.

The bugs directory was added to store bug reports and screenshots, providing a central location for tracking and analyzing issues.

The mobile makefile commands were updated to include the device ID, allowing developers to specify the target device for running mobile apps. The mobile readme was updated with instructions on how to find the device ID.

The strings.g.dart file was updated with the latest generation to ensure that the localization data is up-to-date.

The flutter ephemeral files were added to gitignore to prevent them from being committed to the repository. These files are generated by Flutter for desktop platforms and should not be tracked.

2026-01-31 09:52:36 -05:00

4.1 KiB

Raw Blame History

GEMINI.md - Project Context for AI Assistants

This file provides context for Gemini 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
/bugs                  # Bug reports and screenshots

Key Commands

Mobile Development

# 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

make install    # Install web dependencies
make dev        # Run web dev server

Data Connect

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
bugs/BUG-REPORT-*.md - Bug reports with analysis

Branch Protection

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

Testing Mobile Apps

Connect your Android device or start emulator
Run flutter devices to get device ID
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:

make mobile-client-dev-android DEVICE=3fb285a7

Dependency resolution issues

cd apps/mobile && melos clean && melos bootstrap

Code generation out of sync

cd apps/mobile && melos run gen:all

Known Technical Debt

See bugs/BUG-REPORT-*.md for detailed analysis of:

Authentication/User sync issues
Error handling architecture (needs AppException pattern)
BLoC state management patterns (copyWith null handling)

4.1 KiB Raw Blame History