Skip to content

Commit d391d44

Browse files
nadeem-majeedchnadeem-majeedch
committed
OS Visual lab Complete
0 parents  commit d391d44

385 files changed

Lines changed: 65041 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/deploy.yml‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
name: Deploy to GitHub Pages
2+
3+
# Publishes the statically built lab to GitHub Pages at
4+
# https://nadeem-majeedch.github.io/Operating-Systems-Visual-Lab/
5+
#
6+
# Deployment is artifact-based (no `gh-pages` branch): the built `dist/` folder
7+
# is uploaded as a Pages artifact and published by `actions/deploy-pages`.
8+
on:
9+
push:
10+
branches: ['main']
11+
workflow_dispatch:
12+
13+
# Required by the GitHub Pages deployment flow.
14+
permissions:
15+
contents: read
16+
pages: write
17+
id-token: write
18+
19+
# Allow one concurrent deployment; newer runs cancel older in-progress ones.
20+
concurrency:
21+
group: 'pages'
22+
cancel-in-progress: true
23+
24+
jobs:
25+
build:
26+
name: Build
27+
runs-on: ubuntu-latest
28+
steps:
29+
- name: Checkout
30+
uses: actions/checkout@v5
31+
32+
- name: Set up Node
33+
uses: actions/setup-node@v5
34+
with:
35+
node-version: 22
36+
cache: npm
37+
38+
- name: Install dependencies
39+
run: npm ci
40+
41+
- name: Verify (typecheck, lint, tests)
42+
run: |
43+
npm run typecheck
44+
npm run lint
45+
npm run test
46+
47+
- name: Build
48+
run: npm run build
49+
50+
- name: Configure Pages
51+
uses: actions/configure-pages@v5
52+
53+
- name: Upload artifact
54+
uses: actions/upload-pages-artifact@v3
55+
with:
56+
path: ./dist
57+
58+
deploy:
59+
name: Deploy
60+
needs: build
61+
runs-on: ubuntu-latest
62+
environment:
63+
name: github-pages
64+
url: ${{ steps.deployment.outputs.page_url }}
65+
steps:
66+
- name: Deploy to GitHub Pages
67+
id: deployment
68+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# dependencies
2+
node_modules/
3+
.pnpm-store/
4+
5+
# build output
6+
dist/
7+
dist-ssr/
8+
*.local
9+
10+
# test / tooling output
11+
coverage/
12+
.vitest/
13+
*.tsbuildinfo
14+
15+
# logs
16+
npm-debug.log*
17+
yarn-debug.log*
18+
yarn-error.log*
19+
pnpm-debug.log*
20+
logs/
21+
*.log
22+
23+
# editors / OS
24+
.vscode/*
25+
!.vscode/extensions.json
26+
.idea/
27+
.DS_Store
28+
Thumbs.db
29+
*.swp
30+
31+
# freebuff workspace metadata
32+
.freebuff/

‎README.md‎

Lines changed: 266 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
# Operating Systems Visual Lab
2+
3+
**Explore operating system concepts through interactive simulations, visual experiments, and guided challenges.**
4+
5+
The Operating Systems Visual Lab is a free, browser-based study companion for an introductory
6+
operating systems course. Instead of reading about a scheduler and imagining the Gantt chart, you
7+
build the chart, press play, and read the reason for every decision the scheduler makes. Every
8+
simulation is deterministic and step-by-step: you can pause it, rewind it, and replay it as slowly as
9+
you like.
10+
11+
It runs entirely in your browser. There is no account, no server, and no tracking, and once the page
12+
has loaded it keeps working with the network switched off.
13+
14+
> **Live site:** <https://nadeem-majeedch.github.io/Operating-Systems-Visual-Lab/>
15+
> _(served from GitHub Pages — see [docs/getting-started.md](docs/getting-started.md))_
16+
17+
---
18+
19+
## Why this lab exists
20+
21+
Operating systems are hard for a specific reason: the interesting behaviour is invisible. You cannot
22+
watch a page be evicted, a deadlock close its cycle, or a race condition lose an update. Traditional
23+
diagrams show a *result*; this lab shows the *process*, one recorded step at a time.
24+
25+
The design principle throughout is **learn by manipulating, not by memorising**:
26+
27+
- Every algorithm is a simulation you drive, not a picture you look at.
28+
- Every step carries an explanation of *why* it happened, not just what happened.
29+
- Every metric you compute by hand is then reported by the engine, so you can check your arithmetic
30+
against a reproducible run.
31+
32+
## Where it fits
33+
34+
The lab is written for **undergraduate computer science and data science students** taking a first
35+
operating systems course, and for anyone revising the same material for interviews. It assumes you
36+
can read a little pseudocode and that you know what a process is. It does **not** assume you have
37+
written a kernel.
38+
39+
It is a supplement, not a replacement for your course: the lab gives you something to *do* with the
40+
theory, and each area links back to the standard textbook treatment.
41+
42+
---
43+
44+
## Learning objectives
45+
46+
By working through the lab you should be able to:
47+
48+
1. **Describe** the five process states and the legal transitions between them, and explain what a
49+
process control block records.
50+
2. **Compute**, for any arrival table, the Gantt chart and the turnaround, waiting and response time
51+
of every process under FCFS, SJF, SRTF, Round Robin and priority scheduling.
52+
3. **Explain** why a non-atomic read–modify–write can lose an update, and fix it with a mutex, a
53+
semaphore, or a correctly ordered pair of `wait()` calls.
54+
4. **Apply** the four Coffman conditions, detect a deadlock with a wait-for graph, and decide whether a
55+
resource request keeps the system in a safe state using the banker's algorithm.
56+
5. **Contrast** first-fit, best-fit, worst-fit and next-fit placement, and distinguish internal from
57+
external fragmentation.
58+
6. **Translate** a logical address into a physical one through a page table and TLB, and compare FIFO,
59+
LRU, OPT and Clock page replacement — including Bélády's anomaly.
60+
7. **Compute** total and average head movement for FCFS, SSTF, SCAN, C-SCAN, LOOK and C-LOOK disk
61+
scheduling, and explain each policy's fairness property.
62+
8. **Compare** contiguous, linked and indexed file allocation, and trace a path from a directory entry
63+
through an inode to the data blocks on disk.
64+
9. **Choose** an algorithm for a workload and justify the trade-off in terms of the metrics the engine
65+
reports.
66+
67+
---
68+
69+
## The eight learning areas
70+
71+
| Area | What you will be able to do | Simulations | Difficulty | Guide |
72+
|------|-----------------------------|-------------|------------|-------|
73+
| **Process Management** | Trace a process through every state and inspect its PCB | 2 (1 live) | Beginner | [docs/process-management.md](docs/process-management.md) |
74+
| **CPU Scheduling** | Build Gantt charts and score policies on turnaround, waiting and response time | 4 | Beginner → Intermediate | [docs/cpu-scheduling.md](docs/cpu-scheduling.md) |
75+
| **Process Synchronization** | Reproduce a race condition, then repair it with locks and semaphores | 4 | Intermediate | [docs/synchronization.md](docs/synchronization.md) |
76+
| **Deadlocks** | Detect a cycle, and decide whether a request keeps the system safe | 2 | Intermediate → Advanced | [docs/deadlocks.md](docs/deadlocks.md) |
77+
| **Memory Management** | Place processes into memory and measure the fragmentation you cause | 3 (2 live) | Intermediate | [docs/memory-management.md](docs/memory-management.md) |
78+
| **Virtual Memory** | Translate addresses and choose a page to evict | 2 | Intermediate → Advanced | [docs/virtual-memory.md](docs/virtual-memory.md) |
79+
| **Disk Scheduling** | Turn a request queue into head movement and compare six policies | 1 | Intermediate | [docs/disk-scheduling.md](docs/disk-scheduling.md) |
80+
| **File Systems** | Build a virtual file system and follow a path down to physical blocks | 1 | Intermediate | [docs/file-systems.md](docs/file-systems.md) |
81+
82+
In total the lab ships **19 interactive labs**, **35 algorithm reference entries**, **43 worked
83+
examples**, **8 guided lessons**, **16 practice challenges** and **110 graded quiz questions**. Two
84+
labs are scaffolded with objectives and worked examples while their simulators are still being built;
85+
they are labelled `Planned` and never pretend to run.
86+
87+
Every area is reachable from the sidebar, and every lab is a deep link (for example
88+
`#/labs/lab-disk-scheduling`) that survives a page refresh.
89+
90+
---
91+
92+
## How a guided lesson works
93+
94+
Each learning area has a **guided lesson** (`#/learn`) that walks the same six stages in the same
95+
order, so you always know what comes next:
96+
97+
1. **Concept** — the idea in plain language, with the key terms you should be able to define.
98+
2. **Visualization** — the lab that makes the idea visible, with three things to watch for.
99+
3. **Experiment** — a concrete setup to run, with the observations you should expect.
100+
4. **Walkthrough** — a numbered trace of one full run you can replay in the lab.
101+
5. **Challenge** — graded questions drawn from the matching question bank.
102+
6. **Reflection** — prompts you answer privately, in your own words.
103+
104+
Each lesson also lists its **objectives**, **prerequisites**, **key terms** and **common mistakes**
105+
before the stages, and records your progress locally as you tick stages off.
106+
107+
## How to use a simulator
108+
109+
Every lab uses the same controls, so once you have learned them you can use any of the nineteen:
110+
111+
- **Play / Pause** starts and stops the recording of the run.
112+
- **Step** moves forward or backward exactly one recorded step — the fastest way to see a single
113+
scheduling decision or page eviction.
114+
- **Speed** changes playback rate without changing the result.
115+
- **Reset** returns the lab's inputs to their defaults.
116+
- **View switches** (where a lab offers them, such as *Simulate / Compare / Challenge*) change what
117+
the same panel shows without losing your work.
118+
- **Example selector** loads a worked example with a ready-made input, so you can start from a known
119+
scenario instead of inventing one.
120+
121+
Every step writes to a shared **timeline**, **explanation panel** and **event log**: the log names the
122+
event, the explanation panel says why it happened, and the metrics tiles show the numbers at that
123+
moment.
124+
125+
---
126+
127+
## The recommended learning path
128+
129+
Work through the areas in this order. Each one builds on the vocabulary of the one before it.
130+
131+
```
132+
Processes → Scheduling → Synchronization → Deadlocks → Memory → Virtual Memory → Storage
133+
```
134+
135+
Storage covers both **Disk Scheduling** and **File Systems**. You can also jump straight to the area
136+
you are revising — the topics are self-contained, and each one declares its prerequisites at the top
137+
of its guide.
138+
139+
---
140+
141+
## Practice and self-testing
142+
143+
- **Challenges** (`#/challenges`) — 16 open tasks that state a problem and the evidence a correct
144+
answer must contain. They are answered in the matching lab, then compared against the reference
145+
outcome.
146+
- **Quiz bank** (`#/quizzes`) — 110 graded questions across 20 banks, in five formats: multiple
147+
choice, numerical, prediction, sequence and simulation-decision. Every expected answer is *computed
148+
by the same engine the lab uses*, never typed by hand, so nothing in the quiz can contradict what
149+
you see in the simulator.
150+
151+
See [docs/challenges.md](docs/challenges.md) for a bank-by-bank breakdown and a suggested study
152+
routine.
153+
154+
---
155+
156+
## Screenshots
157+
158+
The lab asks users to manipulate diagrams rather than look at pictures, so it deliberately ships no
159+
image assets — the home page's CPU timeline, every chart, memory map and graph are drawn with CSS and
160+
SVG at runtime. To add you own captures for a course page, drop them in `docs/images/` and embed them
161+
here:
162+
163+
```markdown
164+
![Home dashboard](docs/images/home-dashboard.png)
165+
![CPU scheduling Gantt chart](docs/images/cpu-scheduling.png)
166+
![Deadlock wait-for graph](docs/images/wait-for-graph.png)
167+
![File-system block map](docs/images/file-systems.png)
168+
```
169+
170+
Suggested captures: the **home dashboard**, a **Gantt chart mid-run**, a **deadlocked wait-for
171+
graph**, a **memory map with a fragmented hole**, a **TLB translation step**, and the **file-system
172+
block map with the free-space bitmap**.
173+
174+
---
175+
176+
## Accessibility
177+
178+
The lab aims to be usable with a keyboard alone and readable in both light and dark themes:
179+
180+
- **Semantic structure** — real landmarks (header, navigation, main, footer), one `h1` per page, and a
181+
"skip to main content" link as the first focusable element.
182+
- **Keyboard support** — every control is a native button, link, or labelled form control, and the
183+
simulator playback (including the step scrubber) is fully keyboard-operable.
184+
- **Visible focus** — a consistent, high-contrast focus ring on every interactive element.
185+
- **Accessible names** — decorative glyphs are hidden from assistive technology, and charts that carry
186+
meaning are paired with a text table or an `aria-label`.
187+
- **Reduced motion** — animation and transitions are effectively disabled when the operating system
188+
requests `prefers-reduced-motion`.
189+
- **Higher contrast** — a `prefers-contrast: more` mode strengthens borders and text contrast.
190+
- **Theme** — light, dark and "match your system", applied before first paint so there is no flash of
191+
the wrong theme.
192+
193+
Known limitations are documented in [docs/architecture.md](docs/architecture.md#accessibility-notes):
194+
SVG charts are described in text but are not yet a fully equivalent screen-reader experience.
195+
196+
---
197+
198+
## Technologies
199+
200+
| Layer | Choice |
201+
|-------|--------|
202+
| Language | TypeScript 5.6 (strict, `noUncheckedIndexedAccess`, `verbatimModuleSyntax`) |
203+
| UI | React 18 |
204+
| Build tool | Vite 7 (static bundle; assets served under the `/Operating-Systems-Visual-Lab/` base path) |
205+
| Tests | Vitest 4 (635 unit tests over engines, models, utilities and content) |
206+
| Lint | ESLint 9 (flat config) with `react-hooks` and `react-refresh` |
207+
| Styling | Hand-written CSS with custom-property design tokens — no CSS framework |
208+
| Runtime deps | React and React DOM only |
209+
210+
No backend, no database, no authentication, no external APIs, and no analytics.
211+
212+
---
213+
214+
## Roadmap
215+
216+
**Shipped today** — all eight learning areas with 17 runnable simulators, the eight guided lessons,
217+
the 110-question graded bank, the 16 open challenges, and the dashboard home page.
218+
219+
**In progress**
220+
221+
- **`fork`, `exec` and process trees** (Process Management) — copy-on-write address spaces, descriptor
222+
inheritance and PID assignment, visualised.
223+
- **Buddy allocator** (Memory Management) — split and coalesce power-of-two blocks and measure the
224+
internal fragmentation that buys.
225+
226+
**Planned**
227+
228+
- Aging added to the priority policies so the starvation lesson has a built-in remedy.
229+
- Linking each guided-experiment stage straight to a lab preset, so the setup text and the lab state
230+
cannot drift apart.
231+
- Progress export: turning guided-lesson and quiz results into a downloadable worksheet.
232+
233+
The engines behind every shipped lab and every quiz answer already exist, so new work adds
234+
visualisations and content rather than duplicating algorithms. See
235+
[docs/architecture.md](docs/architecture.md#extending-the-lab) for how the pieces fit together.
236+
237+
---
238+
239+
## Documentation
240+
241+
| Document | Contents |
242+
|----------|----------|
243+
| [docs/getting-started.md](docs/getting-started.md) | Open the lab, learn the controls, and start your first lesson |
244+
| [docs/process-management.md](docs/process-management.md) | Process states, the PCB, context switches |
245+
| [docs/cpu-scheduling.md](docs/cpu-scheduling.md) | FCFS, SJF, SRTF, Round Robin, priority — and the metrics that score them |
246+
| [docs/synchronization.md](docs/synchronization.md) | Race conditions, critical sections, mutexes, semaphores |
247+
| [docs/deadlocks.md](docs/deadlocks.md) | Coffman conditions, wait-for graphs, safe states |
248+
| [docs/memory-management.md](docs/memory-management.md) | Placement strategies, fragmentation, compaction |
249+
| [docs/virtual-memory.md](docs/virtual-memory.md) | Paging, the TLB, page faults, replacement policies |
250+
| [docs/disk-scheduling.md](docs/disk-scheduling.md) | Six head-scheduling policies and how to compare them |
251+
| [docs/file-systems.md](docs/file-systems.md) | Inodes, allocation strategies, free-space management |
252+
| [docs/challenges.md](docs/challenges.md) | The question banks, the five question formats, and how marking works |
253+
| [docs/architecture.md](docs/architecture.md) | How the app is built, and how to extend it |
254+
| [docs/contributing.md](docs/contributing.md) | Set up locally, run the checks, and add a lab or an engine |
255+
256+
---
257+
258+
## License
259+
260+
Released under the **MIT License**, as declared in `package.json`. You are free to use, adapt and
261+
redistribute the lab for teaching, including in your own course, with attribution.
262+
263+
Standard references for the material covered here, useful alongside the labs:
264+
265+
- Silberschatz, Galvin & Gagne, *Operating System Concepts*.
266+
- Arpaci-Dusseau & Arpaci-Dusseau, *Operating Systems: Three Easy Pieces* (available free online).

0 commit comments

Comments
 (0)