botserver/web/desktop/README.md

General Bots Desktop

A modern, themeable desktop web application for AI-powered workspace featuring Chat, Drive, Tasks, and Mail modules.

🎨 Features

• Modern UI/UX: Glass morphism effects, smooth animations, and responsive design
• Theme System: 19+ built-in themes with HSL-based customization
• Modular Architecture: Pluggable sections (Chat, Drive, Tasks, Mail)
• Real-time Communication: WebSocket-based chat with LiveKit integration
• Accessibility: ARIA labels, keyboard navigation, screen reader support
• Performance: Lazy loading, section caching, optimized animations
• Responsive: Works on desktop, tablet, and mobile devices

🚀 Quick Start

Prerequisites

• Modern web browser (Chrome 88+, Firefox 89+, Safari 14+)
• Web server (Apache, Nginx, or development server)

Installation

1. Clone or download the project
2. Serve the web/desktop directory through a web server
3. Navigate to http://localhost/desktop/ (or your server URL)

Development Server

# Using Python
cd web/desktop
python -m http.server 8000

# Using Node.js
npx http-server -p 8000

# Using PHP
php -S localhost:8000

Then open http://localhost:8000 in your browser.

📁 Project Structure

desktop/
├── index.html              # Main entry point
├── README.md              # This file
├── THEMES.md              # Theme system documentation
│
├── css/
│   └── app.css            # Core styles and theme bridge
│
├── js/
│   ├── theme-manager.js   # Theme switching logic
│   └── layout.js          # Section loading and navigation
│
├── public/
│   └── themes/            # Theme CSS files
│       ├── orange.css
│       ├── cyberpunk.css
│       ├── retrowave.css
│       └── ... (16 more themes)
│
├── chat/
│   ├── chat.html          # Chat UI
│   ├── chat.css           # Chat styles
│   └── chat.js            # Chat logic
│
├── drive/
│   ├── drive.html         # Drive UI
│   ├── drive.css          # Drive styles
│   └── drive.js           # Drive logic
│
├── tasks/
│   ├── tasks.html         # Tasks UI
│   ├── tasks.css          # Tasks styles
│   └── tasks.js           # Tasks logic
│
└── mail/
    ├── mail.html          # Mail UI
    ├── mail.css           # Mail styles
    └── mail.js            # Mail logic

🎨 Theme System

The application uses a sophisticated HSL-based theme system that allows for dynamic theme switching without page reloads.

Using Themes

1. Click the theme dropdown in the header
2. Select from 19+ available themes
3. Theme preference is saved to localStorage

Available Themes

• Default - Clean, modern light theme
• Orange - Office-inspired orange palette
• Cyberpunk - Neon cyberpunk aesthetic
• Retrowave - 80s synthwave vibes
• Vapor Dream - Vaporwave aesthetic
• Y2K Glow - Y2K-era design
• 3D Bevel - Classic 3D beveled look
• Arcade Flash - Retro arcade style
• Disco Fever - 70s disco aesthetic
• Grunge Era - 90s grunge style
• Jazz Age - Art deco inspired
• Mellow Gold - Warm, mellow tones
• Mid Century Modern - 50s/60s design
• Polaroid Memories - Vintage photo aesthetic
• Saturday Cartoons - Bright, playful colors
• Seaside Postcard - Beach-inspired palette
• Typewriter - Classic typewriter look
• Xerox UI - Office copier aesthetic
• XTree Gold - DOS file manager tribute

Creating Custom Themes

See THEMES.md for detailed documentation on creating and customizing themes.

⌨️ Keyboard Shortcuts

• Alt + 1 - Switch to Chat
• Alt + 2 - Switch to Drive
• Alt + 3 - Switch to Tasks
• Alt + 4 - Switch to Mail
• Esc - Close open menus/dropdowns
• Enter/Space - Activate focused element

🧩 Modules

Chat

Real-time chat interface with:

• WebSocket communication
• Markdown support
• Voice input (optional)
• Message history
• Typing indicators
• Connection status

Drive

File management system with:

• File upload/download
• Folder navigation
• File preview
• Search functionality
• Sorting and filtering

Tasks

Task management with:

• Create/edit/delete tasks
• Task prioritization
• Due dates
• Categories/tags
• Completion tracking

Mail

Email interface with:

• Inbox/sent/drafts
• Compose messages
• Rich text editing
• Attachments
• Search and filters

🎯 Architecture

Theme System

The theme system uses a two-layer architecture:

1. Base HSL Variables - Defined in theme files
2. Working Variables - Automatically derived in app.css

Example:

/* Base variable (in theme file) */
--primary: 217 91% 60%;

/* Working variable (auto-derived) */
--accent-color: hsl(var(--primary));
--accent-light: hsla(var(--primary) / 0.1);

Section Loading

Sections are loaded dynamically:

1. User clicks app icon or uses keyboard shortcut
2. layout.js loads HTML, CSS, and JS for the section
3. Section content is cached for fast switching
4. Alpine.js components are initialized (for Drive, Tasks, Mail)
5. Chat uses custom WebSocket logic

State Management

• Theme preference: localStorage.getItem('gb-theme')
• Section cache: In-memory JavaScript object
• WebSocket connections: Managed per section

🔧 Configuration

Theme Configuration

Edit js/theme-manager.js to add/remove themes:

const themes = [
  { id: "default", name: "🎨 Default", file: null },
  { id: "mytheme", name: "🌟 My Theme", file: "mytheme.css" }
];

Section Configuration

Edit js/layout.js to add/remove sections:

const sections = {
  chat: "chat/chat.html",
  mysection: "mysection/mysection.html"
};

🎨 Styling Guidelines

Using Theme Variables

Always use theme variables for colors:

/* ✅ Good */
.my-component {
  background: var(--primary-bg);
  color: var(--text-primary);
  border: 1px solid var(--border-color);
}

/* ❌ Bad */
.my-component {
  background: #ffffff;
  color: #000000;
  border: 1px solid #cccccc;
}

Responsive Breakpoints

/* Mobile */
@media (max-width: 480px) { }

/* Tablet */
@media (max-width: 768px) { }

/* Desktop */
@media (min-width: 769px) { }

🧪 Testing

Browser Testing

Test on:

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)
• Mobile browsers

Theme Testing

1. Switch to each theme
2. Navigate to all sections
3. Test interactive elements
4. Verify contrast ratios
5. Check accessibility

Accessibility Testing

• Use screen reader (NVDA, JAWS, VoiceOver)
• Navigate with keyboard only
• Test with high contrast mode
• Verify ARIA labels

🐛 Troubleshooting

Themes Not Loading

1. Check browser console for errors
2. Verify theme file exists in public/themes/
3. Clear browser cache
4. Check theme file syntax

Sections Not Switching

1. Check console for JavaScript errors
2. Verify section files exist
3. Check network tab for failed requests
4. Clear localStorage

WebSocket Connection Issues

1. Check server is running
2. Verify WebSocket URL
3. Check browser console
4. Test network connectivity

📊 Performance

Optimization Techniques

• Lazy Loading: Sections loaded on demand
• Caching: Section HTML/CSS/JS cached after first load
• CSS Variables: Fast theme switching without reflow
• Debouncing: Input handlers debounced
• Animations: GPU-accelerated with transform and opacity

Performance Metrics

• Initial load: < 1s
• Theme switch: < 100ms
• Section switch: < 200ms (cached), < 500ms (first load)
• Animation: 60 FPS target

🔒 Security

Best Practices

• No inline event handlers
• CSP-friendly code
• XSS protection in chat
• Sanitized user input
• Secure WebSocket connections (WSS in production)

Content Security Policy

Recommended CSP header:

Content-Security-Policy: 
  default-src 'self'; 
  script-src 'self' https://cdnjs.cloudflare.com https://cdn.jsdelivr.net https://unpkg.com; 
  style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; 
  font-src https://fonts.gstatic.com;

🤝 Contributing

Adding a New Theme

1. Create public/themes/mytheme.css
2. Define HSL variables (see THEMES.md)
3. Add to js/theme-manager.js
4. Test thoroughly
5. Submit pull request

Adding a New Section

1. Create directory: mysection/
2. Add files: mysection.html, mysection.css, mysection.js
3. Register in js/layout.js
4. Add icon to apps menu in index.html
5. Test integration
6. Update documentation

📝 API Reference

ThemeManager

// Initialize
ThemeManager.init();

// Load theme
ThemeManager.loadTheme('cyberpunk');

// Subscribe to changes
ThemeManager.subscribe((data) => {
  console.log(data.themeId, data.themeName);
});

// Get themes
const themes = ThemeManager.getAvailableThemes();

Layout Manager

// Switch section
window.switchSection('chat');

// Get current section
const section = window.location.hash.substring(1);

🔄 Version History

v1.0.0 (Current)

• Initial release
• 19 built-in themes
• 4 core modules (Chat, Drive, Tasks, Mail)
• HSL-based theme system
• Keyboard shortcuts
• Accessibility improvements

📄 License

See project root for license information.

🙋 Support

For issues, questions, or contributions:

• Check documentation in THEMES.md
• Review browser console for errors
• Test with different browsers/themes
• Contact General Bots team

🌟 Acknowledgments

• shadcn/ui - Theme variable inspiration
• Alpine.js - Reactive components
• GSAP - Smooth animations
• LiveKit - Real-time communication
• marked - Markdown parsing

---

Built with ❤️ by the General Bots Team