Merge commit '9a5c1926a2fb6cc8b25f3c8b767b6df0808b39b4'

.github/workflows/ci.yml

@@ -11,6 +11,8 @@ jobs:
   validate:
     name: Validate HTML & JavaScript
     runs-on: ubuntu-latest
+    env:
+      UI_ENTRY: backend/static/index.html
 
     steps:
       - name: Checkout repository
@@ -25,6 +27,7 @@ jobs:
         run: |
           echo "🔍 Validating HTML structure..."
           python3 << 'EOF'
+          import os
           import sys
           import re
 
@@ -87,21 +90,25 @@ jobs:
                   print("\n✅ All validation checks passed!")
                   return True
 
-          # Validate index.html
+          # Validate canonical UI entrypoint
-          valid = validate_html('index.html')
+          target = os.environ.get('UI_ENTRY', 'backend/static/index.html')
+          valid = validate_html(target)
           sys.exit(0 if valid else 1)
           EOF
 
       - name: Check JavaScript syntax
         run: |
           echo "🔍 Checking JavaScript syntax..."
-          if [ -f "index.html" ]; then
+          if [ -f "$UI_ENTRY" ]; then
             # Extract and check JavaScript
             python3 << 'EOF'
+          import os
           import re
           import sys
 
-          with open('index.html', 'r') as f:
+          target = os.environ.get('UI_ENTRY', 'backend/static/index.html')
+
+          with open(target, 'r') as f:
               content = f.read()
 
           # Extract JavaScript code
@@ -146,26 +153,26 @@ jobs:
               sys.exit(0)
           EOF
           else
-            echo "ℹ️  No index.html found - skipping JS validation"
+            echo "ℹ️  No UI entrypoint found - skipping JS validation"
           fi
 
       - name: Check for common security issues
         run: |
           echo "🔒 Checking for security issues..."
-          if [ -f "index.html" ]; then
+          if [ -f "$UI_ENTRY" ]; then
             # Check for inline event handlers with user input (basic XSS check)
-            if grep -i "eval(" index.html; then
+            if grep -i "eval(" "$UI_ENTRY"; then
               echo "⚠️  Warning: Found eval() - potential security risk"
               # Not failing for this, just warning
             fi
 
-            if grep -i "innerHTML.*user" index.html; then
+            if grep -i "innerHTML.*user" "$UI_ENTRY"; then
               echo "⚠️  Warning: Found innerHTML with user input - potential XSS risk"
             fi
 
             echo "✅ Basic security checks completed"
           else
-            echo "ℹ️  No index.html found - skipping security checks"
+            echo "ℹ️  No UI entrypoint found - skipping security checks"
           fi
 
       - name: Validate README

.github/workflows/deploy.yml

@@ -37,10 +37,11 @@ jobs:
       - name: Setup Pages
         uses: actions/configure-pages@v4
 
-      - name: Upload artifact
+      - name: Upload canonical frontend
         uses: actions/upload-pages-artifact@v3
         with:
           path: './dist'
+          path: 'backend/static'
 
       - name: Deploy to GitHub Pages
         id: deployment

README.md

@@ -39,17 +39,25 @@ BlackRoad OS is a fully functional web-based operating system interface that bri
 
 ### Quick Start
 
-Simply open `index.html` in any modern web browser to launch BlackRoad OS.
+> 🔑 **Canonical UI entry point:** `backend/static/index.html`
+
+The desktop interface is bundled with the FastAPI backend so it can load data
+from the API without breaking features. Use the backend server (locally or in
+Railway/GoDaddy) to serve the UI instead of opening the HTML file directly.
 
 ```bash
 # Clone the repository
 git clone https://github.com/blackboxprogramming/BlackRoad-Operating-System.git
-
-# Navigate to the directory
 cd BlackRoad-Operating-System
 
-# Open in your browser
+# Start the FastAPI backend (serves backend/static/index.html)
-open index.html
+cd backend
+python -m venv .venv && source .venv/bin/activate  # optional but recommended
+pip install -r requirements.txt
+uvicorn app.main:app --reload
+
+# Visit the desktop UI
+# -> http://localhost:8000/ serves backend/static/index.html
 ```
 
 ### GitHub Pages / GoDaddy Deployment
@@ -63,6 +71,16 @@ To publish manually without the workflow:
 1. Copy the contents of `backend/static/` and any required root assets into a temporary folder (e.g., `dist/`).
 2. Upload that folder to your Pages or GoDaddy hosting destination.
 3. Keep the backend running on Railway so the static UI can communicate with the live services.
+For cloud deployments (Railway, GoDaddy, etc.), make sure that
+`backend/static/index.html` is the file exposed at `/` so the UI can talk to the
+API routes that live under `/api/*`.
+
+### GitHub Pages Deployment
+
+The GitHub Pages workflow publishes the canonical frontend from
+`backend/static/`. If you customize the UI, edit
+`backend/static/index.html` (and any supporting assets in that directory) so
+the validation and deploy jobs keep pointing at the same file.
 
 ## Architecture
 

backend/README.md

@@ -23,6 +23,9 @@ A comprehensive FastAPI backend for the BlackRoad Operating System, a Windows 95
 
 ## Quick Start
 
+> The desktop UI is bundled in `backend/static/index.html` and is served by the
+> FastAPI app at `http://localhost:8000/`.
+
 ### Prerequisites
 - Python 3.11+
 - Docker and Docker Compose
@@ -76,10 +79,16 @@ nano .env
 docker run -d -p 5432:5432 -e POSTGRES_USER=blackroad -e POSTGRES_PASSWORD=password -e POSTGRES_DB=blackroad_db postgres:15-alpine
 docker run -d -p 6379:6379 redis:7-alpine
 
-# Run the application
+# Run the application (serves backend/static/index.html at /)
 python run.py
 ```
 
+After either setup option finishes booting, browse to
+`http://localhost:8000/` to load the Windows 95 desktop that lives in
+`backend/static/index.html`. The API is available at `/api/*` from the same
+server, so no extra reverse proxying is required for local or hosted (Railway,
+GoDaddy, etc.) deployments.
+
 ### Configuration
 
 Edit the `.env` file to configure:

validate_html.py

@@ -2,6 +2,9 @@
 """HTML validator for BlackRoad OS"""
 import re
 import sys
+from pathlib import Path
+
+DEFAULT_INDEX = Path("backend/static/index.html")
 
 def validate_html(filename):
     errors = []
@@ -77,6 +80,6 @@ def validate_html(filename):
     return len(errors) == 0
 
 if __name__ == '__main__':
-    filename = sys.argv[1] if len(sys.argv) > 1 else 'index.html'
+    filename = sys.argv[1] if len(sys.argv) > 1 else str(DEFAULT_INDEX)
     valid = validate_html(filename)
     sys.exit(0 if valid else 1)