blackroad-operating-system/web-client/README.md

BlackRoad Web Client (Pocket OS)

Version: 0.1.0 Status: Phase 2 Enhanced

Overview

The BlackRoad Web Client (codename: Pocket OS) is the browser-facing frontend for BlackRoad OS. It provides a Windows 95-inspired desktop interface powered by vanilla JavaScript with zero dependencies.

Architecture

web-client/
├── README.md               # This file
└── (Primary code is in backend/static/)

backend/static/
├── index.html              # Main OS interface
├── js/
│   ├── api-client.js       # Legacy API client
│   ├── core-os-client.js   # New Core OS client (Phase 2)
│   ├── apps.js             # Application definitions
│   └── auth.js             # Authentication
└── assets/
    ├── css/                # Stylesheets
    ├── images/             # Icons and images
    └── fonts/              # Custom fonts

Features

Phase 1 (Existing)

• ✅ Windows 95-style desktop UI
• ✅ Window management (drag, resize, minimize, maximize)
• ✅ Start menu and taskbar
• ✅ Multiple built-in applications
• ✅ Authentication system
• ✅ API integration

Phase 2 (New)

• ✅ Core OS Client (core-os-client.js)
• ✅ System version API integration
• ✅ Public config API integration
• ✅ OS state management client-side
• ✅ Event-driven architecture
• 🔄 Real-time state sync (coming soon)
• 🔄 WebSocket support (coming soon)

Quick Start

Running the Web Client

The web client is served by the FastAPI backend at /:

# Start backend
cd backend
uvicorn app.main:app --reload

# Visit http://localhost:8000/
# The OS interface loads automatically

Using Core OS Client

// Initialize Core OS
const result = await window.coreOS.initialize();
console.log('OS Version:', result.version);
console.log('OS Config:', result.config);
console.log('OS State:', result.state);

// Listen for state updates
window.coreOS.on('state:updated', (state) => {
  console.log('State changed:', state);
});

// Check backend health
const healthy = await window.coreOS.healthCheck();
console.log('Backend healthy:', healthy);

// Get system version
const version = await window.coreOS.getVersion();
console.log('System version:', version.version);

API Endpoints Used

The web client communicates with these backend endpoints:

• GET /health - Backend health check
• GET /api/system/version - System version and build info
• GET /api/system/config/public - Public configuration
• GET /api/system/os/state - Current OS state
• GET /api/auth/* - Authentication endpoints
• GET /api/agents/* - Agent library
• And 30+ other API endpoints for apps

Integration with Core OS Runtime

The web client integrates with the Core OS Runtime (Python) via HTTP API:

┌─────────────────────┐
│   Web Browser       │
│   (Pocket OS UI)    │
└──────────┬──────────┘
           │ HTTP/WebSocket
           ▼
┌─────────────────────┐
│   Backend API       │
│   (FastAPI)         │
└──────────┬──────────┘
           │ Python imports
           ▼
┌─────────────────────┐
│   Core OS Runtime   │
│   (Python)          │
└─────────────────────┘

File Structure

Main Entry Point

• backend/static/index.html - Main OS interface (97KB)
  • Includes complete Windows 95-style UI
  • Desktop with draggable icons
  • Taskbar with Start menu
  • System tray with clock
  • Multiple pre-built applications

JavaScript Modules

Legacy (Phase 1)

• api-client.js (11KB)

  • REST API client
  • Authentication helpers
  • Request/response handling

• apps.js (33KB)

  • Application definitions
  • Window management
  • App lifecycle hooks

• auth.js (11KB)

  • Login/logout
  • Session management
  • Token handling

New (Phase 2)

• core-os-client.js (2KB)
  • Core OS API integration
  • System state management
  • Event system
  • Health monitoring

Development Workflow

Making Changes

1. Edit files in backend/static/

   cd backend/static
   # Edit index.html or js/*.js
   

2. No build step required - Vanilla JS, direct changes

   # Just refresh browser!
   

3. Test locally

   cd backend
   uvicorn app.main:app --reload
   # Visit http://localhost:8000/
   

Adding a New Application

1. Define app in apps.js:

   window.Apps.MyNewApp = {
     init() {
       console.log('App initialized');
     },
   
     render() {
       return `
         <div class="app-content">
           <h1>My New App</h1>
         </div>
       `;
     }
   };
   

2. Add desktop icon in index.html:

   <div class="desktop-icon" data-app="mynewapp">
     <div class="icon-image">🎨</div>
     <div class="icon-label">My New App</div>
   </div>
   

3. Register in app system (if needed)

Using Core OS Client

Include in your HTML:

<script src="/static/js/core-os-client.js"></script>

Then use in your code:

// Auto-initialized as window.coreOS

// Initialize OS
coreOS.initialize().then(result => {
  console.log('OS ready!', result);
});

// Listen for events
coreOS.on('os:initialized', (data) => {
  console.log('OS initialized', data);
});

coreOS.on('state:updated', (state) => {
  console.log('State updated', state);
});

coreOS.on('os:error', (error) => {
  console.error('OS error', error);
});

Testing

Manual Testing

# Start backend
cd backend
uvicorn app.main:app --reload

# Open browser
# Visit http://localhost:8000/
# Test functionality manually

Automated Testing (Future)

# Phase 2 will add:
# - Playwright/Puppeteer tests
# - Visual regression tests
# - E2E tests

Browser Support

• ✅ Chrome 90+
• ✅ Firefox 88+
• ✅ Safari 14+
• ✅ Edge 90+

Performance

• Bundle size: ~140KB uncompressed
• Load time: <200ms on broadband
• Zero dependencies: No framework overhead
• Vanilla JS: Direct DOM manipulation

Phase 2 Enhancements

Current Phase 2 additions:

1. ✅ Core OS Client - New API client for system-level operations
2. ✅ System endpoints - /api/system/version, /api/system/config/public, /api/system/os/state
3. ✅ Event system - Client-side event bus for state changes
4. ✅ Health monitoring - Backend health check integration

Coming in Phase 2:

• 🔄 Real-time sync - WebSocket for live OS state updates
• 🔄 Offline support - Service worker for offline functionality
• 🔄 PWA features - Install as desktop app
• 🔄 Enhanced state management - Local state caching and sync

Integration with Other Modules

With Backend API

// Core OS client talks to backend
const version = await coreOS.getVersion();
// Calls: GET /api/system/version

With Operator Engine

// Future: Subscribe to job updates
coreOS.on('job:completed', (job) => {
  console.log('Job finished:', job);
});

With Prism Console

// Future: Admin mode toggle
if (config.admin_mode) {
  window.location.href = '/prism';
}

License

Part of BlackRoad Operating System - MIT License

---

Next Steps: Add WebSocket support, implement real-time state sync, create PWA manifest, add service worker for offline support.