# 🖥️ Process Scheduler Simulator

> An interactive educational tool for visualizing and comparing classical CPU scheduling algorithms from Operating Systems.

[![React](https://img.shields.io/badge/React-18-61DAFB?logo=react&logoColor=white)](https://react.dev/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Vite](https://img.shields.io/badge/Vite-6-646CFF?logo=vite&logoColor=white)](https://vitejs.dev/)
[![Tailwind CSS](https://img.shields.io/badge/Tailwind-4-06B6D4?logo=tailwindcss&logoColor=white)](https://tailwindcss.com/)
[![Vitest](https://img.shields.io/badge/Tested_with-Vitest-6E9F18?logo=vitest&logoColor=white)](https://vitest.dev/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## ✨ What is it?

The **Process Scheduler Simulator (PSS)** runs entirely in the browser, completely free of servers and system dependencies. You define the processes, choose the algorithm, and watch the simulation unfold in real time through the Gantt chart.

Ideal for:
- 📚 Operating Systems students who want to visualize what was once only theory
- 👩‍🏫 Instructors looking for an interactive classroom tool
- 🔍 Professionals revisiting OS fundamentals

A live demo is available at: **https://pss.lucasrguerra.dev.br/**

---

## 🚀 Quick Start

### Prerequisites

- [Node.js](https://nodejs.org/) 20+
- npm 10+

### Local installation and run

```bash
# Clone the repository
git clone https://github.com/lucasrguerra/pss.git
cd pss

# Install dependencies
npm install

# Start the development server
npm run dev
```

Open [http://localhost:5173](http://localhost:5173) in your browser.

### Production build

```bash
npm run build
npm run preview
```

### With Docker

```bash
docker compose up
```

---

## 🎮 How to use

1. **Create your processes**: In the left panel, add processes by defining name, arrival time, priority, and a sequence of bursts (CPU and I/O). Or use the random generator to get started quickly.
2. **Configure the scheduler**: Choose an algorithm and adjust the parameters (quantum for RR, aging for Priority, etc.).
3. **Run the simulation**: Use the Play/Pause/Step controls to run the simulation at the speed you want (0.25× to 4×).
4. **Analyze the results**: The Gantt chart shows each process's state in real time. At the end, the metrics panel displays turnaround, waiting time, throughput, and more.

> 💡 **Tip:** Load one of the built-in **presets** to see classic phenomena such as the FCFS convoy effect or priority starvation.

---

## ⚙️ Supported Algorithms

| Algorithm | Preemptive? | Parameters |
|-----------|:-----------:|------------|
| **FCFS**: First Come, First Served | ❌ | None |
| **SJF**: Shortest Job First | ❌ | None |
| **SRTF**: Shortest Remaining Time First | ✅ | None |
| **Round Robin (RR)** | ✅ | Quantum |
| **Priority NP**: Non-Preemptive Priority | ❌ | Aging (optional) |
| **Priority P**: Preemptive Priority | ✅ | Aging (optional) |
| **HRRN**: Highest Response Ratio Next | ❌ | None |
| **Multilevel Queue** | ✅ | Quantum per queue |

> See the [algorithms documentation](./docs/algorithms.en.md) for details on how each one works.

---

## 📊 Computed Metrics

For each simulated process, PSS automatically computes:

- **Response Time**: time until the first CPU usage
- **Turnaround Time**: total time from arrival to completion
- **Waiting Time**: total time spent in the Ready queue
- **CPU Time / I/O Time**: effective time in each type of burst
- **CPU Utilization**: percentage of turnaround time spent on CPU
- **Bound Type**: automatic classification as CPU Bound, I/O Bound, or Balanced

Globally: averages for response/turnaround/waiting, throughput, and overall CPU utilization.

---

## 🗂️ Project Structure

```
src/
├── core/                    # Pure logic (no React)
│   ├── algorithms/          # Implementation of each algorithm
│   │   ├── base.ts          # Abstract class BaseScheduler
│   │   ├── fcfs.ts
│   │   ├── sjf.ts
│   │   ├── rr.ts
│   │   ├── priority.ts
│   │   ├── priority_rr.ts
│   │   ├── hrrn.ts
│   │   ├── multilevel.ts
│   │   └── index.ts         # Dispatch by algorithm
│   ├── engine.ts            # SimulationEngine, orchestrates the ticks
│   ├── metrics.ts           # Per-process and global metrics computation
│   ├── types.ts             # All TypeScript interfaces
│   └── presets.ts           # Pre-defined scenarios
│
├── store/                   # Global state with Zustand
├── components/              # React components
│   ├── ProcessPanel/        # Process creation and editing
│   ├── SchedulerPanel/      # Algorithm selection and parameters
│   ├── ControlBar/          # Play, Pause, Step, Reset, speed
│   ├── GanttChart/          # Interactive Gantt chart
│   ├── MetricsPanel/        # Table, charts, and global metrics
│   └── shared/              # Buttons, badges, tooltips, modals
│
└── hooks/                   # Custom hooks (animation loop, export, etc.)
```

---

## 📦 Available Presets

Load classic scenarios with a single click to explore OS phenomena:

| Preset | What it demonstrates |
|--------|----------------------|
| `classic_fcfs` | Basic execution with FCFS, no I/O |
| `convoy_effect` | Convoy effect: one long process blocking many short ones |
| `rr_demo` | Fair time-sharing with Round Robin (quantum=3) |
| `starvation` | Low-priority processes never receive CPU |
| `aging_fix` | The same starvation scenario, solved with aging |
| `io_heavy` | Mix of CPU Bound vs. I/O Bound processes |
| `multilevel_demo` | Multiple queues with different priorities |

---

## 🧪 Tests

```bash
# Run all unit tests
npm test

# Watch mode (re-runs on save)
npm run test:watch

# With coverage report
npm run test:coverage
```

Tests cover the simulation engine, all scheduling algorithms, and metrics computation.

---

## 🛠️ Technology Stack

| Layer | Technology |
|-------|-----------|
| UI Framework | React 18 |
| Language | TypeScript 5 |
| Build tool | Vite 6 |
| Styling | Tailwind CSS 4 |
| Global state | Zustand 5 |
| Charts | Recharts |
| Icons | Lucide React |
| Testing | Vitest + Testing Library |

---

## 📄 Additional Documentation

- [📐 Scheduling Algorithms](./docs/algorithms.en.md): detailed description of each algorithm, tie-breaking rules, and examples
- [📏 Metrics](./docs/metrics.en.md): formulas and definitions for all computed metrics
- [📝 JOSS Paper](./paper.md): scientific paper submitted to the Journal of Open Source Software

*Também disponível em: [🇧🇷 Português](./README.md)*

---

## 🤝 Contributing

Contributions are welcome! Please read our [CONTRIBUTING.md](./CONTRIBUTING.md) guide for details on our code of conduct, and the process for submitting Pull Requests to us.

---

## 📜 License

Distributed under the [MIT License](./LICENSE). Developed by [Lucas Rayan Guerra](https://github.com/lucasrguerra).