Skip to content

Latest commit

ย 

History

9 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

Pseudo-OS: A Web-Based Operating System Environment

Project Status React Version Vite License

A highly interactive, browser-based Web Operating System built entirely with React and Vanilla CSS. Designed as a comprehensive capstone project, Pseudo-OS simulates a modern desktop environment, demonstrating advanced frontend engineering principles, state management architectures, and precise DOM manipulations without relying on heavy external UI frameworks.


๐ŸŒŸ Executive Summary

Pseudo-OS bridges the gap between traditional web applications and desktop environments. It provides a cohesive, unified workspace where multiple simulated applications run concurrently, sharing a central virtual file system. The project strictly adheres to a robust academic syllabus, proving mastery over core web technologies through practical, real-world implementation.

๐Ÿ”— Live Demonstration

๐Ÿš€ Core Features & Application Suite

Pseudo-OS comes pre-packaged with a suite of essential applications, all interacting with the core OS state:

  • ๐Ÿ–ฅ๏ธ Desktop Environment: A responsive workspace featuring a live-updating clock, application dock, and dynamic glassmorphism aesthetics.
  • ๐Ÿ“ File Explorer: A graphical interface to navigate the virtual file system. Supports directory traversal, file creation, deletion, and inline text editing.
  • โŒจ๏ธ Terminal Emulator: A robust command-line interface directly connected to the OS file system. Supports standard POSIX-like commands:
    • ls, cd, pwd, mkdir, touch, cat, rm, echo, clear, whoami
  • ๐Ÿ“ Notes Application: A persistent text editor that reads and writes .txt and .md files directly to the shared /Documents directory.
  • โ›… Weather Dashboard: Real-time meteorological data integration via the Open-Meteo API, featuring dynamic iconography and async data fetching.
  • ๐Ÿงฎ Calculator: A fully functional arithmetic calculator with a custom evaluation engine.
  • โš™๏ธ System Settings: Centralized configuration panel to toggle global themes (Dark/Light) and manage user profiles via localStorage.

๐Ÿ—๏ธ Architecture & Technology Stack

The project is built on a modern, lightweight foundation, intentionally avoiding CSS-in-JS libraries or utility frameworks like Tailwind to demonstrate raw CSS proficiency.

Layer Technology Choice Rationale
Core Framework React 18 (Functional Components) Component-driven architecture and reactive state updates.
Routing Layer React Router DOM v7 Managing the active application state via URL paths.
Styling Engine Vanilla CSS3 + CSS Variables Achieving high-performance glassmorphism and custom themes without build-step overhead.
Iconography Lucide React Consistent, lightweight vector graphics.
Network & Data Native Fetch API Promise-based asynchronous external data retrieval.
Build Tool Vite Lightning-fast HMR and optimized production bundling.
State Management React Context API + Hooks Centralized global state without Redux overhead.

๐Ÿ“Š System Architecture

The interaction model below demonstrates how Pseudo-OS initializes context providers and manages data flow between global state containers and individual simulated applications:

graph TD
    subgraph Providers [Context & Providers]
        M[main.jsx] --> FSC[FileSystemProvider]
        M --> TC[ThemeProvider]
    end

    subgraph Core [OS Shell & Routing]
        FSC --> App[App.jsx Routing]
        TC --> App
        App --> L[Layout.jsx]
        L --> SB[Status Bar]
        L --> D[Dock]
        L --> DK[Desktop.jsx Workspace]
    end

    subgraph Windows [Window Manager]
        DK --> W1[OSWindow: File Explorer]
        DK --> W2[OSWindow: Terminal]
        DK --> W3[OSWindow: Notes]
        DK --> W4[OSWindow: Weather]
        DK --> W5[OSWindow: Calculator]
        DK --> W6[OSWindow: Settings]
    end

    subgraph StateShare [Virtual File System & Settings]
        W1 <--> FSC
        W2 <--> FSC
        W3 <--> FSC
        W6 <--> TC
    end
    
    style Providers fill:#1e1e2e,stroke:#313244,stroke-width:2px,color:#cdd6f4
    style Core fill:#181825,stroke:#313244,stroke-width:2px,color:#cdd6f4
    style Windows fill:#11111b,stroke:#313244,stroke-width:2px,color:#cdd6f4
    style StateShare fill:#313244,stroke:#45475a,stroke-width:2px,color:#cdd6f4
Loading

๐Ÿ“š Capstone Syllabus Alignment

This project was engineered to satisfy specific academic requirements, demonstrating mastery in four key units:

Unit 1: Advanced DOM Manipulation & Event Handling

  • Custom dragging logic for OSWindow components using native mouse events (mousedown, mousemove, mouseup).
  • Keyboard event listeners in the Terminal for command execution and arrow-key history navigation.

Unit 2: Asynchronous JavaScript & Storage

  • Implementation of the Fetch API with .then()/.catch() methodology in the Weather app.
  • Non-blocking setInterval mechanisms for the live Desktop clock.
  • Persistent state management using the browser's localStorage API for themes and user profiles.

Unit 3: React Fundamentals & Component Architecture

  • Modular component design separating OS UI (Layout, Dock, Window) from specific application logic.
  • Robust prop-passing and component composition patterns.

Unit 4: Advanced Hooks & Global State

  • useContext: Engineering a global FileSystemContext that acts as the single source of truth for the Terminal, File Explorer, and Notes apps.
  • useRef: Direct DOM access for auto-scrolling terminal outputs.
  • useState / useEffect: Managing complex component lifecycles, data fetching states, and cleanup operations.

๐Ÿ“‚ Codebase Topography

src/
โ”œโ”€โ”€ context/
โ”‚   โ”œโ”€โ”€ FileSystemContext.jsx   # Shared virtual file system engine
โ”‚   โ””โ”€โ”€ ThemeContext.jsx        # Global appearance state manager
โ”œโ”€โ”€ components/
โ”‚   โ”œโ”€โ”€ Layout.jsx              # Global OS shell (Dock, Status Bar)
โ”‚   โ””โ”€โ”€ OSWindow.jsx            # Reusable, draggable application container
โ”œโ”€โ”€ pages/
โ”‚   โ”œโ”€โ”€ Desktop.jsx             # Main workspace interface
โ”‚   โ”œโ”€โ”€ FileExplorer.jsx        # Graphical FS navigator
โ”‚   โ”œโ”€โ”€ Terminal.jsx            # CLI FS navigator
โ”‚   โ”œโ”€โ”€ Notes.jsx               # FS-connected text editor
โ”‚   โ”œโ”€โ”€ Weather.jsx             # Async API consumer
โ”‚   โ”œโ”€โ”€ Calculator.jsx          # Logic and state computation
โ”‚   โ””โ”€โ”€ Settings.jsx            # LocalStorage preference manager
โ”œโ”€โ”€ App.jsx                     # Route definitions
โ”œโ”€โ”€ main.jsx                    # Application entry point & Provider tree
โ””โ”€โ”€ index.css                   # Global design system & animations

๐Ÿ’ป Installation & Setup

To run Pseudo-OS locally, ensure you have Node.js (v16+) installed.

  1. Clone the repository:

    git clone https://github.com/Inkesk-Dozing/Pseudo-OS.git
    cd Pseudo-OS
  2. Install dependencies:

    npm install
  3. Launch the development environment:

    npm run dev
  4. Open your browser and navigate to http://localhost:5173.


๐Ÿ”ฎ Future Roadmap

  • Process Manager: Implement a task manager to show "running" apps rather than purely route-based rendering.
  • Window Stacking (z-index): Allow overlapping windows with active-window focus management.
  • Draggable Desktop Icons: Implement drag-and-drop API for desktop shortcuts.
  • Persistent File System: Sync the virtual FS state to IndexedDB so files survive browser refreshes.

๐Ÿ”’ Security Summary

We are committed to keeping Pseudo-OS secure. For information regarding supported versions, vulnerability reporting procedures, and disclosure policies, please refer to our Security Policy.


๐Ÿ“„ License

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

Releases

Packages

Contributors

Languages