134 lines
5.5 KiB
Markdown
134 lines
5.5 KiB
Markdown
# KROW Workforce Mobile 📱
|
|
|
|
This folder holds the mobile app code for the KROW Workforce apps.
|
|
This project uses [Melos](https://melos.invertase.dev/) to manage multiple Flutter packages and applications.
|
|
|
|
## 📂 Project Structure
|
|
|
|
The project is organized into modular packages to ensure separation of concerns and maintainability.
|
|
|
|
- **`apps/`**: Main application entry points.
|
|
- `client`: The application for businesses/clients.
|
|
- `staff`: The application for workforce/staff.
|
|
- `design_system_viewer`: A gallery of our design system components.
|
|
- **`packages/`**: Shared logic and feature modules.
|
|
- `features/`: UI and business logic for specific features (e.g., Auth, Home, Hubs).
|
|
- `features/client`: Client specific features.
|
|
- `features/staff`: Staff specific features.
|
|
- `design_system/`: Shared UI components, tokens (colors, spacing), and core widgets.
|
|
- `domain/`: Shared business entities and repository interfaces.
|
|
- `data_connect/`: Data access layer (Mocks and Firebase Data Connect SDK).
|
|
- `core_localization/`: Internationalization using Slang.
|
|
- `core/`: Base utilities and common logic.
|
|
|
|
## 🚀 Getting Started
|
|
|
|
### 1. Prerequisites
|
|
Ensure you have the Flutter SDK installed and configured.
|
|
|
|
### 2. Android Keystore Setup (Required for Release Builds)
|
|
|
|
To build release APKs/AABs for Android, you need the signing keystores. The keystore configuration (`key.properties`) is committed to the repository, but the actual keystore files are **not** for security reasons.
|
|
|
|
#### For Local Development (First-time Setup)
|
|
|
|
Contact your team lead to obtain the keystore files:
|
|
- `krow_with_us_client_dev.jks` - Client app signing keystore
|
|
- `krow_with_us_staff_dev.jks` - Staff app signing keystore
|
|
|
|
Once you have the keystores, copy them to the respective app directories:
|
|
|
|
```bash
|
|
# Copy keystores to their locations
|
|
cp krow_with_us_client_dev.jks apps/mobile/apps/client/android/app/
|
|
cp krow_with_us_staff_dev.jks apps/mobile/apps/staff/android/app/
|
|
```
|
|
|
|
The `key.properties` configuration files are already in the repository:
|
|
- `apps/mobile/apps/client/android/key.properties`
|
|
- `apps/mobile/apps/staff/android/key.properties`
|
|
|
|
No manual property file creation is needed — just place the `.jks` files in the correct locations.
|
|
|
|
#### For CI/CD (CodeMagic)
|
|
|
|
CodeMagic uses a native keystore management system. Follow these steps:
|
|
|
|
**Step 1: Upload Keystores to CodeMagic**
|
|
1. Go to **CodeMagic Team Settings** → **Code signing identities** → **Android keystores**
|
|
2. Upload the keystore files with these **Reference names** (important!):
|
|
- `krow_client_dev` (for dev builds)
|
|
- `krow_client_staging` (for staging builds)
|
|
- `krow_client_prod` (for production builds)
|
|
- `krow_staff_dev` (for dev builds)
|
|
- `krow_staff_staging` (for staging builds)
|
|
- `krow_staff_prod` (for production builds)
|
|
3. When uploading, enter the keystore password, key alias, and key password for each keystore
|
|
|
|
**Step 2: Automatic Environment Variables**
|
|
CodeMagic automatically injects the following environment variables based on the keystore reference:
|
|
- `CM_KEYSTORE_PATH_CLIENT` / `CM_KEYSTORE_PATH_STAFF` - Path to the keystore file
|
|
- `CM_KEYSTORE_PASSWORD_CLIENT` / `CM_KEYSTORE_PASSWORD_STAFF` - Keystore password
|
|
- `CM_KEY_ALIAS_CLIENT` / `CM_KEY_ALIAS_STAFF` - Key alias
|
|
- `CM_KEY_PASSWORD_CLIENT` / `CM_KEY_PASSWORD_STAFF` - Key password
|
|
|
|
**Step 3: Build Configuration**
|
|
The `build.gradle.kts` files are already configured to:
|
|
- Use CodeMagic environment variables when running in CI (`CI=true`)
|
|
- Fall back to `key.properties` for local development
|
|
|
|
Reference: [CodeMagic Android Signing Documentation](https://docs.codemagic.io/yaml-code-signing/signing-android/)
|
|
|
|
### 3. Initial Setup
|
|
Run the following command from the **project root** to install Melos, bootstrap all packages, generate localization files, and generate the Firebase Data Connect SDK:
|
|
|
|
```bash
|
|
# Using Makefile (Recommended)
|
|
make mobile-install
|
|
```
|
|
|
|
This command will:
|
|
- Install Melos if not already installed
|
|
- Generate the Firebase Data Connect SDK from schema files
|
|
- Bootstrap all packages (install dependencies)
|
|
- Generate localization files
|
|
|
|
**Note:** The Firebase Data Connect SDK files (`dataconnect_generated/`) are auto-generated and not committed to the repository. They will be regenerated automatically when you run `make mobile-install` or any mobile development commands.
|
|
|
|
### 4. Running the Apps
|
|
You can run the applications using Melos scripts or through the `Makefile`:
|
|
|
|
First, find your device ID:
|
|
```bash
|
|
flutter devices
|
|
```
|
|
|
|
#### Client App
|
|
```bash
|
|
# Using Melos
|
|
melos run start:client -- -d <device_id>
|
|
# Using Makefile (DEVICE defaults to 'android' if not specified)
|
|
make mobile-client-dev-android DEVICE=<device_id>
|
|
```
|
|
|
|
#### Staff App
|
|
```bash
|
|
# Using Melos
|
|
melos run start:staff -- -d <device_id>
|
|
# Using Makefile (DEVICE defaults to 'android' if not specified)
|
|
make mobile-staff-dev-android DEVICE=<device_id>
|
|
```
|
|
|
|
## 🛠 Useful Commands
|
|
|
|
- **Bootstrap**: `melos bootstrap` (Installs all dependencies)
|
|
- **Generate All**: `melos run gen:all` (Localization + Code Generation)
|
|
- **Analyze**: `melos run analyze:all`
|
|
- **Test**: `melos run test:all`
|
|
- **Help**: `melos run info` (Shows all available custom scripts)
|
|
|
|
## 🏗 Coding Principles
|
|
- **Clean Architecture**: We strictly follow Domain-Driven Design and Clean Architecture.
|
|
- **Modularity**: Every feature should be its own package in `packages/features/`. Client and staff specific features should be in their respective packages.
|
|
- **Consistency**: Use the `design_system` package for all UI elements to ensure a premium, unified look.
|