bolt-diy/MULTIUSER_DOCUMENTATION.md

🚀 bolt.diy Multi-User System Documentation

Developer: Keoma Wright
Version: 1.0.0
Date: 27 August 2025

📋 Table of Contents

1. Overview
2. Architecture
3. Features
4. Installation & Setup
5. User Guide
6. Admin Guide
7. Security
8. API Reference
9. Technical Details
10. Troubleshooting

Overview

The bolt.diy Multi-User System transforms the single-user bolt.diy application into a comprehensive multi-user platform with isolated workspaces, personalized settings, and robust user management - all without requiring a traditional database.

Key Highlights

• ✅ No Database Required - File-based storage system
• ✅ Isolated Workspaces - Each user has their own chat history and projects
• ✅ Beautiful UI - Stunning login/signup pages with glassmorphism design
• ✅ Avatar Support - Users can upload custom avatars
• ✅ Admin Panel - Comprehensive user management interface
• ✅ Security - JWT authentication with bcrypt password hashing
• ✅ Personalized Experience - Custom greetings and user preferences

Architecture

System Components

┌─────────────────────────────────────────────────┐
│                   Frontend                        │
├─────────────────────────────────────────────────┤
│  Authentication Pages  │  Protected Routes        │
│  - Login/Signup       │  - Chat Interface        │
│  - Avatar Upload      │  - User Management       │
│                       │  - Settings              │
├─────────────────────────────────────────────────┤
│                Authentication Layer               │
│  - JWT Tokens         │  - Session Management    │
│  - Auth Store         │  - Protected HOCs        │
├─────────────────────────────────────────────────┤
│                 Storage Layer                     │
│  File-Based Storage   │  User-Specific DBs       │
│  - .users/           │  - IndexedDB per user    │
│  - Security logs     │  - Isolated workspaces   │
└─────────────────────────────────────────────────┘

File Structure

/root/bolt/
├── .users/                          # User data directory (secured)
│   ├── users.json                   # User registry
│   ├── security.log                 # Security audit logs
│   └── data/                        # User-specific data
│       └── {userId}/                # Individual user directories
├── app/
│   ├── components/
│   │   ├── auth/
│   │   │   ├── LoginForm.tsx
│   │   │   ├── SignupForm.tsx
│   │   │   └── ProtectedRoute.tsx
│   │   ├── chat/
│   │   │   ├── AuthenticatedChat.tsx
│   │   │   └── WelcomeMessage.tsx
│   │   ├── header/
│   │   │   └── UserMenu.tsx
│   │   └── admin/
│   │       └── UserManager.tsx
│   ├── lib/
│   │   ├── stores/
│   │   │   └── auth.ts
│   │   ├── utils/
│   │   │   ├── crypto.ts
│   │   │   └── fileUserStorage.ts
│   │   └── persistence/
│   │       └── userDb.ts
│   └── routes/
│       ├── auth.tsx
│       ├── admin.users.tsx
│       └── api.auth.*.ts

Features

🔐 Authentication System

Login Page

• Beautiful gradient animated background
• Glassmorphism card design
• Remember me functionality (7-day sessions)
• Smooth tab transitions between login/signup
• Real-time validation feedback

Signup Page

• Avatar upload with preview
• Password strength indicator
• First name for personalization
• Username validation
• Animated form transitions

👤 User Management

User Profile

• Unique user ID generation
• Avatar storage as base64
• Preferences storage
• Last login tracking
• Creation date tracking

Admin Panel

• User grid with search
• User statistics dashboard
• Delete user with confirmation
• Edit user capabilities
• Activity monitoring

💬 Personalized Chat Experience

Welcome Message

• Personalized greeting: "{First Name}, What would you like to build today?"
• Time-based greetings (morning/afternoon/evening)
• User statistics display
• Example prompts

Chat History Isolation

• User-specific IndexedDB
• Isolated chat sessions
• Personal workspace files
• Settings per user

🎨 UI/UX Enhancements

Design Elements

• Glassmorphism effects
• Animated gradients
• Smooth transitions (Framer Motion)
• Dark/light theme support
• Responsive design

User Menu

• Avatar display
• Quick access to settings
• User management link
• Sign out option
• Member since date

Installation & Setup

Prerequisites

# Required packages
pnpm add bcryptjs jsonwebtoken
pnpm add -D @types/bcryptjs @types/jsonwebtoken

Initial Setup

1. Create user directory

mkdir -p .users
chmod 700 .users

2. Environment Variables

JWT_SECRET=your-secure-secret-key-here

3. Start the application

pnpm run dev

4. Access the application Navigate to http://localhost:5173/auth to create your first account.

User Guide

Getting Started

1. Create an Account

   • Navigate to /auth
   • Click "Sign Up" tab
   • Upload an avatar (optional)
   • Enter your details
   • Create a strong password

2. Login

   • Enter username and password
   • Check "Remember me" for persistent sessions
   • Click "Sign In"

3. Using the Chat

   • Personalized greeting appears
   • Your chat history is private
   • Settings are saved per user

4. Managing Your Profile

   • Click your avatar in the header
   • Access settings
   • View member information

Admin Guide

User Management

1. Access Admin Panel

   • Click user menu → "Manage Users"
   • Or navigate to /admin/users

2. View Users

   • See all registered users
   • View statistics
   • Search and filter

3. Delete Users

   • Click trash icon
   • Confirm deletion
   • User data is permanently removed

4. Monitor Activity

   • Check security logs
   • View last login times
   • Track user creation

Security Logs

Security events are logged to .users/security.log:

• Login attempts (successful/failed)
• User creation
• User deletion
• Errors

Example log entry:

{
  "timestamp": "2024-12-27T10:30:45.123Z",
  "userId": "user_123456_abc",
  "username": "john_doe",
  "action": "login",
  "details": "Successful login",
  "ip": "192.168.1.1"
}

Security

Password Security

• Bcrypt hashing with salt rounds
• Complexity requirements:
  • Minimum 8 characters
  • At least one uppercase letter
  • At least one lowercase letter
  • At least one number

Session Management

• JWT tokens with expiration
• 7-day session option
• Automatic logout on expiration
• Secure cookie storage

File Permissions

• .users/ directory: 700 (owner only)
• User data files: JSON format
• Security logs: Append-only

Best Practices

• Never store plain passwords
• Use environment variables for secrets
• Regular security log reviews
• Implement rate limiting (future)

API Reference

Authentication Endpoints

POST /api/auth/login

Request: {
  username: string;
  password: string;
}

Response: {
  success: boolean;
  user?: UserProfile;
  token?: string;
  error?: string;
}

POST /api/auth/signup

Request: {
  username: string;
  password: string;
  firstName: string;
  avatar?: string;
}

Response: {
  success: boolean;
  user?: UserProfile;
  token?: string;
  error?: string;
}

POST /api/auth/logout

Headers: {
  Authorization: "Bearer {token}"
}

Response: {
  success: boolean;
}

POST /api/auth/verify

Headers: {
  Authorization: "Bearer {token}"
}

Response: {
  success: boolean;
  user?: UserProfile;
}

User Management Endpoints

GET /api/users

Get all users (requires authentication)

DELETE /api/users/:id

Delete a specific user (requires authentication)

Technical Details

Storage System

User Registry (users.json)

{
  "users": [
    {
      "id": "user_123456_abc",
      "username": "john_doe",
      "firstName": "John",
      "passwordHash": "$2a$10$...",
      "avatar": "data:image/png;base64,...",
      "createdAt": "2024-12-27T10:00:00.000Z",
      "lastLogin": "2024-12-27T15:30:00.000Z",
      "preferences": {
        "theme": "dark",
        "deploySettings": {},
        "githubSettings": {},
        "workspaceConfig": {}
      }
    }
  ]
}

User-Specific IndexedDB

Each user has their own database: boltHistory_{userId}

• Chats store
• Snapshots store
• Settings store
• Workspaces store

Authentication Flow

sequenceDiagram
    User->>Frontend: Enter credentials
    Frontend->>API: POST /api/auth/login
    API->>FileStorage: Verify user
    API->>Crypto: Verify password
    API->>Crypto: Generate JWT
    API->>SecurityLog: Log attempt
    API->>Frontend: Return token + user
    Frontend->>AuthStore: Save state
    Frontend->>Cookie: Store token
    Frontend->>Chat: Redirect to chat

Workspace Isolation

Each user's workspace is completely isolated:

1. Chat History - Stored in user-specific IndexedDB
2. Settings - LocalStorage with user prefix
3. Files - Virtual file system per user
4. Deploy Settings - User-specific configurations

Troubleshooting

Common Issues

Cannot Login

• Verify username/password
• Check security logs
• Ensure .users/ directory exists

Session Expired

• Re-login required
• Use "Remember me" for longer sessions

User Data Not Loading

• Check browser IndexedDB
• Verify user ID in auth store
• Clear browser cache if needed

Avatar Not Displaying

• Check file size (max 2MB recommended)
• Verify base64 encoding
• Test with different image formats

Debug Mode

Enable debug logging:

// In browser console
localStorage.setItem('DEBUG', 'true');

View security logs:

tail -f .users/security.log

Recovery

Reset User Password

Currently requires manual intervention:

1. Generate new hash using bcrypt
2. Update users.json
3. Restart application

Restore Deleted User

If backup exists:

1. Restore from users.json backup
2. Recreate user data directory
3. Restore IndexedDB if available

Future Enhancements

Planned Features

• Password reset via email
• Two-factor authentication
• User roles and permissions
• Team workspaces
• Usage analytics
• Export/import user data
• Social login integration
• Rate limiting
• Session management UI
• Audit trail viewer

Performance Optimizations

• Database indexing strategies
• Lazy loading user data
• Caching layer
• CDN for avatars

Contributing

This system was developed by Keoma Wright as an enhancement to the bolt.diy project.

Development Guidelines

1. Maintain backward compatibility
2. Follow existing code patterns
3. Add tests for new features
4. Update documentation
5. Consider security implications

Testing

# Run tests
pnpm test

# Type checking
pnpm typecheck

# Linting
pnpm lint

License

This multi-user system is an extension of the bolt.diy project and follows the same license terms.

Credits

Developer: Keoma Wright
Project: bolt.diy Multi-User Edition
Year: 2025

---

This documentation provides a comprehensive guide to the bolt.diy Multi-User System. For questions or issues, please contact the developer or submit an issue to the repository.