webOS-processMGR

A lightweight, full-stack process management system with real-time monitoring, intelligent task scheduling, and complete virtual OS environment

Experience desktop computing in your browser with dual-mode process monitoring, persistent file system, and advanced resource management

🔗 Links

🚀 Live Demo - Try it out!
🌐 Issues
🤝 Contributing
🛡️ Security
📜 License

📖 Abstract

webOS-processMGR is a lightweight, full-stack process management system that emulates a complete web-based operating system with real-time monitoring capabilities. Built with React (TypeScript) and FastAPI (Python), it provides:

🖥️ Virtual Desktop Environment: Complete OS emulation with boot sequence, login, draggable/resizable windows, taskbar, and persistent desktop state
📊 Dual Process Monitoring: Monitor both virtual OS processes and actual host system processes with real-time CPU/memory metrics
📁 Virtual File System: Full CRUD operations for files and folders with persistent MongoDB storage
🔐 Enterprise Security: JWT authentication, bcrypt password hashing, and role-based access control (RBAC)
⚡ Real-time Updates: WebSocket-powered live metrics streaming every 2 seconds
🤖 Intelligent Management: Smart task scheduling with priority queues and load-based optimization

The system combines the familiar desktop experience with powerful system monitoring tools, making it ideal for educational purposes, process visualization, and resource management demonstrations.

✨ Key Highlights

🚀 Lightweight Architecture - Efficient React + FastAPI stack with minimal dependencies
📊 Real-time Monitoring - Live CPU/Memory/Threads tracking with interactive charts (Recharts)
🔄 Smart Task Scheduling - Priority-based process queue management
🛡️ Resource Isolation - Process-level resource limits and isolation controls
🔍 Advanced Analytics - Historical data tracking and performance metrics
🤖 Auto-scaling - Intelligent load-based resource optimization
🎨 Modern UI/UX - Framer Motion animations with intuitive drag-and-drop interface
🔐 Security First - JWT authentication, bcrypt hashing, admin-only critical operations
📦 Docker Ready - Full Docker Compose setup for one-command deployment
🧩 Modular Design - Clean separation of concerns with well-structured codebase

📑 Table of Contents

Abstract
Key Highlights
Quick Start
Features
Screenshots & Visuals
Tech Stack
Dependencies & Packages
Installation
Usage
Folder Structure
API Reference
Architecture
Development
Performance & Metrics
Deployment
Troubleshooting
Security Considerations
Contributing
Code of Conduct
License

🚀 Quick Start (3 Steps)

For Developers

# 1. Clone and install
git clone https://github.com/H0NEYP0T-466/webOS-processMGR.git
cd webOS-processMGR
npm install

# 2. Start with Docker (easiest)
cd docker && docker-compose up -d

# 3. Open browser
# http://localhost (frontend)
# http://localhost:8888/docs (API docs)

For Users

Try the live demo: https://web-os-process-mgr.vercel.app

No installation needed! Just open the link and experience the full webOS environment.

Default credentials:

Username: admin
Password: admin123

✨ Features

🖥️ Desktop Environment

Boot sequence with staged progress and witty messages
Login screen with JWT-based authentication
Draggable/resizable windows with minimize, maximize, and close
Taskbar with open windows, system tray, and clock
App launcher for quick access to applications
Persistent desktop state (saved to MongoDB)

📁 Virtual File System

Create, rename, move, and delete files and folders
Text editor with autosave
File tree navigation
All data persisted to MongoDB

📊 Task Manager

Two tabs for comprehensive process monitoring:

Virtual OS Tab:

View all running virtual processes (apps/tasks)
Monitor CPU and memory usage
End tasks gracefully

Host System Tab:

Real host machine processes via psutil
Live CPU/memory charts with historical data
Sort and filter processes
End tasks (admin only) with safety checks

🔐 Security

JWT authentication
Password hashing with bcrypt
Role-based access control (RBAC)
Admin-only host process termination

📝 Rich Server Logging

Emoji-rich logs for all major events:

✅ MongoDB connected: mongodb://***localhost:27017
🟢 Server started: http://0.0.0.0:8888
👤 User registered: username=john
🔐 Login success: username=john
🗂️ Folder created: path=/Documents owner=user123
📄 File created: path=/Documents/notes.txt owner=user123
✍️ File updated: path=/Documents/notes.txt bytes=256
🧰 Virtual process started: id=abc123 app=editor
⛔ Host process terminated: pid=1234 by=admin result=success
📦 Desktop state saved: windows=3 icons=2 user=john

🛠 Tech Stack

Languages

Frameworks & Libraries

Databases

DevOps / CI / Tools

📦 Dependencies & Packages

Frontend Dependencies

Runtime Dependencies

- Animation library for React
- JavaScript library for building user interfaces
- React package for working with the DOM
- Popular icons for React projects
- Declarative routing for React
- Composable charting library built on React
- Small, fast state management solution

Dev Dependencies

- ESLint JavaScript configuration
- TypeScript definitions for Node.js
- TypeScript definitions for React
- TypeScript definitions for React DOM
- Official Vite plugin for React
- Pluggable linting utility for JavaScript
- ESLint rules for React Hooks
- ESLint plugin for React Refresh
- Global identifiers from different JavaScript environments
- TypeScript language
- Monorepo for TypeScript ESLint tooling
- Next generation frontend build tool

Backend Dependencies

Python Dependencies

- Modern, fast web framework for building APIs
- Lightning-fast ASGI server
- Async MongoDB driver for Python
- JOSE implementation in Python for JWT
- Modern password hashing library
- Data validation using Python type hints
- Settings management using Pydantic
- Cross-platform library for system and process utilities
- Multipart form data parser
- WebSocket implementation
- Testing framework
- Pytest support for asyncio
- HTTP client for Python

🚀 Installation

Prerequisites

Node.js 18+
Python 3.11+
MongoDB 6+
Docker (optional)

Option 1: Docker Compose (Recommended)

# Clone the repository
git clone https://github.com/H0NEYP0T-466/webOS-processMGR.git
cd webOS-processMGR

# Start all services
cd docker
docker-compose up -d

# Access the app
# Frontend: http://localhost
# Backend: http://localhost:8888
# API Docs: http://localhost:8888/docs

Option 2: Manual Setup

Important: Before starting, create a .env file in the project root:

# Copy the example file
cp .env.example .env

# The .env file should contain:
# VITE_API_URL=http://localhost:8888
# VITE_WS_URL=ws://localhost:8888/ws
# (plus other backend configuration)

Backend Setup

# Navigate to backend
cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set environment variables (or create .env file)
export MONGO_URI=mongodb://localhost:27017
export JWT_SECRET=your-secret-key
export ADMIN_USER=admin
export ADMIN_PASS=admin123

# Start the server
uvicorn app.main:app --host 0.0.0.0 --port 8888 --reload

Frontend Setup

# Install dependencies
npm install

# Set environment variables (create .env file in project root)
# Copy from .env.example and ensure these are set:
# VITE_API_URL=http://localhost:8888
# VITE_WS_URL=ws://localhost:8888/ws

# Start development server
npm run dev

⚡ Usage

Accessing the Application

Open your browser and navigate to http://localhost:5173 (or the port shown by Vite)
You'll see the boot sequence
Login with credentials (default admin: admin / admin123)
Explore the desktop environment with various apps

Key Features to Try

1. Desktop Experience

Boot Sequence: Watch the staged boot process with witty loading messages
Login: Authenticate with default credentials (admin / admin123)
Window Management:
- Drag windows around the desktop
- Resize windows by dragging edges
- Minimize, maximize, and close windows
- Use the taskbar to switch between open applications

2. File Manager

Navigate File Tree: Browse the virtual file system
Create Folders: Right-click or use toolbar to create new folders
Create Files: Add new text files
Edit Files: Open text editor with auto-save functionality
Organize: Rename, move, or delete files and folders
Persistence: All changes saved to MongoDB instantly

3. Task Manager

Virtual OS Tab:

View all running virtual processes (apps/tasks)
Monitor CPU and memory usage for each process
Sort by different metrics
End tasks gracefully with the terminate button

Host System Tab:

View real host machine processes (requires psutil)
Watch live CPU/Memory charts update every 2 seconds
Sort and filter processes by various criteria
Terminate processes (admin only) with safety checks
Protected PIDs (0, 1, self) cannot be terminated

4. Settings

Configure system preferences and user settings

API Documentation

Access interactive API documentation at http://localhost:8888/docs

📂 Folder Structure

webOS-processMGR/
├── src/                          # Frontend source
│   ├── apps/                     # Application components
│   │   ├── FileManager/          # File browser and editor
│   │   │   ├── FileTree.tsx      # Tree navigation component
│   │   │   ├── FileEditor.tsx    # Text editor component
│   │   │   └── FileManager.tsx   # Main file manager
│   │   ├── TaskManager/          # Process monitoring
│   │   │   ├── VirtualTab.tsx    # Virtual OS processes
│   │   │   ├── HostTab.tsx       # Host system processes
│   │   │   └── TaskManager.tsx   # Main task manager
│   │   ├── Editor/               # Standalone text editor
│   │   └── Settings/             # System settings app
│   ├── os/                       # OS components
│   │   ├── Boot/                 # Boot sequence
│   │   │   └── BootScreen.tsx
│   │   ├── Login/                # Authentication UI
│   │   │   └── LoginScreen.tsx
│   │   ├── Desktop/              # Desktop environment
│   │   │   ├── Desktop.tsx
│   │   │   ├── Taskbar.tsx
│   │   │   └── Launcher.tsx
│   │   └── WindowManager/        # Window system
│   │       ├── Window.tsx
│   │       └── WindowManager.tsx
│   ├── services/                 # API and WebSocket clients
│   │   ├── api.ts                # REST API client
│   │   └── websocket.ts          # WebSocket client
│   ├── state/                    # Zustand state management
│   │   ├── authStore.ts          # Authentication state
│   │   ├── desktopStore.ts       # Desktop state
│   │   ├── fileStore.ts          # File system state
│   │   └── processStore.ts       # Process state
│   └── types/                    # TypeScript definitions
│       ├── api.ts
│       └── models.ts
│
├── backend/                      # Backend source
│   └── app/
│       ├── main.py               # FastAPI application entry
│       ├── auth/                 # Authentication module
│       │   ├── routes.py         # Auth endpoints
│       │   ├── models.py         # User models
│       │   ├── security.py       # JWT & hashing
│       │   └── dependencies.py   # Auth dependencies
│       ├── files/                # File system module
│       │   ├── routes.py         # File/folder endpoints
│       │   ├── models.py         # File system models
│       │   └── service.py        # File operations logic
│       ├── desktop/              # Desktop state module
│       │   ├── routes.py         # Desktop state endpoints
│       │   ├── models.py         # Desktop models
│       │   └── service.py        # Desktop state logic
│       ├── vproc/                # Virtual processes module
│       │   ├── routes.py         # Virtual process endpoints
│       │   ├── models.py         # Process models
│       │   └── manager.py        # Process lifecycle
│       ├── hproc/                # Host processes module
│       │   ├── routes.py         # Host process endpoints
│       │   ├── monitor.py        # psutil integration
│       │   └── metrics.py        # Metrics collection
│       ├── ws/                   # WebSocket module
│       │   ├── connection.py     # Connection manager
│       │   └── events.py         # Event broadcasting
│       ├── db/                   # Database configuration
│       │   └── mongodb.py        # Motor async MongoDB
│       ├── config.py             # Application settings
│       └── tests/                # Backend tests
│           ├── test_auth.py
│           ├── test_files.py
│           └── test_processes.py
│
├── docker/                       # Docker configuration
│   ├── docker-compose.yml        # Development compose
│   ├── docker-compose.prod.yml   # Production compose
│   ├── backend.Dockerfile        # Backend image
│   └── frontend.Dockerfile       # Frontend image
│
├── public/                       # Static assets
│   ├── icons/                    # App icons
│   └── favicon.ico
│
├── docs/                         # Documentation
│   ├── API.md                    # API documentation
│   └── ARCHITECTURE.md           # Architecture details
│
├── .github/                      # GitHub templates and workflows
│   ├── workflows/
│   │   └── ci.yml                # CI/CD pipeline
│   └── ISSUE_TEMPLATE/
│
├── .env.example                  # Environment template
├── package.json                  # Frontend dependencies
├── backend/requirements.txt      # Backend dependencies
├── vite.config.ts                # Vite configuration
├── tsconfig.json                 # TypeScript configuration
├── CONTRIBUTING.md               # Contribution guidelines
├── SECURITY.md                   # Security policy
├── CODE_OF_CONDUCT.md            # Code of conduct
├── LICENSE                       # MIT License
└── README.md                     # This file

📡 API Reference

Authentication

Endpoint	Method	Description
`/auth/register`	POST	Register new user
`/auth/login`	POST	Login and get JWT
`/auth/me`	GET	Get current user info

Files

Endpoint	Method	Description
`/files/tree`	GET	Get file tree
`/files/folder`	POST	Create folder
`/files/file`	POST	Create file
`/files/node/{id}`	GET	Get node details
`/files/node/{id}`	PATCH	Update node
`/files/node/{id}`	DELETE	Delete node

Desktop State

Endpoint	Method	Description
`/desktop/state`	GET	Get desktop state
`/desktop/state`	PUT	Update desktop state

Virtual Processes

Endpoint	Method	Description
`/vproc/list`	GET	List virtual processes
`/vproc/start`	POST	Start virtual process
`/vproc/stop/{id}`	POST	Stop virtual process

Host Processes

Endpoint	Method	Description
`/hproc/list`	GET	List host processes
`/hproc/metrics`	GET	Get system metrics
`/hproc/details/{pid}`	GET	Get process details
`/hproc/terminate/{pid}`	POST	Terminate process (admin)

WebSocket

Connect to /ws?token=<jwt_token> for real-time updates.

Topics:

metrics.host - System CPU/memory metrics (every 2s)
vproc.events - Virtual process lifecycle events
fs.events - File system changes

🏗 Architecture

Components

┌─────────────────────────────────────────────────────────────────┐
│                        Frontend (React)                          │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────────┐   │
│  │ Desktop   │ │   Task    │ │   File    │ │   Settings    │   │
│  │  Manager  │ │  Manager  │ │  Manager  │ │     App       │   │
│  └───────────┘ └───────────┘ └───────────┘ └───────────────┘   │
│        │             │             │              │              │
│  ┌─────┴─────────────┴─────────────┴──────────────┴─────┐       │
│  │              Zustand State Store                       │       │
│  └──────────────────────┬────────────────────────────────┘       │
│                         │                                         │
│  ┌──────────────────────┴────────────────────────────────┐       │
│  │         API Client (REST) / WebSocket Client           │       │
│  └──────────────────────┬────────────────────────────────┘       │
└─────────────────────────┼───────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Backend (FastAPI)                           │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────────┐   │
│  │   Auth    │ │  Virtual  │ │   Host    │ │     File      │   │
│  │  Routes   │ │  Process  │ │  Process  │ │    System     │   │
│  └───────────┘ └───────────┘ └───────────┘ └───────────────┘   │
│        │             │             │              │              │
│  ┌─────┴─────────────┴─────────────┴──────────────┴─────┐       │
│  │                  Service Layer                         │       │
│  └──────────────────────┬────────────────────────────────┘       │
│                         │                                         │
│  ┌──────────────────────┼────────────────────────────────┐       │
│  │    MongoDB (Motor)   │     psutil (Host Monitoring)    │       │
│  └──────────────────────┴────────────────────────────────┘       │
└─────────────────────────────────────────────────────────────────┘

Data Flow

User Authentication: JWT tokens stored in frontend state, sent with all API requests
Virtual Processes: CRUD operations stored in MongoDB, events broadcast via WebSocket
Host Processes: Read-only monitoring via psutil, metrics pushed every 1-2 seconds
File System: Virtual file tree stored in MongoDB with path-based indexing

Process Lifecycle

Virtual Processes: Created on app open, tracked in database, cleaned up on app close
Host Processes: Read-only monitoring, admin-only termination with safety guards

📈 Performance & Metrics

Real-time Monitoring

Update Frequency: Metrics pushed every 2 seconds via WebSocket
Data Points: CPU usage, memory usage, thread count, process count
Historical Data: Rolling window for chart visualization

System Requirements

Minimum RAM: 512MB for backend + frontend
Recommended RAM: 2GB for smooth operation
CPU: Single core sufficient, multi-core recommended for better performance
Storage: ~100MB for application + MongoDB data
Browser: Modern browser with WebSocket support (Chrome, Firefox, Safari, Edge)

Scalability

Concurrent Users: Supports multiple simultaneous users with isolated desktop states
Process Tracking: Handles hundreds of virtual processes efficiently
Database: MongoDB indexed for fast path-based file system lookups
WebSocket: Efficient broadcast mechanism for real-time updates

💻 Development

Running Tests

# Backend tests
cd backend
source venv/bin/activate
python -m pytest app/tests -v

# Frontend lint and type check
npm run lint
npm run build

Building for Production

# Frontend
npm run build

# Backend (Docker)
docker build -f docker/backend.Dockerfile -t webos-backend .

Deployment

Vercel (Frontend)

# Build the frontend
npm run build

# Deploy to Vercel
# 1. Install Vercel CLI: npm i -g vercel
# 2. Run: vercel
# 3. Follow prompts to deploy

# Set environment variables in Vercel dashboard:
# VITE_API_URL=https://your-backend-url.com
# VITE_WS_URL=wss://your-backend-url.com/ws

Railway/Render (Backend)

# Prepare for deployment
cd backend

# Railway deployment
# 1. Install Railway CLI
# 2. railway init
# 3. railway up

# Render deployment
# 1. Connect GitHub repository
# 2. Select backend/ as root directory
# 3. Set build command: pip install -r requirements.txt
# 4. Set start command: uvicorn app.main:app --host 0.0.0.0 --port $PORT

MongoDB Atlas (Database)

# 1. Create MongoDB Atlas account
# 2. Create a cluster (free tier available)
# 3. Get connection string
# 4. Update MONGO_URI in backend .env:
#    MONGO_URI=mongodb+srv://username:password@cluster.mongodb.net/webos?retryWrites=true&w=majority

Docker Production Deployment

# Build and run with Docker Compose
cd docker
docker-compose -f docker-compose.prod.yml up -d

# Or use Docker Swarm for scaling
docker swarm init
docker stack deploy -c docker-compose.prod.yml webos

Live Demo: The current deployment is available at https://web-os-process-mgr.vercel.app

Code Quality

The project uses:

ESLint for TypeScript/React linting
pytest for Python testing
GitHub Actions CI for automated testing on PR/push

🔧 Troubleshooting

Common Issues

MongoDB Connection Failed

Ensure MongoDB is running: docker ps or systemctl status mongod
Check MONGO_URI in your .env file

Permission Denied (Host Processes)

Some process information requires elevated privileges
Run the backend with appropriate permissions for full process access

WebSocket Connection Failed

Check VITE_WS_URL in frontend .env
Ensure backend is running and accessible

CORS Errors

Update CORS_ORIGINS in backend .env to include your frontend URL

🔒 Security Considerations

Change JWT_SECRET in production
Use HTTPS in production
Review CORS_ORIGINS settings
Host process termination is admin-only
Critical PIDs (0, 1, self) are protected

See SECURITY.md for more details.

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details on:

Setting up your development environment
Code style and standards
Submitting pull requests
Reporting issues

Fork the repository
Create a feature branch
Make your changes
Run tests
Submit a pull request

📏 Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ by H0NEYP0T-466

Name		Name	Last commit message	Last commit date
Latest commit History 103 Commits
.github		.github
backend		backend
docker		docker
docs		docs
public		public
src		src
.env.example		.env.example
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
eslint.config.js		eslint.config.js
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation