🔬 Protocol Lab

Interactive network protocols learning platform — Visualize, simulate, and master network protocols through hands-on experimentation.

---

📚 What is This Project?

This is a learning project where we build an interactive platform to understand network protocols (like how your browser talks to websites).

But the goal isn't just to build it — it's to LEARN while building it!

Every tool, every file, every concept is documented so you understand:

• 📖 What it does — Core functionality
• 🤔 Why we use it — Problem it solves
• 🔧 How it works — Key concepts
• 🆚 Alternatives — What else could we use

---

📁 Project Structure Explained (BEGINNER GUIDE)

This project uses a monorepo structure. Let's break down what that means:

What is a Monorepo?

Mono = One, Repo = Repository

Instead of having 5 separate folders/projects on your computer, we have ONE folder that contains multiple related projects. This makes it easier to:

• Share code between projects
• Keep everything in sync
• Run all projects with one command

The Folder Structure

protocol-lab/                    👈 THE ROOT - Everything lives here
│
├── 📦 apps/                     👈 APPLICATIONS (things users interact with)
│   │
│   ├── 📱 web/                  👈 THE WEBSITE (what you see in browser)
│   │   ├── app/                 # Pages of the website
│   │   │   ├── layout.tsx       # The "frame" around every page (header, footer)
│   │   │   ├── page.tsx         # The home page (what you see at localhost:3000)
│   │   │   └── globals.css      # Styles for the whole website
│   │   ├── components/          # Reusable UI pieces (buttons, cards, etc.)
│   │   ├── lib/                 # Helper functions
│   │   ├── public/              # Static files (images, icons)
│   │   ├── package.json         # Lists what this app needs to run
│   │   └── tsconfig.json        # TypeScript settings
│   │
│   └── 🖥️ server/               👈 THE API (backend that powers the website)
│       ├── src/
│       │   └── index.ts         # Entry point - where the server starts
│       ├── package.json         # Lists what this app needs
│       └── tsconfig.json        # TypeScript settings
│
├── 📚 packages/                 👈 SHARED CODE (used by multiple apps)
│   │
│   ├── 🎨 ui/                   👈 Shared UI components
│   │   └── src/                 # Button, Card, etc. used by both apps
│   │
│   ├── 🔄 protocols/            👈 Protocol simulation logic
│   │   └── src/
│   │       └── index.ts         # State machines for TCP, TLS, etc.
│   │
│   ├── 📋 types/                👈 Shared data definitions
│   │   └── src/
│   │       └── index.ts         # "What does a Packet look like?"
│   │
│   ├── ⚙️ config/               👈 Shared configuration
│   │   └── biome.json           # Linting/formatting rules
│   │
│   └── 📝 typescript-config/    👈 Shared TypeScript settings
│       └── base.json            # Common compiler options
│
├── 📄 Configuration Files (ROOT LEVEL)
│   │
│   ├── package.json             # 👈 ROOT package.json (manages the whole monorepo)
│   ├── pnpm-workspace.yaml      # 👈 Tells pnpm which folders are "packages"
│   ├── turbo.json               # 👈 Turborepo config (how to build/run things)
│   ├── biome.json               # 👈 Code style rules (formatting, linting)
│   └── README.md                # 👈 You are here! 📍
│
└── 📂 Generated Folders (DON'T EDIT THESE)
    ├── node_modules/            # Downloaded dependencies (auto-generated)
    ├── .next/                   # Next.js build output (auto-generated)
    ├── dist/                    # Server build output (auto-generated)
    └── .turbo/                  # Turborepo cache (auto-generated)

Why This Structure?

Problem	Solution
"I have duplicate code in frontend and backend"	Put shared code in packages/
"My types don't match between apps"	Share types via packages/types/
"Building is slow"	Turborepo caches builds, only rebuilds changed code
"I need to run 5 terminals"	pnpm dev runs everything at once

---

📄 File-by-File Explanation

Root Configuration Files

package.json (Root)

{
  "name": "protocol-lab",       // Project name
  "private": true,              // Don't publish to npm (this is our project)
  "scripts": {
    "dev": "turbo run dev",     // 👈 Runs ALL apps in development mode
    "build": "turbo run build", // 👈 Builds ALL apps for production
    "lint": "biome check ."     // 👈 Checks code style
  }
}

What is package.json?

• It's like a recipe card for your project
• Lists all the "ingredients" (dependencies) your project needs
• Defines "scripts" — shortcuts for common commands

pnpm-workspace.yaml

packages:
  - "apps/*"      # Everything in apps/ is a package
  - "packages/*"  # Everything in packages/ is a package

What does this do?

• Tells pnpm "hey, these folders are all part of the same project"
• Allows packages to import from each other with workspace:*

turbo.json

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],  // Build dependencies first
      "outputs": [".next/**"]   // Cache these files
    },
    "dev": {
      "persistent": true        // Keep running (don't exit)
    }
  }
}

What is Turborepo?

• It's a build orchestrator — it figures out what to run, in what order
• If you change packages/types, it knows to rebuild everything that uses it
• It caches builds — if nothing changed, it skips the build (super fast!)

biome.json

{
  "linter": { "enabled": true },    // Check for bugs
  "formatter": { "enabled": true }  // Make code pretty
}

What is Biome?

• Linter: Finds bugs and bad practices (like var instead of const)
• Formatter: Makes code look consistent (indentation, quotes, etc.)
• Replaces ESLint + Prettier (one tool instead of two!)

---

🛠️ Tech Stack Deep Dive

🚀 Runtime & Build Tools

Bun — The JavaScript Engine

Question	Answer
What is it?	A program that runs JavaScript/TypeScript code
What does "runtime" mean?	The engine that reads your code and executes it
Why not just use Node.js?	Bun is 3x faster and understands TypeScript natively
What's the catch?	It's newer, some packages might have issues

# With Node.js, you need extra steps:
node app.js              # Only runs JavaScript
tsc app.ts && node app.js # TypeScript needs compilation

# With Bun, it just works:
bun app.ts               # Runs TypeScript directly!

pnpm — Package Manager

Question	Answer
What is it?	Downloads and manages dependencies (external code)
What are dependencies?	Code written by others that we use (React, etc.)
Why not npm?	pnpm is faster and uses less disk space
How does it save space?	Uses "symlinks" — shortcuts instead of copies

# What happens when you run:
pnpm install

# 1. pnpm reads package.json
# 2. Downloads all listed dependencies
# 3. Stores them in a global cache (~/.pnpm-store)
# 4. Creates symlinks in node_modules/

What is a symlink? Think of it like a shortcut on your desktop. Instead of copying the same file 10 times, we have 10 shortcuts pointing to one file.

Turborepo — Monorepo Orchestrator

Question	Answer
What is it?	Runs and builds multiple projects together
What's a "task"?	Something to run, like build, dev, lint
What's caching?	Remembering results so we don't redo work

# Without Turborepo:
cd apps/web && npm run build    # Build frontend
cd apps/server && npm run build # Build backend
cd packages/ui && npm run build # Build UI package
# ... and so on, manually, every time

# With Turborepo:
pnpm build  # Does everything, in the right order, skipping unchanged!

---

⚛️ Frontend Stack

Next.js — React Framework

Question	Answer
What is React?	A library for building user interfaces with components
What is Next.js?	A framework built ON TOP of React, adds routing, SSR, etc.
What's the difference?	React = building blocks, Next.js = full house blueprint
What's App Router?	File-based routing — files become URLs automatically

# File-based routing example:
app/
├── page.tsx          → localhost:3000/
├── about/page.tsx    → localhost:3000/about
└── blog/[id]/page.tsx → localhost:3000/blog/123

TypeScript — Typed JavaScript

Question	Answer
What are types?	Labels that say what kind of data something is
Why do we need them?	Catches bugs before you run the code
What's the downside?	More code to write, learning curve

// JavaScript - no types, errors happen at runtime (when users see them!)
function add(a, b) {
  return a + b;
}
add("hello", 5); // Returns "hello5" - probably not what you wanted!

// TypeScript - types catch errors before running
function add(a: number, b: number): number {
  return a + b;
}
add("hello", 5); // ❌ Error: "hello" is not a number!

Tailwind CSS — Utility Classes

Question	Answer
What is CSS?	The language that styles web pages (colors, sizes, etc.)
What's different about Tailwind?	Instead of writing CSS files, you use classes
Why is that better?	Faster to write, no naming things, stays consistent

<!-- Traditional CSS -->
<div class="my-card">Hello</div>
<style>
  .my-card {
    padding: 16px;
    background: white;
    border-radius: 8px;
    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
  }
</style>

<!-- Tailwind CSS -->
<div class="p-4 bg-white rounded-lg shadow-md">Hello</div>
<!-- No separate CSS file needed! Classes describe the style -->

---

🖥️ Backend Stack

Hono — Web Server Framework

Question	Answer
What is a web server?	A program that responds to HTTP requests
What's HTTP?	The protocol browsers use to fetch web pages
Why Hono?	Super lightweight (14KB), fast, TypeScript-first
What about Express?	Express is 1.4MB, older, requires more setup

// Simple Hono server
import { Hono } from 'hono'

const app = new Hono()

// When someone visits "/", send back "Hello!"
app.get('/', (c) => c.text('Hello!'))

// When someone visits "/api/users", send back JSON data
app.get('/api/users', (c) => c.json([
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob' }
]))

---

📊 State Management

XState — State Machines

Question	Answer
What is state?	The current "situation" of your app
What's a state machine?	A diagram of all possible states and how to move between them
Why use it for protocols?	Protocols have defined states (CONNECTING → CONNECTED → CLOSED)

TCP Connection State Machine:
┌─────────┐   SYN    ┌──────────┐  SYN-ACK  ┌─────────────┐
│ CLOSED  │ ───────► │ SYN_SENT │ ────────► │ ESTABLISHED │
└─────────┘          └──────────┘           └─────────────┘

Zod — Data Validation

Question	Answer
What is validation?	Checking if data has the right format
When do we need it?	When receiving data from users or APIs
Why Zod?	Validates data AND gives TypeScript types

import { z } from 'zod'

// Define what a "User" should look like
const UserSchema = z.object({
  name: z.string(),           // Must be text
  age: z.number().min(0),     // Must be number >= 0
  email: z.string().email(),  // Must be valid email
})

// Validate incoming data
const result = UserSchema.safeParse({
  name: "Alice",
  age: 25,
  email: "alice@example.com"
})

if (result.success) {
  console.log(result.data) // Safe to use!
} else {
  console.log(result.error) // Show what's wrong
}

---

🚀 Getting Started

Prerequisites

Step 1: Install Required Tools

# Install Bun (JavaScript runtime)
# This downloads and installs Bun on your computer
curl -fsSL https://bun.sh/install | bash

# Install pnpm (package manager)
# This downloads and installs pnpm
curl -fsSL https://get.pnpm.io/install.sh | sh -

# Restart your terminal or run:
source ~/.zshrc  # macOS/Linux

Step 2: Install Project Dependencies

# Navigate to the project folder
cd protocol-lab

# Install all dependencies
# This reads package.json files and downloads everything needed
pnpm install

Step 3: Start Development

# Start all apps in development mode
pnpm dev

# This starts:
# - Frontend at http://localhost:3000
# - Backend at http://localhost:3001

Step 4: Open in Browser

1. Open your browser
2. Go to http://localhost:3000
3. You should see the app running!

---

🧪 Common Commands

Command	What it does
pnpm dev	Start development servers (auto-reloads on changes)
pnpm build	Build for production (optimized, ready to deploy)
pnpm lint	Check code for errors and style issues
pnpm lint:fix	Automatically fix linting issues
pnpm format	Format code to look consistent

---

📖 Learning Resources

Start Here (Beginner)

• JavaScript.info — Learn JavaScript from scratch
• TypeScript Handbook — Official TypeScript guide
• React Tutorial — Official React tutorial

Our Tech Stack

• Bun Documentation — Learn Bun
• Next.js Documentation — Learn Next.js
• Tailwind CSS — Learn Tailwind
• Hono Documentation — Learn Hono
• XState Documentation — Learn state machines

Monorepo & Tooling

• Turborepo Handbook — Learn Turborepo
• pnpm Workspaces — Learn pnpm workspaces

---

❓ FAQ

Why do we have so many config files?

Each tool needs its own configuration. It looks like a lot, but:

• package.json — What dependencies to install
• tsconfig.json — How to compile TypeScript
• turbo.json — How to run builds
• biome.json — How to format/lint code

What's the difference between apps/ and packages/?

• apps/ — Standalone applications (has an entry point, runs on its own)
• packages/ — Shared libraries (imported BY apps, doesn't run alone)

Why workspace:* in package.json?

This tells pnpm "use the local package from this monorepo, not one from npm".

{
  "dependencies": {
    "@repo/types": "workspace:*"  // Use local packages/types folder
  }
}

What does "build" mean?

Transforming source code into optimized code browsers can run:

• TypeScript → JavaScript
• Modern JS → Compatible JS
• Many files → Bundled/minified files

---

📝 License

MIT License — use this freely for learning!