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."