From 969bc13939d0726d2b3cb53257412e74c6349206 Mon Sep 17 00:00:00 2001
From: bwnyasse <5323628+bwnyasse@users.noreply.github.com>
Date: Sat, 10 Jan 2026 23:04:36 -0500
Subject: [PATCH] feat: add documentation for synchronizing prototypes and
 script to automate the process

This commit introduces a new document explaining how to synchronize visual prototypes and POCs into the monorepo.
It also adds a script to automate the process of building and copying the prototype files into the `internal/launchpad/prototypes/web/` directory.
The documentation explains the benefits of synchronizing prototypes, the prerequisites, and the steps to synchronize them.
The script automates the process of installing dependencies, building the web application, and copying the resulting `dist/` folder into the `internal/launchpad/prototypes/web/` directory.
This allows developers to easily synchronize prototypes and make them available for local preview and deployment.
---
 docs/04-sync-prototypes.md | 58 ++++++++++++++++++++++++++++++++++++++
 scripts/sync-prototypes.sh | 56 ++++++++++++++++++++++++++++++++++++
 2 files changed, 114 insertions(+)
 create mode 100644 docs/04-sync-prototypes.md
 create mode 100755 scripts/sync-prototypes.sh

diff --git a/docs/04-sync-prototypes.md b/docs/04-sync-prototypes.md
new file mode 100644
index 00000000..31d50cdd
--- /dev/null
+++ b/docs/04-sync-prototypes.md
@@ -0,0 +1,58 @@
+# Synchronization of Prototypes
+
+This document explains how to synchronize visual prototypes and POCs (Proof of Concept) into this monorepo.
+
+## Overview
+
+Prototypes are developed in separate repositories (e.g., `client-krow-poc`). To keep this main repository clean and focused on production code, we do not commit the build artifacts of these prototypes. Instead, we use a synchronization script to bring them in locally.
+
+**Key benefits:**
+1.  **AI Context:** Once synced, AI tools (like Gemini) can read the prototype code to understand the intended UI/UX and logic.
+2.  **Local Preview:** You can view the prototypes directly through the **DevOps Launchpad**.
+3.  **Local Deployment:** Allows you to deploy the latest prototypes to Firebase Hosting from your machine.
+
+## Prerequisites
+
+The synchronization script assumes that the prototype repository is cloned **adjacent** to this project directory.
+
+```bash
+# Navigate to your workspace root
+cd ..
+# Clone the POC repository
+git clone git@github.com:Oloodi/client-krow-poc.git
+```
+
+Your folder structure should look like this:
+```
+/workspace
+  ├── krow-workforce-web (This repo)
+  └── client-krow-poc    (POC repo)
+```
+
+## How to Synchronize
+
+Run the following command from the root of this repository:
+
+```bash
+make sync-prototypes
+```
+
+**What this command does:**
+1.  Navigates to the adjacent `client-krow-poc` repository.
+2.  Installs dependencies (via `pnpm`).
+3.  Builds the web application (`pnpm run build`).
+4.  Copies the resulting `dist/` folder into `internal/launchpad/prototypes/web/`.
+
+## Git & AI Behavior
+
+*   **Git:** The contents of the `prototypes/` directories are defined in `.gitignore`. They will **not** be committed to this repository.
+*   **Gemini/AI:** These files are **not** ignored in `.geminiignore`. Once you run the sync script, the AI will be able to "see" the code and use it as a reference for your tasks.
+
+## Deployment to Hosting
+
+If you want to make these prototypes available on the live DevOps Launchpad (`launchpad.krowwithus.com`), you must:
+1.  Run `make sync-prototypes` on your local machine.
+2.  Run `make deploy-launchpad-hosting`.
+
+---
+*Note: As we add mobile prototypes (Flutter), this guide and the script will be updated to include the `flutter build web` steps.*
diff --git a/scripts/sync-prototypes.sh b/scripts/sync-prototypes.sh
new file mode 100755
index 00000000..764c6516
--- /dev/null
+++ b/scripts/sync-prototypes.sh
@@ -0,0 +1,56 @@
+#!/bin/bash
+set -e
+
+# Configuration - Paths relative to project root
+POC_REPO_PATH="../client-krow-poc"
+WEB_POC_SOURCE="$POC_REPO_PATH/prototypes/web/krow_web_application"
+WEB_DEST="internal/launchpad/prototypes/web"
+
+# Colors
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}🚀 Starting Prototypes Synchronization...${NC}"
+
+# Check if POC repo exists
+if [ ! -d "$POC_REPO_PATH" ]; then
+    echo -e "${RED}❌ Error: POC repository not found at $POC_REPO_PATH${NC}"
+    echo "Please clone the repository adjacent to this one:"
+    echo "  cd .. && git clone git@github.com:Oloodi/client-krow-poc.git"
+    exit 1
+fi
+
+# --- Sync Web Dashboard ---
+echo -e "${BLUE}📦 Building Web Dashboard Prototype...${NC}"
+if [ -d "$WEB_POC_SOURCE" ]; then
+    cd "$WEB_POC_SOURCE"
+    
+    echo "  -> Installing dependencies..."
+    pnpm install --silent
+    
+    echo "  -> Building dist..."
+    pnpm run build
+    
+    # Go back to project root
+    cd - > /dev/null
+    
+    echo "  -> Deploying to Launchpad..."
+    # Ensure destination exists and is clean (remove old files but keep .keep if needed, though usually we wipe for a clean build)
+    rm -rf "$WEB_DEST"/*
+    mkdir -p "$WEB_DEST"
+    
+    # Copy build artifacts
+    cp -R "$WEB_POC_SOURCE/dist/"* "$WEB_DEST/"
+    
+    echo -e "${GREEN}✅ Web Dashboard synced successfully.${NC}"
+else
+    echo -e "${RED}⚠️  Warning: Web POC source directory not found at $WEB_POC_SOURCE${NC}"
+fi
+
+# --- Future: Sync Mobile Prototypes ---
+# Add logic here when mobile prototypes are ready to be built for web (Flutter Web)
+
+echo -e "${GREEN}🎉 Synchronization complete!${NC}"
+echo "You can now verify the prototypes in internal/launchpad/prototypes/ and commit the changes."