9517606e7a
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.
139 lines
4.1 KiB
Markdown
139 lines
4.1 KiB
Markdown
# 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
|
|
```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
|
|
- `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
|
|
|
|
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
|
|
```
|
|
|
|
## 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)
|