Krow-workspace/README.md

<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](https://github.com/Oloodi/krow-workforce/releases/tag/krow-withus-worker-mobile%2Fdev-v0.0.1-m4)
- ✅ Client Mobile App: [v0.0.1-m4](https://github.com/Oloodi/krow-workforce/releases/tag/krow-withus-client-mobile%2Fdev-v0.0.1-m4)

## 🚀 Repository Structure

### 📦 Apps (`/apps`)
These are the production-ready applications for our users:
-   **`web-dashboard/`**: The primary React/Vite dashboard for Admin, Vendors, and Clients.
-   **`mobile/`**: Flutter applications for client and staff.
  - `client`: The application for final clients to manage orders and billing.
  - `staff`: The application for staff members (scheduling, clock-in/out, earnings).

### ⚙️ Backend (`/backend`)
The core data engine powering all applications:
-   **`dataconnect/`**: Firebase Data Connect configuration, GraphQL schemas (PostgreSQL), and auto-generated SDKs.

### 🛠️ Internal (`/internal`)
Tools and resources for the development and operations team:
-   **`launchpad/`**: A secure portal (DevOps Launchpad) to access internal resources, documentation, and infrastructure links.
-   **`api-harness/`**: A technical tool for testing and validating the Data Connect API and Cloud Functions.
-   **`prototypes/`**: Reference code and visual prototypes (synchronized from external sources).

### 📂 Support Directories
-   **`/docs`**: Project vision, technical specifications, and guides.
-   **`/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)
-   **Mobile:** Flutter
-   **Backend:** Firebase (Data Connect, Auth, Hosting, Functions)
-   **Database:** PostgreSQL (managed via Cloud SQL & Data Connect)
-   **Infrastructure:** Google Cloud Platform (GCP)

## 📦 Getting Started

This project uses a modular `Makefile` for all common tasks.

1.  **View available commands:**
    ```bash
    make help
    ```

2.  **Install dependencies (Web):**
    ```bash
    make install
    ```

3.  **Run the Web Dashboard locally:**
    ```bash
    make dev
    ```

4.  **Run the DevOps Launchpad locally:**
    ```bash
    make launchpad-dev
    ```

5.  **Mobile app development:**
    ```bash
    make mobile-install
    make mobile-client-dev-android [DEVICE=android]
    make mobile-staff-dev-android [DEVICE=android]
    ```

## 🚀 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/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.

---
© 2026 KROW Workforce / Oloodi Technologies Inc.