docs: update README and project onboarding for M4 milestone

Updated README with logo and M4 status. Updated project onboarding doc to version 2.0 with M4 features, release automation, and architecture updates.
2026-03-06 15:36:57 -05:00
parent 37d8427df9
commit 5a5b8894c4
4 changed files with 312 additions and 85 deletions
--- a/docs/05-project-onboarding-master.md
+++ b/docs/05-project-onboarding-master.md
@@ -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>