Krow/Krow-workspace
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update README and project onboarding for M4 milestone

Browse Source 
Updated README with logo and M4 status. Updated project onboarding doc to version 2.0 with M4 features, release automation, and architecture updates.
This commit is contained in:
Achintha Isuru
2026-03-06 15:36:57 -05:00
parent 37d8427df9
commit 5a5b8894c4
4 changed files with 312 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
BLOCKERS.md
View File

@@ -1,57 +0,0 @@
# Blockers
## App
- Client application
### Github issue
- https://github.com/Oloodi/krow-workforce/issues/210
### Why this task is blocked:
- This task is currently blocked, mainly because client registration via social logins is blocked. To create a business, we require a business name, and with social sign-up we don’t have a screen to capture that information. Because of this, the flow cannot be completed.
- The best option, in my opinion, is to allow Google and Apple sign-in only for existing users, and not use them for new user registration.
### Github issue
- https://github.com/Oloodi/krow-workforce/issues/257
### Why this task is blocked:
- Although this page existed in the prototype, it was not connected to any other pages. In other words, there was no way to navigate to it from anywhere in the application. Therefore, this issue can be closed, as the page is not required in the main application.
## App
- Staff application
### Github issue
- https://github.com/Oloodi/krow-workforce/issues/249
### Why this task is blocked:
- Although this page existed in the prototype, it was not connected to any other pages. In other words, there was no way to navigate to it from anywhere in the application. Therefore, this issue can be closed, as the page is not required in the main application.
### Github issue
- https://github.com/Oloodi/krow-workforce/issues/262
### Why this task is blocked:
- Although this page existed in the prototype, it was not connected to any other pages. In other words, there was no way to navigate to it from anywhere in the application. Therefore, this issue can be closed, as the page is not required in the main application.
# Deviations
## App
- Client Application
### Github issue
- https://github.com/Oloodi/krow-workforce/issues/240
### Deveations:
- In the web prototype, when creating an order, position role rates are displayed based on the selected vendor. This behavior was missing in the mobile prototype. Therefore, we added a dropdown to select the vendor and display the corresponding role rates based on that selection.
# Points to considerate in the future
- client APP:
- Billing need to download a pdf of their invoice.
- On app launch, check whether there is an active session. If a valid session exists, skip the auth flow and navigate directly to Home, loading business account.
- Add an expiration time (TTL) to the session (store expiresAt / expiryTimestamp) and invalidate/clear the session when it has expired.
- Rapid order need IA to work, I think we need also to add a form as the webpage.
- Staff APP:
- On app launch, check whether there is an active session. If a valid session exists, skip the auth flow and navigate directly to Home, loading Staff account.
- Add an expiration time (TTL) to the session (store expiresAt / expiryTimestamp) and invalidate/clear the session when it has expired.
- For staffs Skills = Roles? thinking in the future for the smart assigned that need to know the roles of staff to assign.
## App
- Staff Application
### Github issue
- https://github.com/Oloodi/krow-workforce/issues/248
### Deveations:
- Assumed that a worker can only have one shift per day.

56
README.md
View File

@@ -1,7 +1,20 @@
<p align="center">
<img src="apps/mobile/packages/design_system/assets/logo-yellow.png" alt="KROW Logo" width="200"/>
</p>
# KROW Workforce Monorepo
KROW is a comprehensive workforce management platform designed to streamline operations for events, hospitality, and enterprise staffing. This monorepo contains all components of the ecosystem, from the data layer to the user-facing applications.
## 📍 Current Status
**Latest Milestone:** M4 (Released: March 5, 2026)
- ✅ Staff Mobile App: v0.0.1-m4
- ✅ Client Mobile App: v0.0.1-m4
- 🚀 Full profile management with documents & certificates
- 🚀 Enhanced session management and Core API integration
- 🚀 Automated GitHub Actions workflows for releases
## 🚀 Repository Structure
### 📦 Apps (`/apps`)
@@ -26,6 +39,7 @@ Tools and resources for the development and operations team:
- **`/makefiles`**: Modularized `Makefile` logic for project automation.
- **`/scripts`**: Automation scripts (security, hachage, environment setup).
- **`/firebase`**: Global Firebase configuration (Firestore/Storage rules).
- **`/.github`**: GitHub Actions workflows for CI/CD and release automation.
## 🛠️ Tech Stack
- **Frontend:** React (Vite)
@@ -58,17 +72,57 @@ This project uses a modular `Makefile` for all common tasks.
make launchpad-dev
```
5. **Mobile app development:**
```bash
cd apps/mobile
flutter pub get
melos bootstrap
flutter run # Select device
```
## 🚀 Release Process
### Mobile App Releases
We use GitHub Actions for automated mobile releases:
- **Standard Release**: Trigger [Product Release workflow](https://github.com/Oloodi/krow-workforce/actions/workflows/product-release.yml)
- Auto-extracts version from `pubspec.yaml`
- Creates Git tags: `krow-withus-<app>-mobile/<env>-vX.Y.Z`
- Generates GitHub Release with CHANGELOG
- Builds and signs APK (dev/stage/prod keystores)
- **Hotfix Release**: Trigger [Hotfix Branch Creation workflow](https://github.com/Oloodi/krow-workforce/actions/workflows/hotfix-branch-creation.yml)
- Auto-increments PATCH version
- Updates `pubspec.yaml` and `CHANGELOG.md`
- Creates PR with fix instructions
**See:** [Mobile Release Documentation](./docs/RELEASE/mobile-releases.md) for complete guide.
## 📚 Documentation
### Core Documentation
- **[00-vision.md](./docs/00-vision.md)**: Project objectives and guiding principles.
- **[01-backend-api-specification.md](./docs/01-backend-api-specification.md)**: (Legacy) Reference for data schemas.
- **[02-codemagic-env-vars.md](./docs/02-codemagic-env-vars.md)**: Guide for CI/CD environment variables.
- **[03-contributing.md](./docs/03-contributing.md)**: Guidelines for new developers and setup checklist.
- **[04-sync-prototypes.md](./docs/04-sync-prototypes.md)**: How to sync prototypes for local dev and AI context.
- **[05-project-onboarding-master.md](./docs/05-project-onboarding-master.md)**: Comprehensive onboarding guide and project overview.
### Mobile Development Documentation
- **[MOBILE/00-agent-development-rules.md](./docs/MOBILE/00-agent-development-rules.md)**: Rules and best practices for mobile development.
- **[MOBILE/01-architecture-principles.md](./docs/MOBILE/01-architecture-principles.md)**: Flutter clean architecture, package roles, and dependency flow.
- **[MOBILE/02-design-system-usage.md](./docs/MOBILE/02-design-system-usage.md)**: Design system components and theming guidelines.
- **[MOBILE/00-agent-development-rules.md](./docs/MOBILE/00-agent-development-rules.md)**: Rules and best practices for mobile development.
- **[MOBILE/03-data-connect-connectors-pattern.md](./docs/MOBILE/03-data-connect-connectors-pattern.md)**: Data Connect integration patterns.
- **[MOBILE/04-use-case-completion-audit.md](./docs/MOBILE/04-use-case-completion-audit.md)**: Feature implementation status and audit.
- **[MOBILE/05-release-process.md](./docs/MOBILE/05-release-process.md)**: Mobile app release process (quick reference).
### Release Documentation
- **[RELEASE/mobile-releases.md](./docs/RELEASE/mobile-releases.md)**: Comprehensive mobile release guide with versioning, CHANGELOGs, GitHub Actions workflows, and APK signing.
### CHANGELOGs
- **[Staff Mobile CHANGELOG](./apps/mobile/apps/staff/CHANGELOG.md)**: Staff app release history (M3, M4).
- **[Client Mobile CHANGELOG](./apps/mobile/apps/client/CHANGELOG.md)**: Client app release history (M3, M4).
## 🤝 Contributing
New to the team? Please read our **[Contributing Guide](./docs/03-contributing.md)** to get your environment set up and understand our workflow.

276
docs/05-project-onboarding-master.md
View File

@@ -1,8 +1,9 @@
# KROW Workforce Platform - Project Onboarding Master Document
> **Version:** 1.1
> **Last Updated:** 2026-01-22
> **Version:** 2.0
> **Last Updated:** 2026-03-06
> **Purpose:** Source of Truth for Team Onboarding & Sprint Planning
> **Latest Milestone:** M4 (Released: March 5, 2026)
---
@@ -13,7 +14,8 @@
3. [Core Domain Logic](#3-core-domain-logic)
4. [Feature Gap Analysis](#4-feature-gap-analysis)
5. [Data Connect & Development Strategy](#5-data-connect--development-strategy)
6. [Definition of Done (DoD)](#6-definition-of-done-dod)
6. [Release Process & Automation](#6-release-process--automation)
7. [Definition of Done (DoD)](#7-definition-of-done-dod)
---
@@ -160,27 +162,54 @@ graph TB
- Event-driven architecture for async operations
- Clean separation from data layer
3. **PostgreSQL Retention:**
3. **Core API Services:**
- Document verification service
- File upload service with signed URLs
- LLM service for AI features (RAPID orders)
- Integrated via ApiService (Dio-based)
4. **PostgreSQL Retention:**
- Full data ownership and portability
- Complex queries and reporting capabilities
- Industry-standard for enterprise requirements
4. **Monorepo Structure:**
5. **Monorepo Structure:**
```
krow-workforce-web/
├── apps/
│ ├── web-dashboard/ # Vite + React
│ ├── mobile/
| | ├── apps/
| | │ ├── client/ # Flutter (business app)
| | │ └── staff/ # Flutter (staff app)
| | │ ├── client/ # Flutter (business app) - v0.0.1-m4
| | │ └── staff/ # Flutter (staff app) - v0.0.1-m4
| | └── packages/
| | ├── features/
| | │ ├── client/ # Client app features
| | │ └── staff/ # Staff app features
| | │ └── profile_sections/ # Modular profile (M4)
| | │ ├── onboarding/ # Profile info, experience, emergency
| | │ ├── compliance/ # Documents, certificates, attire
| | │ ├── finances/ # Bank, tax forms, timecard
| | │ └── support/ # FAQs, privacy & security
| | ├── core/ # Cross-cutting concerns
| | ├── data_connect/ # Backend integration
| | ├── domain/ # Entities & failures
| | ├── design_system/ # UI components & theme
| | └── core_localization/ # i18n
├── backend/
│ ├── dataconnect/ # Firebase Data Connect schemas
│ └── functions/ # Cloud Functions
│ ├── cloud-functions/ # Firebase Cloud Functions
│ ├── command-api/ # Command API service
│ └── core-api/ # Core API (verification, upload, LLM)
├── firebase/ # Firebase config
├── internal/
│ └── launchpad/ # Internal tools & prototypes
├── .github/
│ ├── workflows/ # GitHub Actions (release automation)
│ └── scripts/ # Release helper scripts
└── docs/ # Documentation
├── MOBILE/ # Mobile dev docs
└── RELEASE/ # Release docs
```
---
@@ -634,7 +663,92 @@ These **must be ported** from legacy:
11. **Push Notifications** - FCM integration
12. **Geofencing** - Location-based clock validation
### 4.6 Migration Strategy
### 4.6 M4 Milestone Completion Status (Released: March 5, 2026)
**Version:** v0.0.1-m4 (both staff and client apps)
#### Staff App M4 Achievements
**Profile Management - 13 Subsections (✅ Complete):**
Via modular `profile_sections/` architecture:
**Onboarding:**
- ✅ Personal Info (name, email, phone, address, SSN)
- ✅ Experience (work history, skills, preferences)
- ✅ Emergency Contacts (safety contacts with relationship)
**Compliance:**
- ✅ Documents (ID verification, uploads)
- ✅ Certificates (certifications with expiry tracking)
- ✅ Attire (uniform verification with camera/gallery)
**Finances:**
- ✅ Bank Account (payout setup with validation)
- ✅ Tax Forms (I-9, W-4 forms)
- ✅ Time Card (hours log with history)
**Support:**
- ✅ FAQs (help articles)
- ✅ Privacy & Security (settings, account management)
**Profile Features:**
- ✅ Benefits Overview (perks information)
- ✅ Profile completion tracking
**Architecture:**
- ✅ Modular feature structure (`profile_sections/onboarding`, `/compliance`, `/finances`, `/support`)
- ✅ Flutter Modular dependency injection
- ✅ Data Connect integration with type-safe SDKs
- ✅ Shared design system components
#### M4 Core Features
**Authentication:**
- ✅ Firebase phone auth (OTP flow)
- ✅ Email/password authentication
- ✅ Profile setup wizard
**Session Management:**
- ✅ Clock in/out flow (prototype UI)
- ✅ Shift viewing and management
- ✅ Session status tracking
**Core API Integration:**
- ✅ Document verification service
- ✅ File upload service with signed URLs
- ✅ ApiService (Dio-based) with error handling
**Release Automation:**
- ✅ GitHub Actions workflows (product-release, hotfix-branch-creation)
- ✅ APK signing with 24 GitHub Secrets
- ✅ Automated changelog generation
- ✅ Git tag automation
- ✅ 8 helper scripts for release management
#### Client App M4 Status
**Completion:** 89% of 9 major feature categories
**Key Features:**
- ✅ Authentication (email/password)
- ✅ Order management (4 types: one-time, rapid, recurring, permanent)
- ✅ Coverage dashboard
- ✅ Reports (daily ops, spend, forecast, performance, no-show)
- ✅ Hub management
- ✅ Settings and preferences
#### Documentation M4
- ✅ Comprehensive release guide (`docs/RELEASE/mobile-releases.md` - 900+ lines)
- ✅ Mobile development documentation (6 files in `docs/MOBILE/`)
- ✅ Release process quick reference
- ✅ GitHub Actions workflow documentation
- ✅ APK signing setup guide
- ✅ Architecture principles and patterns
- ✅ Use case completion audit
### 4.7 Migration Strategy
```
┌─────────────────────────────────────────────────────────────────┐
@@ -665,9 +779,9 @@ These **must be ported** from legacy:
└─────────────────────────────────────────────────────────────────┘
```
### 4.7 Mobile Prototype Analysis (Source Code)
### 4.8 Mobile Prototype Analysis (Source Code)
#### 4.7.1 Mobile Client App (Flutter)
#### 4.8.1 Mobile Client App (Flutter)
**Location:** `internal/launchpad/prototypes-src/mobile/apps/client/`
@@ -706,7 +820,7 @@ These **must be ported** from legacy:
---
#### 4.7.2 Mobile Staff App (Flutter)
#### 4.8.2 Mobile Staff App (Flutter)
**Location:** `internal/launchpad/prototypes-src/mobile/apps/staff/`
@@ -776,7 +890,7 @@ These **must be ported** from legacy:
---
### 4.8 Complete Feature Comparison (All 3 Apps)
### 4.9 Complete Feature Comparison (All 3 Apps)
| Feature | Legacy Mobile | Web Prototype | Mobile Prototype |
|---------|--------------|---------------|------------------|
@@ -802,7 +916,7 @@ These **must be ported** from legacy:
| **Penalty System** | ✅ | ❌ | ❌ |
| **Staff Rating** | ✅ | ❌ | ❌ |
### 4.9 Source Code Locations
### 4.10 Source Code Locations
| Component | Location | Tech |
|-----------|----------|------|
@@ -926,9 +1040,133 @@ Based on minimal dependencies:
---
## 6. Definition of Done (DoD)
## 6. Release Process & Automation
### 6.1 Feature-Level DoD (MVP Phase)
### 6.1 Versioning Strategy
**Mobile Apps:**
- Format: `v{major}.{minor}.{patch}-{milestone}`
- Example: `v0.0.1-m4` (current release)
- Milestones: m1, m2, m3, m4, etc.
- Auto-extracted from `apps/mobile/apps/{staff|client}/pubspec.yaml`
**Git Tags:**
- Format: `{app-name}/{version}`
- Examples: `staff/v0.0.1-m4`, `client/v0.0.1-m4`
### 6.2 GitHub Actions Workflows
**1. Product Release (`.github/workflows/product-release.yml`)**
- **Trigger:** Manual dispatch via GitHub UI
- **Purpose:** Automated production releases with APK signing
- **Process:**
1. Extracts version from `pubspec.yaml`
2. Builds signed APKs for both apps
3. Creates GitHub release with changelog
4. Tags release (e.g., `staff/v0.0.1-m4`)
5. Uploads APKs as release assets
- **Secrets Required:** 24 GitHub Secrets for APK signing (see `docs/RELEASE/mobile-releases.md`)
**2. Hotfix Branch Creation (`.github/workflows/hotfix-branch-creation.yml`)**
- **Trigger:** Manual dispatch with version input
- **Purpose:** Emergency fixes for production issues
- **Process:**
1. Creates `hotfix/{version}` branch from latest tag
2. Opens PR back to `dev` branch
3. Auto-updates PR description with hotfix checklist
**3. Helper Scripts (`.github/scripts/`)**
- `extract-version.sh` - Extracts version from pubspec.yaml
- `generate-changelog.sh` - Generates release notes from CHANGELOG
- `create-release.sh` - Creates GitHub release
- `upload-assets.sh` - Uploads APKs to release
- `build-apk.sh` - Builds signed APK
- `tag-release.sh` - Creates Git tags
- `hotfix-branch.sh` - Creates hotfix branches
- `update-pr.sh` - Updates PR descriptions
### 6.3 APK Signing Setup
**Required GitHub Secrets (per app):**
```
STAFF_UPLOAD_KEYSTORE_BASE64 # Base64-encoded keystore
STAFF_UPLOAD_STORE_PASSWORD # Keystore password
STAFF_UPLOAD_KEY_ALIAS # Key alias
STAFF_UPLOAD_KEY_PASSWORD # Key password
STAFF_KEYSTORE_PROPERTIES_BASE64 # Base64-encoded key.properties
CLIENT_UPLOAD_KEYSTORE_BASE64
CLIENT_UPLOAD_STORE_PASSWORD
CLIENT_UPLOAD_KEY_ALIAS
CLIENT_UPLOAD_KEY_PASSWORD
CLIENT_KEYSTORE_PROPERTIES_BASE64
```
### 6.4 CHANGELOG Format
Each app maintains a separate CHANGELOG:
- `apps/mobile/apps/staff/CHANGELOG.md`
- `apps/mobile/apps/client/CHANGELOG.md`
**Format:**
```markdown
## [Unreleased]
### Added
- New feature descriptions
### Changed
- Modified feature descriptions
### Fixed
- Bug fix descriptions
## [0.0.1-m4] - 2026-03-05
### Added
- Profile management with 13 subsections
- Documents & certificates management
- Benefits overview
...
```
### 6.5 Release Documentation
**Comprehensive Guide:**
- Location: `docs/RELEASE/mobile-releases.md`
- Length: 900+ lines
- Contents:
- Complete versioning strategy
- CHANGELOG format and examples
- GitHub Actions workflow details
- APK signing setup (with secret generation)
- Helper scripts reference
- Troubleshooting guide
**Quick Reference:**
- Location: `docs/MOBILE/05-release-process.md`
- Links to comprehensive guide and workflows
### 6.6 Local Release Commands (via Makefile)
```bash
# Build unsigned APKs locally
make build-apk-staff
make build-apk-client
# Run GitHub Actions locally (requires act)
make test-release-workflow
# Generate changelog entries
make changelog-staff
make changelog-client
```
---
## 7. Definition of Done (DoD)
### 7.1 Feature-Level DoD (MVP Phase)
A feature is **DONE** when:
@@ -944,7 +1182,7 @@ A feature is **DONE** when:
> **Note (MVP):** For rapid MVP delivery, we focus on manual/integration testing directly in applications rather than unit tests. Automated test coverage will be added post-MVP.
### 6.2 Sprint-Level DoD
### 7.2 Sprint-Level DoD
A sprint is **DONE** when:
@@ -956,7 +1194,7 @@ A sprint is **DONE** when:
- [ ] Demo-ready for stakeholders
- [ ] Documentation updated
### 6.3 Code Quality Standards
### 7.3 Code Quality Standards
| Aspect | Standard |
|--------|----------|
@@ -967,7 +1205,7 @@ A sprint is **DONE** when:
| **PRs** | Template completed, 1+ approval |
| **Testing (MVP)** | Manual testing in application |
### 6.4 Commit Message Format
### 7.4 Commit Message Format
```
<type>(<scope>): <subject>

8
krow-workforce-web.code-workspace
View File

@@ -1,8 +0,0 @@
{
"folders": [
{
"path": "."
}
],
"settings": {}
}