# 🖥️ 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 — no server, no 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 | ❌ | — |
| **SJF** — Shortest Job First | ❌ | — |
| **SRTF** — Shortest Remaining Time First | ✅ | — |
| **Round Robin (RR)** | ✅ | Quantum |
| **Priority NP** — Non-Preemptive Priority | ❌ | Aging (optional) |
| **Priority P** — Preemptive Priority | ✅ | Aging (optional) |
| **HRRN** — Highest Response Ratio Next | ❌ | — |
| **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! Feel free to open an [issue](https://github.com/lucasrguerra/pss/issues) or submit a Pull Request.

---

## 📜 License

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