# Contributing to KROW Workforce Platform

Welcome to the KROW Workforce development team! This guide will help you get set up and understand our development practices.

---

## 🚀 Getting Started & Setup Checklist

Follow these steps to set up your development environment and gain access to all necessary resources.

1.  **Access Google Chat Space:**
    *   Ensure you have been invited to and joined our main Google Chat space for daily communication and quick questions.

2.  **GitHub Access & SSH Key:**
    *   Confirm you have read/write access to this GitHub repository.
    *   Configure your SSH key for GitHub. Ensure your commits are verified (GPG signing is recommended).

3.  **Install & Configure Gemini CLI:**
    *   Install the Gemini CLI on your local machine.
    *   Familiarize yourself with its usage for code assistance and documentation.

4.  **Install & Configure Enpass:**
    *   Install Enpass (our team's shared password manager).
    *   Ensure you have access to the shared KROW vault for all project credentials (API keys, service accounts, etc.).

5.  **Install Required Development Tools:**
    
    Before running the project, ensure you have the following installed:

    *   **Node.js (v20+):** We recommend using **[nvm](https://github.com/nvm-sh/nvm)** (Node Version Manager) to install and manage Node versions.
    *   **pnpm:** Our preferred package manager for JavaScript projects. (`npm install -g pnpm`)
    *   **Flutter Version Management (FVM):** We use **[FVM](https://fvm.app/)** to manage Flutter SDK versions per project. Install it via Homebrew (`brew install fvm`) or Dart (`dart pub global activate fvm`).
    *   **Firebase CLI:** Required for emulation and deployment. (`npm install -g firebase-tools`)
    *   **Google Cloud CLI (gcloud):** Required for backend authentication and resource management.

    **Recommended IDE:**
    *   **[Google Project IDX (Antigravity)](https://idx.google.com/)** or **VS Code**.
    *   **Essential Extensions:**
        *   Flutter & Dart
        *   Firebase
        *   Tailwind CSS IntelliSense
        *   ESLint & Prettier

    **Diagramming:**
    *   Use **MermaidChart.com** for creating and editing diagrams (Mermaid syntax).

6.  **Local Development Environment Setup:**
    *   Clone the monorepo: `git clone git@github.com:Oloodi/krow-workforce.git`
    *   Navigate to the project root: `cd krow-workforce`
    *   Install web frontend dependencies: `make install`

- **Install Git Hooks:**
    -   Run `make install-git-hooks` to set up local safeguards that prevent direct pushes to protected branches (`main` and `dev`). **This is a mandatory step.**

7.  **Firebase Project Access Validation:**
    *   Confirm you have access to the `dev` Firebase/GCP project.
    *   Verify you can run `firebase login` and `gcloud auth login` successfully.

8.  **Understand the Monorepo Structure:**
    *   Familiarize yourself with the project layout (`apps/`, `backend/`, `internal/`) as described in the main `README.md`.

---

## 💡 Development Guidelines

1.  **Branching Strategy:**
    *   We adopt a **feature branch workflow**. All code modifications must be done on a new branch.
    *   The `main` and `dev` branches are protected.

2.  **Commit Messages:**
    *   Use clear and descriptive commit messages (standardized via Open Commit if available).

3.  **Code Standards:**
    *   Adhere to existing code style, formatting, and architectural patterns found in the codebase.
    *   Run linters and formatters before committing.

4.  **Documentation:**
    *   Keep documentation up to date in the `docs/` directory.

5.  **Diagrams:**
    *   All diagrams should be created using **Mermaid syntax** and stored in Markdown files.

---

## 🔗 Useful Links

-   **KROW Internal Launchpad:** [https://launchpad.krowwithus.com](https://launchpad.krowwithus.com)
-   **Project Onboarding (Start Here):** [docs/05-project-onboarding-master.md](./05-project-onboarding-master.md) - Comprehensive guide covering architecture, domain logic, feature gap analysis, and development strategy
-   **Project Vision:** [docs/00-vision.md](./00-vision.md)
-   **Backend Specification (Legacy Reference):** [docs/01-backend-api-specification.md](./01-backend-api-specification.md) - Historical API spec from Digital Ocean stack
-   **Codemagic Env Vars:** [docs/02-codemagic-env-vars.md](./02-codemagic-env-vars.md)