Add PR preview cleanup workflow for frontend

.github/workflows/cleanup-pr-preview-frontend.yml

@@ -0,0 +1,40 @@
+# =============================================================================
+# Frontend PR Preview Cleanup Overlay Workflow
+# =============================================================================
+# Purpose: Trigger cleanup when frontend PRs are closed/merged
+# Calls: refactor-platform-rs/cleanup-pr-preview.yml (reusable workflow)
+# =============================================================================
+
+name: Cleanup PR Preview (Frontend)
+
+on:
+  pull_request:
+    # Trigger on PR close (includes merge)
+    types: [closed]
+
+permissions:
+  contents: read
+  packages: write
+  pull-requests: write
+
+jobs:
+  # ===========================================================================
+  # JOB: Call reusable cleanup workflow from backend repo
+  # ===========================================================================
+  cleanup-frontend-pr:
+    name: Cleanup Frontend PR Preview
+    # Call the reusable workflow from backend repository
+    uses: refactor-group/refactor-platform-rs/.github/workflows/cleanup-pr-preview.yml@190-add-a-staging-environment-for-previewing-and-testing-ahead-of-a-new-deployment
+    with:
+      # This is a frontend PR cleanup
+      repo_type: 'frontend'
+      # PR number to cleanup
+      pr_number: ${{ github.event.pull_request.number }}
+      # Branch name for image identification
+      branch_name: ${{ github.head_ref }}
+    secrets: inherit
+    # =========================================================================
+    # NO SECRETS NEEDED!
+    # =========================================================================
+    # The reusable workflow uses the backend repo's pr-preview environment
+    # which contains all necessary secrets for cleanup.

.github/workflows/pr-preview-frontend.yml

@@ -0,0 +1,68 @@
+# =============================================================================
+# Frontend PR Preview Overlay Workflow
+# =============================================================================
+# Purpose: Trigger PR preview deployments when frontend PRs are opened/updated
+# Strategy: Build frontend from PR branch, use main-arm64 backend image
+# Calls: refactor-platform-rs/ci-deploy-pr-preview.yml (reusable workflow)
+# =============================================================================
+
+name: PR Preview (Frontend)
+
+on:
+  pull_request:
+    # Trigger on PR lifecycle events
+    types: [opened, synchronize, reopened]
+    # Only run for frontend code changes
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - '.github/**'
+      - '!.github/workflows/pr-preview-frontend.yml'
+      - '!.github/workflows/cleanup-pr-preview-frontend.yml'
+
+# Prevent multiple deployments for the same PR
+concurrency:
+  group: pr-preview-frontend-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  packages: write
+  pull-requests: write
+  attestations: write
+  id-token: write
+
+jobs:
+  # ===========================================================================
+  # JOB: Call reusable workflow with frontend-specific configuration
+  # ===========================================================================
+  deploy-frontend-pr:
+    name: Deploy Frontend PR Preview
+    # Call the reusable workflow from backend repository
+    # TODO: After backend PR #201 merges, update both:
+    #   - uses: line to @main (instead of branch name)
+    #   - backend_branch: to 'main' (instead of PR branch)
+    uses: refactor-group/refactor-platform-rs/.github/workflows/ci-deploy-pr-preview.yml@190-add-a-staging-environment-for-previewing-and-testing-ahead-of-a-new-deployment
+    with:
+      # This is a frontend PR deployment
+      repo_type: 'frontend'
+      # Use the PR number for port allocation and naming
+      pr_number: ${{ github.event.pull_request.number }}
+      # Build frontend from this PR's branch
+      branch_name: ${{ github.head_ref }}
+      # TEMPORARY: Use backend PR branch until #201 merges (compose file exists there)
+      # After merge: Change back to 'main'
+      backend_branch: '190-add-a-staging-environment-for-previewing-and-testing-ahead-of-a-new-deployment'
+      # Optional: override with specific image tags if needed
+      # backend_image: ''  # Leave empty to use main-arm64
+      # frontend_image: '' # Leave empty to build from PR branch
+      # Optional: force complete rebuild
+      force_rebuild: false
+    # =========================================================================
+    # SECRETS - Resolved from backend repo's pr-preview environment
+    # =========================================================================
+    # The reusable workflow (defined in backend repo) uses 'environment: pr-preview'
+    # which resolves to the BACKEND repo's pr-preview environment, not the frontend's.
+    # All secrets are consolidated in the backend repo's pr-preview environment.
+    # We use 'secrets: inherit' to pass GITHUB_TOKEN for cross-repo operations.
+    secrets: inherit

README.md

@@ -156,3 +156,19 @@ All tests should pass before merging code. The test suite is designed to:
 For more detailed testing information, see [docs/testing/frontend-testing-strategy.md](./docs/testing/frontend-testing-strategy.md).
 
 #### For Working with and Running the Application in Docker, navigate to the [Container-README](./docs/runbooks/Container-README.md)
+
+---
+
+## PR Preview Environments
+
+This repository automatically deploys **isolated preview environments** for each pull request. When you open a PR, a complete stack (backend + frontend + database) deploys to a dedicated server on our Tailnet for testing before merge.
+
+**What happens automatically:**
+
+- ✅ PR opened → Environment deploys
+- ✅ New commits → Environment updates
+- ✅ PR closed/merged → Environment cleans up
+
+**Access:** Requires Tailscale VPN connection. Access URLs are posted as a comment on your PR in the GitHub Web UI.
+
+For detailed information, see the [PR Preview Environments Runbook](docs/runbooks/pr-preview-environments.md).

docs/runbooks/pr-preview-environments.md

@@ -0,0 +1,115 @@
+# PR Preview Environments - Developer Guide
+
+This guide explains how to use automatic PR preview environments for the Refactor Platform.
+
+## 🚀 Quick Start
+
+**Open a PR = Get a live preview environment automatically!**
+
+Every PR in `refactor-platform-rs` (backend) or `refactor-platform-fe` (frontend) triggers an automatic deployment of a full-stack preview environment.
+
+### What Happens When You Open a PR
+
+1. ✅ **Automatic deployment** starts (~5-10 min for first build)
+2. ✅ **Full stack** deployed: Postgres + Backend + Frontend  
+3. ✅ **Unique ports** assigned based on PR number
+4. ✅ **PR comment** posted with access URLs
+5. ✅ **Auto-cleanup** when PR closes/merges
+
+### Access Your Preview
+
+After deployment completes, check the PR comment for your URLs:
+
+```
+🚀 PR Preview Environment Deployed!
+
+Frontend: http://rpi5-hostname:3042
+Backend:  http://rpi5-hostname:4042  
+Health:   http://rpi5-hostname:4042/health
+
+Ports: Frontend: 3042 | Backend: 4042 | Postgres: 5474
+```
+
+**Requirements:**
+- 🔐 Must be connected to Tailscale VPN
+
+---
+
+## 📖 Full Documentation
+
+For complete documentation including troubleshooting, advanced usage, and monitoring:
+
+👉 **See: [Backend Repo PR Preview Runbook](https://github.com/refactor-group/refactor-platform-rs/blob/main/docs/runbooks/pr-preview-environments.md)**
+
+The complete runbook covers:
+- Port allocation formula
+- Deployment architecture
+- Testing & debugging
+- Manual cleanup procedures
+- Advanced configuration options
+- Security considerations
+
+---
+
+## 🎯 Quick Reference
+
+### Port Formula
+
+| Service | Formula | Example (PR #42) |
+|---------|---------|------------------|
+| Frontend | 3000 + PR# | 3042 |
+| Backend | 4000 + PR# | 4042 |
+| Postgres | 5432 + PR# | 5474 |
+
+### Common Commands
+
+**Health check:**
+```bash
+curl http://rpi5-hostname:4042/health
+```
+
+**View logs:**
+```bash
+ssh user@rpi5-hostname
+docker logs pr-42-frontend-1 -f
+docker logs pr-42-backend-1 -f
+```
+
+**Check status:**
+```bash
+ssh user@rpi5-hostname
+docker compose -p pr-42 ps
+```
+
+---
+
+## 🔧 How Frontend PRs Work
+
+When you open a frontend PR:
+1. **Frontend:** Builds from your PR branch 📦
+2. **Backend:** Uses main-arm64 image (or builds if missing)
+3. **Deploy:** Full stack with your frontend changes
+
+**No secrets needed in frontend repo!** All configuration is managed centrally in the backend repo's `pr-preview` environment.
+
+---
+
+## 🐛 Troubleshooting
+
+**Deployment failed?**
+- Check workflow logs: PR → "Checks" tab → View failed workflow
+- Common: Lint errors, test failures, build errors
+
+**Can't access preview?**
+- Verify Tailscale: `tailscale status`
+- Check correct port from PR comment
+- Ensure workflow succeeded
+
+**Need help?**
+- Check full runbook (linked above)
+- Ask in #engineering Slack
+- Open an issue
+
+---
+
+**Happy Testing! 🚀**