Forem: Emrah G.

Why “School Bus Routing Software” Is Harder Than It Looks

Emrah G. — Fri, 20 Mar 2026 07:20:56 +0000

When people hear school bus routing software, they usually imagine a simple workflow:

Add student addresses

Assign buses

Generate the best route

In practice, it is much more complex than that.

Real transportation operations involve changing student lists, different vehicle capacities, pickup-time expectations, traffic realities, and constant exceptions. So the real challenge is not just finding the shortest path on a map. It is building a system that helps operators manage daily complexity without drowning in manual work.

That is why I find this space interesting. Good routing software should not only optimize routes. It should also help teams make better operational decisions, adapt quickly, and reduce workload.

A few things matter much more than flashy optimization demos:

handling messy real-world address data

assigning passengers in a practical way

giving operators visibility and control

supporting route adjustments without chaos

making the output usable for daily operations

That last part is important. A route can look mathematically efficient and still be frustrating in real life. If dispatchers keep fixing everything manually, the software is not solving the real problem.

I wrote a more detailed breakdown here for anyone interested in the topic:

School Bus Routing Software

For me, that is the key idea: routing is not just a map problem — it is an operations problem.

Building WatchContact: An AI Chat Analyzer with OCR, Rate Limiting, and a Content Blog

Emrah G. — Thu, 12 Mar 2026 23:19:45 +0000

What We Built

WatchContact is a two-part product:

AI Chat Analyzer — A free tool where users paste a conversation (or upload a screenshot) and get an AI-powered analysis: intent, tone, risk level, and suggested replies.
Blog — Articles on messaging psychology, WhatsApp behavior, texting etiquette, and relationship signals.

The goal was to ship something useful quickly: no auth, no signup, just paste and analyze. Here's how we built it.

Architecture Overview

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Next.js 14     │────▶│  Express API    │────▶│  MongoDB        │
│  (Frontend)     │     │  (Backend)      │     │  (Analytics)    │
└─────────────────┘     └────────┬────────┘     └─────────────────┘
        │                        │
        │                        ├────────────────▶ OpenAI API
        │                        ├────────────────▶ Tesseract.js (OCR)
        │                        └────────────────▶ Cloudflare R2
        │
        └─────────────────────────────────────────▶ Markdown blog (static)

Frontend: Next.js 14, React, Tailwind CSS
Backend: Express, Mongoose, MongoDB
AI: OpenAI GPT for conversation analysis
OCR: Tesseract.js for screenshot text extraction
Storage: Cloudflare R2 for screenshot files (S3-compatible)
Auth: None — IP-based rate limiting instead

1. The AI Chat Analyzer Flow

Two Input Paths

Text input: User pastes or types a conversation → sent directly to the analysis API.

Screenshot input: User pastes an image (Ctrl+V) or uploads a file → backend runs OCR → extracted text is analyzed. The screenshot can optionally be stored in R2 for reference.

Backend API Endpoints

Endpoint	Purpose
`POST /api/analysis/text`	Analyze pasted text
`POST /api/analysis/screenshot-extract`	OCR + optional R2 upload
`POST /api/analysis/screenshot-final`	Analyze OCR text (reuses rate limit from extract)
`GET /api/analysis/limit-status`	Return remaining analyses for the day

Rate Limiting: IP-Based, No Auth

We wanted to avoid signup but still control abuse. Solution: 3 analyses per IP per day.

// rateLimit.service.js - simplified
const DAILY_LIMIT = 3;

async function checkAndIncrement(ipAddress) {
  if (isLocalhost(ipAddress)) return { allowed: true }; // dev bypass

  const dateKey = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
  let record = await IpUsage.findOne({ ipAddress, dateKey });

  if (!record) record = await IpUsage.create({ ipAddress, dateKey, analysisCount: 0 });
  if (record.analysisCount >= DAILY_LIMIT) return { allowed: false };

  record.analysisCount += 1;
  await record.save();
  return { allowed: true };
}

IpUsage model: { ipAddress, dateKey, analysisCount }
Localhost is exempt for development
Frontend calls limit-status to show "X of 3 analyses remaining today"

OpenAI Analysis

We use a structured JSON prompt so the model returns a consistent shape:

// buildPrompt.js - system prompt excerpt
{
  "overallSignal": "Interested" | "Hesitant" | "Mixed Signals" | "Low Interest" | "Neutral",
  "intentSummary": "Short paragraph...",
  "toneAnalysis": ["observation 1", "observation 2", ...],
  "riskLevel": "Low" | "Medium" | "High",
  "riskExplanation": "Brief explanation",
  "suggestedReplies": {
    "safe": "A cautious reply",
    "confident": "A more direct reply",
    "warm": "A warm, casual reply"
  },
  "disclaimer": "This is a behavioral interpretation, not certainty."
}

We validate the response, parse JSON, and reject if required keys are missing. Token usage and estimated cost are stored in MongoDB for monitoring (not shown to users).

OCR with Tesseract.js

For screenshots, we use Tesseract.js on the backend:

// ocr.service.js
const { createWorker } = require('tesseract.js');

async function extractText(imagePath) {
  const worker = await createWorker('eng');
  try {
    const result = await worker.recognize(imagePath);
    return { text: (result.data?.text || '').trim(), confidence: result.data?.confidence };
  } finally {
    await worker.terminate();
  }
}

Multer handles the upload; we pass the temp file path to Tesseract. If no text is found, we return a friendly error ("No text found in image. Try a clearer screenshot.").

Screenshot Storage: Cloudflare R2

Screenshots are uploaded to Cloudflare R2 (S3-compatible) under a chat-analyzer/ prefix. We use the AWS SDK with R2's custom endpoint:

// r2.service.js
const client = new S3Client({
  region: 'auto',
  endpoint: `https://${accountId}.r2.cloudflarestorage.com`,
  credentials: { accessKeyId, secretAccessKey },
  forcePathStyle: true,
});

If R2 env vars are not set, we fall back to local disk. This keeps local dev simple.

2. Frontend UX Decisions

Single Input Area

We avoided separate "text" and "image" modes. One input area handles both:

Paste (Ctrl+V): If clipboard has an image → treat as screenshot; otherwise → text
Upload: File input for PNG/JPEG/WebP

ChatGPT-Style Image Preview

When the user pastes or uploads an image, we show a preview inside the input box. If an image is present, we hide the textarea and placeholder to reduce clutter.

Loading Overlay

During analysis, we overlay the input box with a semi-transparent layer and a spinner. No layout shift—the box stays in place.

Example Analysis Card

New users don't know what to expect. We added a sticky "Example Analysis" card on the right (desktop) showing sample output: signal, intent, suggested reply. On mobile it appears below the form.

3. The Blog

The blog is a standard Next.js + Markdown setup:

Content: Markdown files in content/posts/ with frontmatter (title, description, date, tags, category)
Rendering: react-markdown + remark-gfm for GitHub Flavored Markdown
Categories: Messaging Psychology, WhatsApp Behavior, Texting Etiquette, Relationship Signals, Communication Boundaries

The homepage is the Chat Analyzer; the blog lives at /blog/ with categories, featured articles, and latest posts.

4. SEO and Structured Data

We added:

Page metadata: Title and description for each route, including "AI Chat Analyzer" and blog keywords
SoftwareApplication schema: For the Chat Analyzer tool, so search engines understand it's a web application
Blog schema: For article listings
RSS feed: Generated at build time for blog posts (title, link, description only—no full content to limit scraping)

5. Deployment Notes

Frontend: Next.js on Vercel or Cloudflare Pages (we use wrangler deploy)
Backend: Node.js on any host (Railway, Render, Fly.io, etc.)
Database: MongoDB Atlas
Storage: Cloudflare R2 for screenshots

Environment variables: OPENAI_API_KEY, MONGODB_URI, R2 credentials (optional), NEXT_PUBLIC_API_URL for the frontend to call the API.

Lessons Learned

IP rate limiting works for a free tool without auth. 3/day is enough to prevent abuse while allowing real use.
Tesseract.js is slow on first run (worker init). Consider warming it up or using a queue for production.
Structured JSON prompts with validation make the AI output reliable and easy to render.
R2 as S3-compatible storage keeps things simple; the AWS SDK works with minimal config.
Combining tool + blog helps SEO and gives users a reason to return beyond a one-off analysis.

Try It

WatchContact — Paste a conversation or screenshot, get intent, tone, risk level, and suggested replies. No signup, 3 free analyses per day.

Built with Next.js, Express, OpenAI, Tesseract.js, MongoDB, and Cloudflare R2.

HUD Overlays with Canvas 2D

Emrah G. — Thu, 12 Feb 2026 02:59:25 +0000

Ever wanted to record yourself looking like you're on a Mars mission, running a cyber operation, or filming a found-footage VHS tape? That's exactly what we built with LogMaker — a client-side web app that composites sci-fi HUD overlays on top of your webcam feed in real time and records the result as a WebM video. No backend, no uploads, everything runs in your browser.

In this article, I'll walk you through the entire architecture: how we capture the camera, draw HUD elements on a Canvas, and record the composited output — all with vanilla browser APIs.

Architecture Overview

Here's the full data pipeline:

Camera (getUserMedia)
    ↓
Hidden <video> element
    ↓
Canvas 2D (drawImage + HUD overlay @ 60fps)
    ↓
canvas.captureStream(30) + audio tracks
    ↓
MediaRecorder (WebM VP9/VP8)
    ↓
Blob → Download / Web Share API

The key insight: the canvas is both the preview and the recording source. The user sees the composited result in real time, and captureStream() captures exactly what's on the canvas — HUD included.

Tech stack: Next.js 14 (static export), React 18, Tailwind CSS, and zero external runtime dependencies. The HUD drawing system is pure Canvas 2D — no React, no DOM manipulation.

Step 1: Accessing the Camera

First, we need the webcam feed. We use getUserMedia with specific constraints:

const buildConstraints = (videoDeviceId, audioDeviceId) => {
  const video = videoDeviceId
    ? { deviceId: { exact: videoDeviceId }, width: { ideal: 1280 }, height: { ideal: 720 } }
    : { width: { ideal: 1280 }, height: { ideal: 720 }, facingMode: "user" };
  const audio = audioDeviceId
    ? { deviceId: { exact: audioDeviceId } }
    : true;
  return { video, audio };
};

If the user has selected a specific device (e.g., an external webcam), we use exact to pin it. Otherwise, we default to facingMode: "user" for mobile front cameras and ideal: 1280x720 for desktop.

Stream Acquisition

const acquireStream = async (videoDeviceId, audioDeviceId) => {
  const constraints = buildConstraints(videoDeviceId, audioDeviceId);
  const stream = await navigator.mediaDevices.getUserMedia(constraints);

  // Wire to hidden video element
  const video = videoRef.current;
  video.srcObject = stream;

  // Wait for metadata to load
  await new Promise((resolve) => {
    video.onloadedmetadata = () => {
      video.play().then(resolve).catch(resolve);
    };
  });

  // Match canvas size to actual video resolution
  const canvas = canvasRef.current;
  canvas.width = video.videoWidth || 1280;
  canvas.height = video.videoHeight || 720;

  return stream;
};

Critical detail: we set the canvas dimensions to match the actual video resolution, not the ideal. The camera might give us 1920x1080 or 640x480 depending on the device. The canvas must match exactly.

The Hidden Video Element

The <video> element is invisible — it's only a bridge for getting frames into the canvas:

<video
  ref={videoRef}
  autoPlay
  muted
  playsInline
  className="absolute inset-0 w-0 h-0 opacity-0 pointer-events-none"
/>

muted and playsInline are critical for autoplay to work on mobile. Without playsInline, iOS Safari will try to go fullscreen.

Step 2: The Draw Loop

This is where the magic happens. A requestAnimationFrame loop runs at ~60fps, drawing the camera frame and HUD overlay on every tick:

const startDrawLoop = (theme) => {
  const canvas = canvasRef.current;
  const video = videoRef.current;
  const ctx = canvas.getContext("2d");
  let frameCount = 0;

  function draw() {
    const { width: w, height: h } = canvas;

    // 1. Draw the camera frame
    if (video.readyState >= video.HAVE_CURRENT_DATA) {
      ctx.drawImage(video, 0, 0, w, h);
    }

    // 2. Build HUD state
    const isRec = statusRef.current === "recording";
    const now = Date.now();
    const hudState = {
      isRecording: isRec,
      elapsedMs: isRec ? now - startTimeRef.current : 0,
      blinkPhase: Math.sin(now / 500) * 0.5 + 0.5,  // smooth 0→1→0 pulse
      frameCount: frameCount++,
      solBase: solBaseRef.current,
    };

    // 3. Draw HUD overlay on top
    drawHud(ctx, w, h, theme, hudState);

    // 4. Schedule next frame
    requestAnimationFrame(draw);
  }

  requestAnimationFrame(draw);
};

Why `statusRef` Instead of `status` State?

Notice we read statusRef.current instead of the React state status. This is intentional — the draw function is created once and runs in a requestAnimationFrame loop. If we read the state variable directly, it would be a stale closure. The ref always has the latest value:

const statusRef = useRef("idle");

useEffect(() => {
  statusRef.current = status;
}, [status]);

The Blink Phase

The blinkPhase is a smooth oscillation between 0 and 1 using a sine wave:

blinkPhase: Math.sin(Date.now() / 500) * 0.5 + 0.5

This drives the pulsing glow on corner brackets, the REC indicator, and other animated elements. A full cycle takes ~3.14 seconds (π × 1000ms / 500).

Step 3: The HUD Drawing System

The entire HUD is drawn with Canvas 2D — no DOM, no React. This is important for two reasons:

Performance: DOM manipulation during a 60fps loop would be brutal. Canvas is GPU-accelerated.
Recording: captureStream() captures the canvas pixels. DOM overlays wouldn't be recorded.

Responsive Scaling

Every dimension in the HUD is scaled relative to a 1280px baseline:

/** Scale factor: 1.0 at 1280px width, min 0.5 */
function S(w) {
  return Math.max(w / 1280, 0.5);
}

And a safe margin keeps elements away from the edges:

/** Safe margin: 4% of the smaller dimension */
function safeMargin(w, h) {
  return Math.round(Math.min(w, h) * 0.04);
}

Every pixel value in the HUD is multiplied by S(w):

const s = S(w);
const m = safeMargin(w, h);

// Title font size: 22px at 1280w, scales proportionally
ctx.font = `bold ${Math.round(22 * s)}px monospace`;

// Position anchored to top-left corner with safe margin
const titleX = m + Math.round(18 * s);
const titleY = m + Math.round(16 * s);

This means the HUD looks correct whether the canvas is 640px or 1920px wide.

The Composition Hierarchy

Each theme follows a layered composition model. Think of it like Photoshop layers:

Layer 1: Tone overlay (dust, color tint)
Layer 2: Vignette (darkened edges)
Layer 3: Film grain / noise
Layer 4: Scanline sweep (animated horizontal line)
Layer 5: CRT scanlines (static horizontal lines)
Layer 6: Corner brackets (cinematic framing)
PRIMARY: Title + timestamp (most important info)
SECONDARY: Telemetry data (supporting info)
TERTIARY: Scrolling terminal log (ambient detail)

Theme Dispatcher

A simple switch routes to the correct drawing function:

export const THEMES = [
  { id: "mars_log", name: "MARS LOG", accent: "#ff6b35" },
  { id: "cyber_ops", name: "CYBER OPS", accent: "#39ff14" },
  { id: "vhs_archive", name: "VHS ARCHIVE", accent: "#e0e0e0" },
];

export function drawHud(ctx, w, h, theme, state) {
  ctx.save();
  switch (theme) {
    case "mars_log":    drawMarsLog(ctx, w, h, state);    break;
    case "cyber_ops":   drawCyberOps(ctx, w, h, state);   break;
    case "vhs_archive": drawVhsArchive(ctx, w, h, state); break;
    default:            drawMarsLog(ctx, w, h, state);
  }
  ctx.restore();
}

The ctx.save() / ctx.restore() pair is essential — each theme can modify globalCompositeOperation, shadows, etc. without leaking state.

Step 4: Drawing the HUD Elements

Let's look at the shared building blocks every theme uses.

Vignette Effect

A radial gradient that darkens the edges, creating a cinematic framing:

function drawVignette(ctx, w, h, r, g, b, strength) {
  const a = strength || 0.65;
  const grad = ctx.createRadialGradient(
    w / 2, h / 2, w * 0.22,   // inner circle (transparent)
    w / 2, h / 2, w * 0.85    // outer circle (colored)
  );
  grad.addColorStop(0, `rgba(${r},${g},${b},0)`);
  grad.addColorStop(0.65, `rgba(${r},${g},${b},${a * 0.25})`);
  grad.addColorStop(1, `rgba(${r},${g},${b},${a})`);
  ctx.fillStyle = grad;
  ctx.fillRect(0, 0, w, h);
}

Each theme tints the vignette differently:

Mars Log: warm red/orange (35, 8, 0) — dusty Martian atmosphere
Cyber Ops: green (0, 12, 0) — night-vision / hacker terminal feel
VHS Archive: pure black (0, 0, 0) — old TV edges

CRT Scanlines

Horizontal lines drawn at regular intervals to mimic a CRT monitor:

function drawCrtScanlines(ctx, w, h, alpha, gap) {
  ctx.fillStyle = `rgba(0,0,0,${alpha})`;
  for (let y = 0; y < h; y += gap) {
    ctx.fillRect(0, y, w, 1);
  }
}

At a gap of 3-4 pixels with an alpha of 0.06-0.12, this creates a subtle but effective CRT look. We keep the alpha low to avoid making the video unwatchable.

Film Grain / Noise

Random dots scattered across the frame to simulate film grain:

function drawNoise(ctx, w, h, count, tint, alphaMin, alphaMax, frameCount) {
  // Only render every 3rd frame for performance
  if (frameCount % 3 !== 0) return;

  const maxDots = Math.min(count, Math.round(w * h * 0.0003));
  for (let i = 0; i < maxDots; i++) {
    const x = Math.random() * w;
    const y = Math.random() * h;
    const size = Math.random() * 1.5 + 0.5;
    const a = alphaMin + Math.random() * (alphaMax - alphaMin);
    ctx.fillStyle = tint
      ? `rgba(${tint[0]},${tint[1]},${tint[2]},${a})`
      : `rgba(${Math.floor(Math.random() * 180 + 60)},...)`;
    ctx.fillRect(x, y, size, size);
  }
}

Two performance tricks here:

Frame skipping: Only drawing every 3rd frame. The persistence of the previous frame's noise gives a natural flicker effect.
Count capping: maxDots is capped relative to canvas area (w * h * 0.0003), so a 4K canvas doesn't try to draw thousands of dots.

Animated Scanline Sweep

A glowing horizontal line that sweeps down the screen:

function drawScanlineSweep(ctx, w, h, speed, color, alpha, thickness) {
  const now = Date.now();
  const y = (now / speed) % h;  // position cycles through canvas height
  const s = S(w);

  // Sharp line
  ctx.fillStyle = `rgba(${color},${alpha})`;
  ctx.fillRect(0, y, w, thickness * s);

  // Soft glow around the line
  const glowH = 25 * s;
  const grad = ctx.createLinearGradient(0, y - glowH, 0, y + glowH);
  grad.addColorStop(0, `rgba(${color},0)`);
  grad.addColorStop(0.5, `rgba(${color},${alpha * 0.2})`);
  grad.addColorStop(1, `rgba(${color},0)`);
  ctx.fillStyle = grad;
  ctx.fillRect(0, y - glowH, w, glowH * 2);
}

The speed parameter controls how fast the line moves. A speed of 22 (Cyber Ops) is faster than 55 (VHS Archive), matching each theme's energy level.

Corner Brackets

The cinematic framing brackets in each corner, with a glow effect:

function drawCornerBrackets(ctx, w, h, offset, len, thickness, color, glowSize) {
  ctx.strokeStyle = color;
  ctx.lineWidth = thickness;
  ctx.lineCap = "square";
  ctx.shadowColor = color;
  ctx.shadowBlur = glowSize;

  // Top-left bracket
  ctx.beginPath();
  ctx.moveTo(offset, offset + len);
  ctx.lineTo(offset, offset);
  ctx.lineTo(offset + len, offset);
  ctx.stroke();

  // Top-right bracket
  ctx.beginPath();
  ctx.moveTo(w - offset - len, offset);
  ctx.lineTo(w - offset, offset);
  ctx.lineTo(w - offset, offset + len);
  ctx.stroke();

  // Bottom-left and bottom-right follow the same pattern...
  // ...

  ctx.shadowBlur = 0;  // Reset shadow to avoid bleeding
}

The shadowBlur creates the neon glow. Each theme uses its accent color — orange for Mars, green for Cyber, and a subtle white for VHS.

Blinking REC Indicator

A cinematic recording indicator with a pulsing red dot:

function drawRecIndicator(ctx, x, y, s, blinkPhase, elapsedMs) {
  const alpha = 0.4 + blinkPhase * 0.6;  // pulsates between 0.4 and 1.0
  const text = `REC ${formatTime(elapsedMs)}`;

  // Background pill
  ctx.fillStyle = `rgba(120,10,10,${0.3 + blinkPhase * 0.12})`;
  roundRect(ctx, boxX, boxY, totalW, totalH, r);
  ctx.fill();

  // Pulsing red dot with glow
  ctx.fillStyle = `rgba(255,40,40,${alpha})`;
  ctx.shadowColor = "#ff2828";
  ctx.shadowBlur = 12 * s * blinkPhase;
  ctx.beginPath();
  ctx.arc(dotX, dotY, dotR, 0, Math.PI * 2);
  ctx.fill();
  ctx.shadowBlur = 0;

  // Text: "REC 00:01:23"
  ctx.fillStyle = `rgba(255,220,220,${alpha})`;
  ctx.fillText(text, dotX + dotR + 10 * s, y + 1);
}

The blinkPhase (0→1→0 sine wave) drives both the dot opacity and glow radius, creating a smooth pulsing effect.

Scrolling Terminal Log

An ambient scrolling log that adds "life" to the HUD:

// Module-level state — persists across frames
const terminalState = {
  mars_log: { lines: [], lastPush: 0 },
  cyber_ops: { lines: [], lastPush: 0 },
  vhs_archive: { lines: [], lastPush: 0 },
};

function updateTerminalLog(themeId, pool, interval, maxLines) {
  const ts = terminalState[themeId];
  const now = Date.now();

  if (now - ts.lastPush > interval) {
    // Pick a random line from the pool
    const line = pool[Math.floor(Math.random() * pool.length)];
    ts.lines.push({ text: line, time: now });

    // Keep only the last N lines
    if (ts.lines.length > maxLines) ts.lines.shift();
    ts.lastPush = now;
  }

  return ts.lines;
}

Each theme has its own message pool:

const TERMINAL_LINES_MARS = [
  "SYS: SIGNAL LOCKED",
  "NAV: ORBITAL POSITION LOCKED",
  "COM: UPLINK ACTIVE",
  "SYS: DUST FILTER ENGAGED",
  "HAB: PRESSURE NOMINAL",
  "SYS: SOLAR ARRAY 98%",
  "MED: BIOMETRICS SYNCED",
  // ...
];

const TERMINAL_LINES_CYBER = [
  "NET: PACKET STREAM OK",
  "ENC: AES-256 LOCKED",
  "NET: PROXY CHAIN VALID",
  "OPS: SURVEILLANCE ACTIVE",
  "NET: VPN TUNNEL ACTIVE",
  // ...
];

const TERMINAL_LINES_VHS = [
  "TAPE: HEAD ALIGNED",
  "SYS: TRACKING OK",
  "REC: SIGNAL STABLE",
  "SYS: CHROMA LOCK",
  // ...
];

The log is drawn with a fade effect — older lines are more transparent:

function drawTerminalLog(ctx, x, y, s, lines, color, maxAge, maxVisible) {
  // Semi-transparent background panel
  ctx.fillStyle = "rgba(0,0,0,0.22)";
  roundRect(ctx, panelX, panelY, panelW, panelH, r);
  ctx.fill();

  for (let i = 0; i < lines.length; i++) {
    // Newer lines are brighter (bottom = newest)
    const posRatio = lines.length > 1 ? i / (lines.length - 1) : 1;
    const alpha = 0.5 + posRatio * 0.4;

    ctx.fillStyle = `rgba(${color},${alpha})`;
    ctx.shadowColor = `rgba(${color},${alpha * 0.3})`;
    ctx.shadowBlur = 4 * s;
    ctx.fillText(lines[i].text, x, y + i * lineH);
  }
  ctx.shadowBlur = 0;
}

Step 5: Theme Deep Dive — Mars Log

Let me show you how these building blocks compose into a complete theme. Here's the Mars Log theme, the most feature-rich one:

function drawMarsLog(ctx, w, h, state) {
  const s = S(w);
  const { isRecording, elapsedMs, blinkPhase, frameCount, solBase } = state;
  const accent = "215,95,45";  // warm orange
  const m = safeMargin(w, h);

  // ── Layer 1: Dusty warm tint ──
  ctx.globalCompositeOperation = "multiply";
  ctx.fillStyle = "rgba(180,120,70,0.08)";
  ctx.fillRect(0, 0, w, h);
  ctx.globalCompositeOperation = "source-over";

  // ── Layer 2: Dark vignette with red/orange tint ──
  drawVignette(ctx, w, h, 35, 8, 0, 0.6);

  // ── Layer 3: Warm-tinted film grain ──
  drawNoise(ctx, w, h, 30, [200, 130, 60], 0.02, 0.05, frameCount);

  // ── Layer 4: Orange scanline sweep ──
  drawScanlineSweep(ctx, w, h, 35, accent, 0.08, 2);

  // ── Layer 5: CRT scanlines + tracking distortion ──
  drawCrtScanlines(ctx, w, h, 0.06, 4);

  // Tracking distortion — a line that drifts across the screen
  const trackCycle = 5000;
  const trackPhase = (Date.now() % trackCycle) / trackCycle;
  const trackY = trackPhase * h;
  ctx.fillStyle = `rgba(${accent},0.05)`;
  ctx.fillRect(0, trackY, w, 2 * s);

  // ── Layer 6: Corner brackets with orange glow ──
  drawCornerBrackets(
    ctx, w, h, m,
    Math.round(80 * s),   // arm length
    Math.round(7 * s),    // thickness
    `rgba(${accent},${0.4 + blinkPhase * 0.2})`,  // pulses with blink
    Math.round(14 * s)    // glow size
  );

  // ── PRIMARY: Title "MARS LOG" (top-left) ──
  ctx.font = `bold ${Math.round(22 * s)}px monospace`;
  ctx.shadowColor = "#d75f2d";
  ctx.shadowBlur = 12 * s;
  ctx.fillStyle = `rgba(${accent},0.95)`;
  ctx.fillText("MARS LOG", m + 18 * s, m + 16 * s);

  // Mission ID below title
  ctx.font = `${Math.round(11 * s)}px monospace`;
  ctx.fillStyle = `rgba(${accent},0.6)`;
  ctx.fillText(getMissionId(), m + 18 * s, m + 46 * s);

  // ── PRIMARY: UTC timestamp (top-right) ──
  drawBigTimestamp(ctx, w - m - 18*s, m + 16*s, utcTimestamp(), 26*s,
    `rgba(${accent},0.85)`, "right", "30,12,4");

  // ── SECONDARY: SOL counter (bottom-left) ──
  const solNum = solBase + Math.floor(elapsedMs / 1000);
  const solText = `SOL ${solNum}`;
  // ... draws with background panel and mini brackets ...

  // ── SECONDARY: ENV DATA (bottom-right) ──
  // Temperature, pressure, radiation — all slowly drifting
  const env = updateEnvData();
  ctx.fillText(`TEMP: ${env.temp.toFixed(1)}°C`, brX, brBaseY);
  ctx.fillText(`PRES: ${env.pres} Pa`, brX, brBaseY - envLineH);
  ctx.fillText(`RAD: ${env.rad.toFixed(2)} mSv`, brX, brBaseY - 2*envLineH);

  // ── TERTIARY: Terminal log + center crosshair ──
  const logLines = updateTerminalLog("mars_log", TERMINAL_LINES_MARS, 900, 8);
  drawTerminalLog(ctx, titleX, m + 100*s, s, logLines, "255,160,80", 7000, 8);

  // ── REC indicator (bottom-center, only during recording) ──
  if (isRecording) {
    drawRecIndicator(ctx, w/2, h - m - 22*s, s, blinkPhase, elapsedMs);
  }
}

Drifting Telemetry Data

The environment data (temp, pressure, radiation) slowly drifts using a random walk:

const envData = { temp: -42.3, pres: 610, rad: 0.24, lastUpdate: 0 };
const ENV_BASE = { temp: -42.3, pres: 610, rad: 0.24 };
const ENV_RANGE = { temp: 1.5, pres: 5, rad: 0.06 };

function updateEnvData() {
  const now = Date.now();
  const interval = 3000 + Math.random() * 2000; // 3-5 seconds
  if (now - envData.lastUpdate < interval) return envData;
  envData.lastUpdate = now;

  // Tiny random delta
  const dTemp = (Math.random() - 0.5) * 0.3;
  const dPres = Math.round((Math.random() - 0.5) * 2);
  const dRad = (Math.random() - 0.5) * 0.02;

  // Apply + clamp to range
  envData.temp = Math.max(
    ENV_BASE.temp - ENV_RANGE.temp,
    Math.min(ENV_BASE.temp + ENV_RANGE.temp, envData.temp + dTemp)
  );
  // ... same for pres and rad ...

  return envData;
}

This creates a realistic "live telemetry" feel — the numbers change, but only slightly and slowly. They stay within a realistic range around the base values.

Step 6: VHS-Specific Effects

The VHS Archive theme has unique effects that deserve their own section.

Color Bleed (Chromatic Aberration)

The title text is drawn twice — once with a red offset to simulate analog color bleeding:

// Red ghost — shifted right
ctx.fillStyle = `rgba(200,140,140,0.18)`;
ctx.fillText("ARCHIVE LOG", titleX + 2 * s + jX, titleY + jY);

// Main text on top
ctx.fillStyle = `rgba(${accent},0.85)`;
ctx.fillText("ARCHIVE LOG", titleX + jX, titleY + jY);

Jitter

The position offset jX and jY add random micro-movements:

const jX = (Math.random() - 0.5) * 1.5;
const jY = (Math.random() - 0.5) * 1.5;

Since this runs every frame at 60fps, the text appears to vibrate slightly — just like a paused VHS tape.

Edge Wobble

The top and bottom edges wobble with a sine wave to simulate tape head instability:

const edgeH = Math.round(h * 0.02);
const wobble = Math.sin(Date.now() / 200) * 3 * s;
ctx.fillStyle = "rgba(0,0,0,0.3)";
ctx.fillRect(wobble, 0, w + 10, edgeH);
ctx.fillRect(-wobble, h - edgeH, w + 10, edgeH);

Tracking Line

A bright horizontal line that periodically sweeps down the screen, like a VHS tracking error:

const trackCycle = 4000;
const trackPhase = (Date.now() % trackCycle) / trackCycle;
if (trackPhase < 0.1) {  // only visible 10% of the time
  const trackY = (trackPhase / 0.1) * h;
  ctx.fillStyle = "rgba(255,255,255,0.1)";
  ctx.fillRect(0, trackY - 1, w, 2.5 * s);
}

Step 7: Recording the Composited Output

This is where captureStream() and MediaRecorder come together:

const handleStartRecording = () => {
  const canvas = canvasRef.current;

  // 1. Capture the canvas at 30fps
  const canvasStream = canvas.captureStream(30);

  // 2. Add audio tracks from the original camera stream
  const audioTracks = streamRef.current?.getAudioTracks() || [];
  audioTracks.forEach((track) => canvasStream.addTrack(track));

  // 3. Pick the best codec
  const mimeType = pickMimeType();
  const recorder = new MediaRecorder(canvasStream, { mimeType });

  // 4. Collect chunks
  const chunks = [];
  recorder.ondataavailable = (e) => {
    if (e.data && e.data.size > 0) chunks.push(e.data);
  };

  // 5. On stop, create a downloadable blob
  recorder.onstop = () => {
    const blob = new Blob(chunks, { type: mimeType });
    const url = URL.createObjectURL(blob);
    setDownloadUrl(url);
  };

  // 6. Start recording with 100ms timeslice
  recorder.start(100);
};

Codec Selection

We try VP9 first (better quality), then fall back:

function pickMimeType() {
  const candidates = [
    "video/webm;codecs=vp9,opus",
    "video/webm;codecs=vp8,opus",
    "video/webm;codecs=vp9",
    "video/webm;codecs=vp8",
    "video/webm",
  ];
  for (const mime of candidates) {
    if (MediaRecorder.isTypeSupported(mime)) return mime;
  }
  return "video/webm";
}

Why 30fps Capture but 60fps Draw?

The draw loop runs at 60fps for a smooth preview, but captureStream(30) captures at 30fps. This is intentional:

60fps draw: Smooth visual feedback for the user
30fps capture: Smaller file size, still looks great for video

Download and Share

const handleDownload = () => {
  const a = document.createElement("a");
  a.href = downloadUrl;
  a.download = "logmaker-recording.webm";
  document.body.appendChild(a);
  a.click();
  document.body.removeChild(a);
};

// Web Share API (mobile)
const handleShare = async () => {
  const file = new File([blob], "logmaker-recording.webm", {
    type: "video/webm",
  });
  await navigator.share({
    files: [file],
    title: "LogMaker Recording",
  });
};

Step 8: Device Management

Users might have multiple cameras and microphones. We enumerate them and let them switch:

const enumerateDevices = async () => {
  const devices = await navigator.mediaDevices.enumerateDevices();
  const vDevices = devices.filter((d) => d.kind === "videoinput");
  const aDevices = devices.filter((d) => d.kind === "audioinput");

  setVideoDevices(vDevices);
  setAudioDevices(aDevices);

  // Restore saved selections from localStorage
  const savedVideo = localStorage.getItem("logmaker_videoDevice");
  if (savedVideo && vDevices.some((d) => d.deviceId === savedVideo)) {
    setSelectedVideoDevice(savedVideo);
  }
};

// Listen for device changes (plug/unplug)
useEffect(() => {
  navigator.mediaDevices.addEventListener("devicechange", enumerateDevices);
  return () => navigator.mediaDevices.removeEventListener("devicechange", enumerateDevices);
}, []);

Device labels are only available after permission is granted (a browser security measure), so we enumerate again after the first getUserMedia call succeeds.

Performance Considerations

A few things we do to keep this running at 60fps:

Frame-skipped noise: Grain only renders every 3rd frame
Throttled React updates: UI elapsed time updates at ~2Hz, not 60Hz
Capped dot counts: Noise dots are proportional to canvas area
Module-level state: Terminal log state lives outside React to avoid re-renders
No DOM manipulation in the loop: Everything is pure canvas operations
Ref-based status reads: Avoids stale closures in the draw loop

// Throttled UI update — only every 15th frame (~2Hz at 30fps)
if (isRec && frameCountRef.current % 15 === 0) {
  setElapsedTime(elapsed);
}

Putting It All Together

The React component structure is minimal:

export default function RecorderClient() {
  const [status, setStatus] = useState("idle");
  // idle → camera_on → recording → stopped

  return (
    <div className="flex flex-col flex-1 min-h-0">
      {/* Stage: canvas fills available space */}
      <div className="relative flex-1 bg-black">
        <video ref={videoRef} autoPlay muted playsInline
          className="w-0 h-0 opacity-0" />
        <canvas ref={canvasRef} width={1280} height={720}
          className="w-full h-full object-contain" />
      </div>

      {/* Control bar: theme selector + action buttons */}
      <div className="flex items-center gap-2 px-3 py-2 bg-gray-950">
        <select value={selectedTheme} onChange={...}>
          {THEMES.map(t => <option key={t.id} value={t.id}>{t.name}</option>)}
        </select>
        {/* Buttons change based on status */}
      </div>
    </div>
  );
}

The canvas uses object-contain CSS so it maintains aspect ratio while filling the available space — no letterboxing logic needed.

Key Takeaways

Canvas is your compositing layer. Use drawImage() for the video frame and draw everything else on top. captureStream() captures the final result.
Keep HUD drawing pure. No React, no DOM. Just a function that takes (ctx, width, height, state) and draws. This is fast and testable.
Use module-level state for animation. Terminal logs, environment data, and mission IDs live outside React. They persist across frames without causing re-renders.
Scale everything relative to canvas width. A single S(w) function makes the entire HUD responsive.
Use refs for the draw loop. React state creates stale closures in requestAnimationFrame. Refs always have the current value.
Layer your effects. Tone → vignette → grain → scanlines → brackets → text. Each layer adds depth. Keep alpha values low — subtlety is cinematic.

Try It Out

logmaker.app — try it right now in your browser. No signups, no backend, no data collection.

The HUD system is under 1000 lines of pure Canvas 2D, and the entire app has zero runtime dependencies beyond React and Next.js.

If you build your own HUD theme, I'd love to see it. Drop a comment below!

What sci-fi HUD would you want to see next? Night-vision? Submarine sonar? Mech cockpit? Let me know in the comments.

How We Solve the Vehicle Routing Problem: Clustering, TSP Heuristics, and Real-World Constraints

Emrah G. — Sun, 08 Feb 2026 10:06:47 +0000

If you've ever looked at the Traveling Salesman Problem and thought "interesting, but when would I actually need this?" — fleet route optimization is one of those real-world domains where combinatorial optimization isn't academic. It's the difference between a transport operation that burns cash and one that runs efficiently.

I work on RouteBot, a transport management platform for school buses and personnel shuttles. Every day, our system distributes thousands of passengers across hundreds of vehicles and sequences their stops. This article walks through the algorithmic pipeline we use — and the engineering tradeoffs involved.

For a broader, less code-focused comparison of manual vs. algorithmic route planning (including operational scenarios and implementation roadmaps), see the full guide on our blog.

The Problem, Formally

Given:

A set of n passengers, each with a geographic coordinate (lat/lng)
A set of k vehicles, each with a capacity c
A destination (school, factory, office)

Find:

An assignment of passengers to vehicles such that no vehicle exceeds capacity and total intra-cluster distance is minimized (Capacitated Clustering)
For each vehicle, a stop sequence that minimizes total travel distance (TSP variant)

This is a variant of the Capacitated Vehicle Routing Problem (CVRP), which is NP-hard. Exact solutions are computationally infeasible for real-world fleet sizes. We need heuristics that produce near-optimal solutions in bounded time.

Step 1: Capacitated Clustering

The first stage assigns passengers to vehicles. This is not standard k-means — we have hard capacity constraints.

Why k-means Doesn't Work Directly

Standard k-means minimizes intra-cluster variance without any constraint on cluster size. In transport routing, an unconstrained cluster might assign 40 passengers to a 25-seat vehicle. You could run k-means and then redistribute overflow, but that post-hoc rebalancing tends to break geographic compactness.

Our Approach: Constrained k-means with Multi-Restart

We use a modified k-means that enforces capacity during assignment, combined with a swap-based local search to escape local minima.

def capacitated_clustering(passengers, k, capacity, n_restarts=12, max_iter=100):
    best_assignment = None
    best_cost = float('inf')

    for _ in range(n_restarts):
        # Initialize centroids (k-means++ seeding)
        centroids = kmeans_plus_plus_init(passengers, k)
        assignment = [None] * len(passengers)

        for iteration in range(max_iter):
            cluster_sizes = [0] * k
            # Assignment step: nearest centroid with capacity check
            # Sort passengers by distance to nearest centroid (farthest first)
            # to ensure hard-to-place passengers get priority
            passengers_by_difficulty = sorted(
                range(len(passengers)),
                key=lambda i: min(
                    haversine(passengers[i], centroids[j]) for j in range(k)
                ),
                reverse=True
            )

            for i in passengers_by_difficulty:
                # Find nearest centroid with available capacity
                candidates = sorted(
                    range(k),
                    key=lambda j: haversine(passengers[i], centroids[j])
                )
                for j in candidates:
                    if cluster_sizes[j] < capacity:
                        assignment[i] = j
                        cluster_sizes[j] += 1
                        break

            # Update step: recompute centroids
            new_centroids = compute_centroids(passengers, assignment, k)
            if centroids_converged(centroids, new_centroids):
                break
            centroids = new_centroids

        # Local search: try swapping passengers between clusters
        assignment = swap_optimization(passengers, assignment, k, capacity)

        cost = total_intra_cluster_distance(passengers, assignment, k)
        if cost < best_cost:
            best_cost = cost
            best_assignment = assignment[:]

    return best_assignment

Key decisions:

k-means++ initialization prevents poor starting configurations. Random init can produce wildly different results between runs.
Farthest-first assignment during the constrained step ensures outlier passengers (who have the fewest viable cluster options) get assigned before the easy cases. Without this, outliers end up in distant clusters because all nearby ones filled up.
Multi-restart (typically 10–15 restarts) is critical because the constrained assignment step makes the algorithm more sensitive to initial conditions than standard k-means.
Swap optimization as a post-processing step tries all pairwise swaps between clusters. If swapping passenger A from cluster X with passenger B from cluster Y reduces total distance without violating capacity, the swap is accepted. This catches improvements that the greedy assignment misses.

Complexity

Each restart runs in O(max_iter × n × k) for the assignment step. The swap optimization is O(n² × k) in the worst case but is fast in practice because we only evaluate swaps between geographically adjacent clusters. Total: O(n_restarts × (max_iter × n × k + n²)).

For 1,200 passengers and 40 vehicles with 12 restarts, this completes in under 2 seconds on commodity hardware.

Step 2: Distance Matrix Computation

Before we can sequence stops, we need the pairwise driving distances between all stops in a cluster. This is where the problem stops being pure geometry and becomes an engineering challenge.

Haversine vs. Driving Distance

Great-circle distance (haversine) is fine for clustering — it's a fast proxy for geographic proximity. But for stop sequencing, you need actual road distances. Two stops might be 500m apart as the crow flies but 3km by road if a river separates them.

Batching API Calls

Mapping APIs (Google Maps, Mapbox, HERE) provide distance matrix endpoints. For a route with s stops, we need an s × s matrix — that's s² distance pairs. Most APIs cap matrix requests at 25×25 or similar.

async function computeDistanceMatrix(
  stops: LatLng[],
  batchSize: number = 25
): Promise<number[][]> {
  const n = stops.length;
  const matrix: number[][] = Array.from({ length: n }, () =>
    new Array(n).fill(0)
  );

  // For small matrices, single API call
  if (n <= batchSize) {
    const result = await mapsApi.distanceMatrix({
      origins: stops,
      destinations: stops,
    });
    return parseMatrixResponse(result);
  }

  // For larger matrices, partition into sub-matrices
  for (let i = 0; i < n; i += batchSize) {
    for (let j = 0; j < n; j += batchSize) {
      const originSlice = stops.slice(i, Math.min(i + batchSize, n));
      const destSlice = stops.slice(j, Math.min(j + batchSize, n));

      const result = await mapsApi.distanceMatrix({
        origins: originSlice,
        destinations: destSlice,
      });

      // Fill the corresponding sub-matrix
      const subMatrix = parseMatrixResponse(result);
      for (let oi = 0; oi < originSlice.length; oi++) {
        for (let di = 0; di < destSlice.length; di++) {
          matrix[i + oi][j + di] = subMatrix[oi][di];
        }
      }
    }
  }

  return matrix;
}

Caching Strategy

Distance matrices are expensive (both in latency and API cost). We cache them aggressively:

L1 cache: In-memory LRU for the current optimization session
L2 cache: Database-backed cache keyed on sorted coordinate pairs with a configurable TTL (we use 30 days — road networks don't change that often)
Cache invalidation: Manual purge when an operator reports a new road or closure

For routes with 15–20 stops, the matrix has 225–400 entries. With caching, repeat optimizations (e.g., after adding one passenger) hit ~90%+ cache rate.

Step 3: Stop Sequencing (TSP)

With passengers clustered and the distance matrix computed, each route needs an optimal stop order.

Exact Solution for Small Routes

For routes with ≤ 11 stops, we evaluate all permutations. 11! = 39,916,800 — that's tight but feasible if we prune aggressively:

def tsp_exact(distance_matrix, depot):
    """Exact TSP via branch-and-bound for small instances."""
    n = len(distance_matrix)
    stops = [i for i in range(n) if i != depot]
    best_distance = float('inf')
    best_order = None

    def branch_and_bound(current, remaining, cost_so_far):
        nonlocal best_distance, best_order

        if not remaining:
            total = cost_so_far + distance_matrix[current][depot]
            if total < best_distance:
                best_distance = total
                best_order = [depot] + visited + [depot]
            return

        # Pruning: if current cost already exceeds best, abandon
        if cost_so_far >= best_distance:
            return

        # Lower bound: minimum remaining edge cost
        min_remaining = sum(
            min(distance_matrix[r][j] for j in remaining if j != r)
            for r in remaining
        ) if len(remaining) > 1 else 0
        if cost_so_far + min_remaining >= best_distance:
            return

        for next_stop in sorted(
            remaining,
            key=lambda s: distance_matrix[current][s]
        ):
            visited.append(next_stop)
            branch_and_bound(
                next_stop,
                remaining - {next_stop},
                cost_so_far + distance_matrix[current][next_stop]
            )
            visited.pop()

    visited = []
    branch_and_bound(depot, set(stops), 0)
    return best_order, best_distance

Heuristic for Larger Routes

For routes with 12+ stops, exact solutions become impractical. We fall back to a nearest-neighbor heuristic followed by 2-opt improvement:

def tsp_heuristic(distance_matrix, depot):
    n = len(distance_matrix)
    unvisited = set(range(n)) - {depot}
    tour = [depot]
    current = depot

    # Phase 1: Nearest-neighbor construction
    while unvisited:
        nearest = min(unvisited, key=lambda s: distance_matrix[current][s])
        tour.append(nearest)
        unvisited.remove(nearest)
        current = nearest
    tour.append(depot)

    # Phase 2: 2-opt improvement
    improved = True
    while improved:
        improved = False
        for i in range(1, len(tour) - 2):
            for j in range(i + 1, len(tour) - 1):
                # Cost of current edges
                d_current = (
                    distance_matrix[tour[i-1]][tour[i]] +
                    distance_matrix[tour[j]][tour[j+1]]
                )
                # Cost if we reverse the segment between i and j
                d_new = (
                    distance_matrix[tour[i-1]][tour[j]] +
                    distance_matrix[tour[i]][tour[j+1]]
                )
                if d_new < d_current:
                    tour[i:j+1] = reversed(tour[i:j+1])
                    improved = True

    return tour, tour_distance(tour, distance_matrix)

Why 2-opt? It's O(n²) per pass and typically converges in 2–5 passes. For routes with 15–25 stops, it reliably gets within 2–5% of optimal. More sophisticated approaches (3-opt, LKH) offer diminishing returns for this problem size and don't justify the added complexity.

Mapping API Waypoint Optimization

As an alternative (or validation), we can delegate stop ordering to the mapping API itself. Google Maps' Directions API, for example, accepts optimizeWaypoints: true:

const response = await mapsApi.directions({
  origin: depot,
  destination: depot,
  waypoints: stops.map(s => ({ location: s })),
  optimizeWaypoints: true,
});

// response.routes[0].waypoint_order gives the optimized sequence
const optimizedOrder: number[] = response.routes[0].waypoint_order;

This has the advantage of using real-time traffic data and actual road geometry. The downside: it's a black box, you're rate-limited by the API, and most providers cap waypoints at 23–25 per request.

In practice, we use our own TSP solver as the primary method and cross-reference against the mapping API's ordering for quality validation.

Putting It All Together: The Pipeline

┌─────────────────────────────────────────────────────┐
│  Input: Passenger list (CSV/Excel)                  │
│  [name, address, school, vehicle_capacity]           │
└───────────────────────┬─────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│  Geocoding                                          │
│  address → (lat, lng) via Maps API                  │
│  Flag invalid/ambiguous addresses                   │
└───────────────────────┬─────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│  Capacitated Clustering                             │
│  Constrained k-means + swap optimization            │
│  12 restarts × 100 iterations                       │
│  Output: passenger → vehicle assignment             │
└───────────────────────┬─────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│  Distance Matrix Computation                        │
│  Per-cluster pairwise driving distances             │
│  Batched API calls + multi-layer caching            │
└───────────────────────┬─────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│  Stop Sequencing (TSP)                              │
│  ≤11 stops → exact (branch & bound)                 │
│  >11 stops → nearest-neighbor + 2-opt               │
│  Cross-validate with mapping API                    │
└───────────────────────┬─────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│  Output                                             │
│  Optimized routes with stop sequences               │
│  Distance & time estimates per route                │
│  Route polylines for map visualization              │
└─────────────────────────────────────────────────────┘

For a concrete example: 1,200 passengers across 40 vehicles. The clustering stage runs in ~2 seconds. Distance matrix computation takes 10–30 seconds (depending on cache hit rate). TSP for 40 routes runs in parallel and completes in <1 second. Total wall time: under a minute.

A manual planner doing the same work? 8–10 working days, with routes typically 15–30% longer than our output.

The Hard Parts Aren't the Algorithms

The algorithms above are well-understood CS fundamentals. The genuinely hard engineering problems are:

1. Address Data Quality

Real-world passenger data is messy. Addresses are misspelled, incomplete, or ambiguous. Geocoding "123 Main St" might return 15 results across different cities. We run a multi-pass geocoding pipeline:

Geocode with the full address
If confidence is low, retry with normalized components (street, city, postal code separately)
If still ambiguous, flag for manual review and skip from optimization

Bad coordinates silently poison the entire optimization. A single passenger geocoded to the wrong city can distort an entire cluster.

2. Re-optimization vs. Full Optimization

When 5 new passengers join mid-term, should you re-optimize everything from scratch or surgically insert them into existing routes?

Full re-optimization produces mathematically better results but reshuffles routes that drivers and parents have memorized. We offer both modes:

Full re-optimization: Run the entire pipeline. Best total distance, but maximum disruption.
Incremental insertion: For each new passenger, find the route with available capacity where inserting them increases total distance the least. O(new_passengers × routes × stops_per_route).

def incremental_insert(new_passengers, existing_routes, capacity):
    for passenger in new_passengers:
        best_route = None
        best_position = None
        best_cost_increase = float('inf')

        for route in existing_routes:
            if len(route.passengers) >= capacity:
                continue

            for pos in range(1, len(route.stops)):
                # Cost of inserting at this position
                cost_increase = (
                    distance(route.stops[pos-1], passenger.location) +
                    distance(passenger.location, route.stops[pos]) -
                    distance(route.stops[pos-1], route.stops[pos])
                )
                if cost_increase < best_cost_increase:
                    best_cost_increase = cost_increase
                    best_route = route
                    best_position = pos

        if best_route:
            best_route.insert(best_position, passenger)

3. The Human Override Layer

Algorithmic output is a starting point. Planners need to drag passengers between routes, reorder stops, and apply constraints the algorithm doesn't know about ("this child shouldn't be on the same bus as that child", "this street is under construction").

Every manual override needs to be validated: does the swap violate capacity? Does reordering increase total distance? The system needs to provide instant feedback on the cost impact of every manual change.

Results in Practice

On production data from operations we manage:

Metric	Manual Planning	Algorithmic + Human Review
Planning time (40 routes)	8–10 days	< 2 hours
Avg route distance vs optimal	+20–25%	+2–4%
Capacity utilization std dev	8.3 passengers	2.1 passengers
Routes requiring post-review changes	N/A	~12% get minor tweaks

The algorithmic approach doesn't eliminate human involvement — it reduces it from days of tedious manual work to a focused hour of review and refinement.

How We Built an Instant Live Demo System for Our SaaS Product

Emrah G. — Fri, 30 Jan 2026 11:20:43 +0000

At RouteBot, we build transportation management software used by schools and corporations to optimize routes for thousands of daily passengers. Recently, we launched something that changed how potential customers evaluate our product: an instant live demo with zero signup.

Click a button, and within seconds you're inside a fully functional environment with sample data. No forms. No email verification. No waiting for a sales call.

In this post, I'll share the technical decisions, architecture patterns, and actual code we used to build this system. Whether you're building a SaaS product or just curious about demo infrastructure, I hope you'll find something useful here.

Try our live demo →

The Problem with Traditional Demos
Architecture Overview
Demo Account Generation
Data Seeding Strategy
Frontend Implementation
Security Considerations
Rate Limiting & Abuse Prevention
Cleanup & Resource Management
Lessons Learned

The Problem with Traditional Demos

Before building this system, our demo flow looked like this:

User fills out a contact form
Sales team reaches out within 24-48 hours
Call is scheduled for the following week
30-minute screen share where we show the product
User still doesn't have hands-on experience

The conversion rate was okay, but the time-to-value was terrible. Users had to invest hours before they could actually use the product.

We wanted to flip this completely:

Traditional: Form → Wait → Call → Demo → Decision
New:         Click → Use → Decision

The goal was instant access — get users into the product within seconds.

Architecture Overview

Here's the high-level architecture of our demo system:

┌─────────────────────────────────────────────────────────────────┐
│                        Landing Page                              │
│                    (routebot.com)                                │
│                                                                  │
│    [Try Live Demo] ─────────────────────────────────────────────┤
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Demo Proxy Page                              │
│                  (app.routebot.com/demo)                         │
│                                                                  │
│  1. Create demo account (POST /clients/createdemoaccount)        │
│  2. Login with credentials (POST /clients/login)                 │
│  3. Redirect to dashboard                                        │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Backend API                                  │
│                                                                  │
│  • Generate unique demo company                                  │
│  • Seed sample data (routes, passengers, vehicles)               │
│  • Create temporary credentials                                  │
│  • Apply demo restrictions                                       │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                     MongoDB                                      │
│                                                                  │
│  • Demo companies (auto-expire after 24h)                        │
│  • Sample data per demo instance                                 │
│  • Isolated from production data                                 │
└─────────────────────────────────────────────────────────────────┘

Key decisions:

Same codebase: Demo runs on the same infrastructure as production. No separate "demo environment."
Real isolation: Each demo gets its own company/tenant. Data is completely isolated.
Automatic cleanup: Demo accounts expire and are cleaned up automatically.

Demo Account Generation

The core of the system is the demo account creation endpoint. Here's a simplified version:

// backend/controllers/clients-controller.js

const createDemoAccount = async (req, res, next) => {
  const session = await mongoose.startSession();
  session.startTransaction();

  try {
    // Generate unique identifiers
    const demoId = generateDemoId();
    const companyName = `Demo Company ${demoId}`;
    const email = `demo-${demoId}@demo.routebot.com`;
    const tempPassword = generateSecurePassword();

    // Create demo company
    const company = new Company({
      name: companyName,
      isDemo: true,
      createdAt: new Date(),
      expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24 hours
      settings: getDefaultDemoSettings(),
    });
    await company.save({ session });

    // Create demo admin user
    const hashedPassword = await bcrypt.hash(tempPassword, 12);
    const client = new Client({
      email,
      password: hashedPassword,
      name: "Demo User",
      company: company._id,
      role: "admin",
      isDemo: true,
      permissions: getDemoPermissions(),
    });
    await client.save({ session });

    // Seed sample data
    await seedDemoData(company._id, session);

    await session.commitTransaction();

    // Return credentials (temporary, for immediate login)
    res.status(201).json({
      email,
      tempPassword,
      companyId: company._id,
    });
  } catch (error) {
    await session.abortTransaction();
    return next(new HttpError("Could not create demo account", 500));
  } finally {
    session.endSession();
  }
};

Key Implementation Details

1. Unique Demo IDs

We use a combination of timestamp and random string to ensure uniqueness:

const generateDemoId = () => {
  const timestamp = Date.now().toString(36);
  const random = Math.random().toString(36).substring(2, 8);
  return `${timestamp}-${random}`;
};

2. Temporary Passwords

Demo passwords are randomly generated and only used for the initial login:

const generateSecurePassword = () => {
  return crypto.randomBytes(16).toString("hex");
};

3. Demo Permissions

Demo accounts have restricted permissions — they can view and interact with most features, but certain actions are blocked:

const getDemoPermissions = () => ({
  canViewDashboard: true,
  canManageRoutes: true,
  canViewAnalytics: true,
  canSendSMS: false, // Blocked in demo
  canExportData: false, // Blocked in demo
  canDeleteCompany: false, // Blocked in demo
  canModifyBilling: false, // Blocked in demo
});

Data Seeding Strategy

An empty demo is useless. Users need to see the product with realistic data. Here's how we approach seeding:

// backend/utils/demo-seeder.js

const seedDemoData = async (companyId, session) => {
  // Seed in order of dependencies
  const schools = await seedSchools(companyId, session);
  const vehicles = await seedVehicles(companyId, session);
  const drivers = await seedDrivers(companyId, vehicles, session);
  const passengers = await seedPassengers(companyId, schools, session);
  const routes = await seedRoutes(companyId, vehicles, passengers, session);
  const shifts = await seedShifts(companyId, routes, session);

  return {
    schools: schools.length,
    vehicles: vehicles.length,
    drivers: drivers.length,
    passengers: passengers.length,
    routes: routes.length,
  };
};

Sample Data Templates

We maintain JSON templates for realistic sample data:

// backend/data/demo-templates/passengers.json
const passengerTemplates = [
  {
    name: "Alice Johnson",
    type: "student",
    grade: "5th",
    location: { lat: 40.7128, lng: -74.006 },
    pickupAddress: "123 Main Street",
    parentPhone: "+1555000001",
  },
  {
    name: "Bob Smith",
    type: "student",
    grade: "3rd",
    location: { lat: 40.7148, lng: -74.013 },
    pickupAddress: "456 Oak Avenue",
    parentPhone: "+1555000002",
  },
  // ... 50+ more templates
];

Randomization for Realism

Each demo gets slightly different data to feel authentic:

const seedPassengers = async (companyId, schools, session) => {
  const templates = shuffleArray([...passengerTemplates]);
  const count = getRandomInt(30, 50); // 30-50 passengers per demo

  const passengers = templates.slice(0, count).map((template, index) => ({
    ...template,
    company: companyId,
    school: schools[index % schools.length]._id,
    // Add slight location variance
    location: {
      lat: template.location.lat + (Math.random() - 0.5) * 0.01,
      lng: template.location.lng + (Math.random() - 0.5) * 0.01,
    },
  }));

  return await Passenger.insertMany(passengers, { session });
};

Frontend Implementation

The frontend demo page is a React component that orchestrates the entire flow:

// frontend/src/pages/auth/Demo.js

import React, { useContext, useEffect, useState } from "react";
import { useNavigate } from "react-router-dom";
import { useTranslation } from "react-i18next";
import { useHttpClient } from "shared/hooks/http-hook";
import { AuthContext } from "shared/context/auth-context";
import { getDeviceId } from "shared/util/auth/device-id";
import LoadingSpinner from "shared/components/UIElements/LoadingSpinner";

const Demo = () => {
  const auth = useContext(AuthContext);
  const { t } = useTranslation();
  const { sendRequest } = useHttpClient();
  const navigate = useNavigate();
  const [error, setError] = useState(null);

  useEffect(() => {
    const loginWithDemo = async () => {
      // Already logged in? Redirect to dashboard
      if (auth.isLoggedIn) {
        navigate("/dashboard");
        return;
      }

      try {
        // Step 1: Create demo account
        const created = await sendRequest(
          `${process.env.REACT_APP_BACKEND_URL}/clients/createdemoaccount`,
          "POST",
          JSON.stringify({}),
        );

        // Step 2: Login with demo credentials
        const loginResponse = await sendRequest(
          `${process.env.REACT_APP_BACKEND_URL}/clients/login`,
          "POST",
          JSON.stringify({
            phonenumber: created.email,
            password: created.tempPassword,
            language: "en",
            deviceId: getDeviceId(),
          }),
          { "Content-Type": "application/json" },
        );

        // Step 3: Complete authentication
        await auth.login(loginResponse.id, loginResponse.token);
        // Redirect happens automatically via auth state change
      } catch (err) {
        setError(err?.message || t("anErrorOccurred"));
      }
    };

    loginWithDemo();
  }, [auth, navigate, sendRequest, t]);

  if (error) {
    return (
      <div className="demo-error-container">
        <h1>{t("auth.demoError")}</h1>
        <p>{error}</p>
        <button onClick={() => window.location.reload()}>{t("auth.tryAgain")}</button>
        <button onClick={() => navigate("/login")}>{t("auth.goToLogin")}</button>
      </div>
    );
  }

  return (
    <div className="demo-loading-container">
      <LoadingSpinner />
      <h1>{t("auth.preparingDemo")}</h1>
      <p>{t("auth.pleaseWait")}</p>
    </div>
  );
};

export default Demo;

Device ID for Analytics

We track demo sessions using a device ID (stored in localStorage):

// frontend/src/shared/util/auth/device-id.js

export const getDeviceId = () => {
  let deviceId = localStorage.getItem("deviceId");

  if (!deviceId) {
    deviceId = generateUUID();
    localStorage.setItem("deviceId", deviceId);
  }

  return deviceId;
};

const generateUUID = () => {
  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
    const r = (Math.random() * 16) | 0;
    const v = c === "x" ? r : (r & 0x3) | 0x8;
    return v.toString(16);
  });
};

Security Considerations

Running user-facing demo infrastructure requires careful security planning.

1. Demo Account Isolation

Each demo account is completely isolated at the database level:

// All queries include company filter
const getRoutes = async (companyId) => {
  return await Route.find({ company: companyId });
};

2. Action Restrictions

We use middleware to block sensitive actions:

// backend/middleware/demo-guard.js

const demoGuard = (blockedActions) => {
  return async (req, res, next) => {
    const client = req.userData;

    if (client.isDemo && blockedActions.includes(req.action)) {
      return res.status(403).json({
        message: "This action is not available in demo mode",
        upgradeUrl: "/sign-up",
      });
    }

    next();
  };
};

// Usage
router.post("/send-sms", demoGuard(["SEND_SMS"]), smsController.sendSMS);

3. Rate Limiting Demo Creation

We prevent abuse with rate limiting:

// backend/middleware/rate-limit.js

const demoRateLimiter = rateLimit({
  windowMs: 60 * 60 * 1000, // 1 hour
  max: 5, // 5 demo accounts per IP per hour
  message: {
    error: "Too many demo accounts created. Please try again later.",
  },
  keyGenerator: (req) => {
    return req.ip || req.headers["x-forwarded-for"];
  },
});

router.post("/createdemoaccount", demoRateLimiter, createDemoAccount);

Rate Limiting & Abuse Prevention

Beyond basic rate limiting, we implement several layers of protection:

IP-Based Throttling

const rateLimitConfig = {
  demo: {
    windowMs: 60 * 60 * 1000, // 1 hour
    maxRequests: 5,
    blockDuration: 24 * 60 * 60 * 1000, // 24 hour block after abuse
  },
};

const checkRateLimit = async (ip, action) => {
  const key = `ratelimit:${action}:${ip}`;
  const current = await redis.incr(key);

  if (current === 1) {
    await redis.expire(key, rateLimitConfig[action].windowMs / 1000);
  }

  if (current > rateLimitConfig[action].maxRequests) {
    // Block the IP
    await redis.setex(`blocked:${ip}`, rateLimitConfig[action].blockDuration / 1000, "1");
    throw new Error("Rate limit exceeded");
  }

  return true;
};

Honeypot Fields

We add invisible form fields to catch bots:

<form onSubmit={handleDemoStart}>
  {/* Honeypot - hidden from users, filled by bots */}
  <input type="text" name="website" style={{ display: "none" }} tabIndex="-1" autoComplete="off" />
  <button type="submit">Try Live Demo</button>
</form>

Cleanup & Resource Management

Demo accounts generate data that needs to be cleaned up. We use a scheduled job:

// backend/crons/cleanup-demo-accounts.js

const cleanupDemoAccounts = async () => {
  const expiredDemos = await Company.find({
    isDemo: true,
    expiresAt: { $lt: new Date() },
  });

  for (const company of expiredDemos) {
    const session = await mongoose.startSession();
    session.startTransaction();

    try {
      // Delete all related data
      await Promise.all([
        Client.deleteMany({ company: company._id }, { session }),
        Route.deleteMany({ company: company._id }, { session }),
        Passenger.deleteMany({ company: company._id }, { session }),
        Vehicle.deleteMany({ company: company._id }, { session }),
        Driver.deleteMany({ company: company._id }, { session }),
        // ... other models
      ]);

      // Delete the company
      await Company.deleteOne({ _id: company._id }, { session });

      await session.commitTransaction();
      console.log(`Cleaned up demo company: ${company._id}`);
    } catch (error) {
      await session.abortTransaction();
      console.error(`Failed to cleanup: ${company._id}`, error);
    } finally {
      session.endSession();
    }
  }
};

// Run every hour
cron.schedule("0 * * * *", cleanupDemoAccounts);

Monitoring Demo Usage

We track demo metrics for insights:

const trackDemoMetrics = async (action, metadata) => {
  await DemoAnalytics.create({
    action,
    timestamp: new Date(),
    ip: metadata.ip,
    userAgent: metadata.userAgent,
    deviceId: metadata.deviceId,
    duration: metadata.duration,
  });
};

// Track demo creation
await trackDemoMetrics("DEMO_CREATED", {
  ip: req.ip,
  userAgent: req.headers["user-agent"],
});

// Track demo exploration
await trackDemoMetrics("FEATURE_EXPLORED", {
  feature: "route-optimization",
  deviceId: req.body.deviceId,
});

Lessons Learned

After running this system in production for several months, here's what we've learned:

1. Instant Access Dramatically Increases Engagement

Our demo-to-signup conversion improved by 3x after removing the signup barrier. Users who experience the product firsthand are much more likely to create a real account.

2. Sample Data Quality Matters

Early versions had obviously fake data ("Test User 1", "123 Fake Street"). Users didn't take the demo seriously. Investing in realistic sample data made a huge difference.

3. Demo Restrictions Need UX Consideration

When users hit a restriction (like trying to send SMS), don't just show an error. Explain why it's blocked and how to unlock it:

<Modal>
  <h3>SMS is disabled in demo mode</h3>
  <p>Create a free account to send real notifications to passengers.</p>
  <Button href="/sign-up">Create Account</Button>
</Modal>

4. Monitor for Abuse Early

We underestimated how quickly bad actors would find the endpoint. Implement rate limiting and monitoring from day one.

5. Keep Demo Environment in Sync with Production

Running demos on the same codebase as production means every new feature is automatically available in demos. This was a great decision.

Conclusion

Building an instant demo system was one of the best investments we made for RouteBot. It reduced friction, increased engagement, and gave potential customers the confidence to make decisions faster.

If you're building a SaaS product and still relying on traditional demo calls, consider giving users direct access. The technical challenges are solvable, and the impact on conversions is significant.

Want to see how it works? Try our live demo →

Resources

If you found this useful, follow me for more technical deep-dives on SaaS development. Questions? Drop a comment below!

A GitBook-Style Docs Site with Next.js (App Router), Markdown, SEO, and Cloudflare Workers

Emrah G. — Tue, 20 Jan 2026 22:19:45 +0000

Why build your own docs site?

If you already write your documentation in Markdown, the best docs site is often the one that:

Requires zero code changes when you add a new .md file
Feels like GitBook: sidebar navigation, table of contents, next/previous links
Ships with great SEO defaults: canonical URLs, Open Graph, Twitter cards, sitemap, robots, structured data
Deploys as static assets so it’s fast, cheap, and easy to host

That’s exactly what we built for RouteBot’s documentation, available here:

RouteBot Docs: https://docs.routebot.com/

This article walks through the architecture and key implementation details so you can replicate (or adapt) it for your own product.

What we built (feature checklist)

Markdown-powered content pipeline
- Auto-discovers Markdown files from a content/ directory
- Uses filename prefixes (e.g., 01-, 02-) for ordering
- Extracts title/description automatically if frontmatter is missing
GitBook-like UI
- Collapsible category sidebar
- “On this page” table of contents (H2–H4)
- Breadcrumbs
- Prev/Next navigation
Search
- Build-time generated JSON index
- Client-side search modal
SEO
- Per-page metadata (title/description/canonical)
- Open Graph & Twitter cards
- JSON-LD (article + breadcrumbs)
- Static robots.txt + sitemap.xml
Great UX
- Scroll resets to top on navigation
- Support email is copy-to-clipboard (not mailto:)
Deployment
- Next.js static export (out/)
- Cloudflare Workers with Static Assets (wrangler.jsonc)

Tech stack

Next.js 14 (App Router) with static export
Tailwind CSS + @tailwindcss/typography for clean Markdown rendering
remark + remark-gfm + remark-html for Markdown → HTML
gray-matter for optional frontmatter
Cloudflare Workers + Static Assets for hosting the static output

Project structure (high level)

This is the mental model:

content/<variant>/<language>/*.md — your Markdown source of truth
src/lib/docs.js — content loader + TOC extraction + navigation model
src/app/[slug]/page.js — the doc page route (SSG)
src/app/sitemap.js + src/app/robots.js — SEO essentials
src/app/search-index.json/route.js — build-time JSON search index endpoint
src/components/* — UI pieces (sidebar, TOC, search modal, etc.)
next.config.js — output: "export" for static export
wrangler.jsonc — Cloudflare Workers static assets config

1) Markdown pipeline: auto-discovery, slugs, titles, and descriptions

The heart of the system is a function that scans the content directory, then derives everything needed to generate pages:

slug from filename (removing the numeric prefix)
order from filename prefix (so navigation is stable)
title from frontmatter or the first # H1
description from frontmatter or the first non-heading paragraph
lastModified from the filesystem (used for sitemap + “last updated”)

Here’s the core idea (simplified from our implementation):

import fs from "fs";
import path from "path";
import matter from "gray-matter";

const DOCS_DIRECTORY = path.join(process.cwd(), "content", process.env.CONTENT_DIR);

export async function getAllDocs() {
  const files = fs.readdirSync(DOCS_DIRECTORY);

  return files
    .filter((file) => file.endsWith(".md") && file !== "README.md")
    .map((file) => {
      const filePath = path.join(DOCS_DIRECTORY, file);
      const fileContent = fs.readFileSync(filePath, "utf-8");
      const { data: frontmatter, content } = matter(fileContent);

      const titleMatch = content.match(/^#\s+(.+)$/m);
      const title = frontmatter.title || (titleMatch ? titleMatch[1] : file.replace(".md", ""));

      const descriptionMatch = content.match(/^[^#\n].+$/m);
      const description =
        frontmatter.description || (descriptionMatch ? descriptionMatch[0].slice(0, 160) : "");

      const slug = file.replace(".md", "").replace(/^\d+-/, "").toLowerCase();
      const orderMatch = file.match(/^(\d+)-/);
      const order = orderMatch ? parseInt(orderMatch[1], 10) : 999;

      const stats = fs.statSync(filePath);

      return { slug, title, description, fileName: file, order, lastModified: stats.mtime.toISOString() };
    })
    .sort((a, b) => a.order - b.order);
}

Why filename prefixes beat manual nav config

This approach avoids maintaining a hard-coded nav tree in code.

Add 31-new-feature.md → it appears automatically
Rename it to 05-new-feature.md → it moves automatically
You can still add frontmatter later, but you don’t need it to get started

2) Markdown → HTML rendering (with GFM) + Table of Contents

For output, we convert Markdown into HTML at build time using remark:

import { remark } from "remark";
import remarkGfm from "remark-gfm";
import remarkHtml from "remark-html";

const processedContent = await remark()
  .use(remarkGfm)
  .use(remarkHtml, { sanitize: false })
  .process(markdownContent);

const html = processedContent.toString();

For the TOC, we extract headings (H2–H4) and generate stable IDs:

function extractHeadings(content) {
  const headingRegex = /^(#{2,4})\s+(.+)$/gm;
  const headings = [];
  let match;

  while ((match = headingRegex.exec(content)) !== null) {
    const level = match[1].length;
    const text = match[2];
    const id = text.toLowerCase().replace(/[^\w\s-]/g, "").replace(/\s+/g, "-");
    headings.push({ level, text, id });
  }

  return headings;
}

Tailwind Typography (prose) makes the HTML look great with almost no extra work.

3) Navigation: categories derived from filename patterns

To get a GitBook-like sidebar, we group pages into categories based on filename prefixes.

Instead of annotating every Markdown file, we define category rules once:

const CATEGORIES = [
  { name: "Getting Started", pattern: /^(01|02)/, order: 1 },
  { name: "User Management", pattern: /^(05|06|07|08)/, order: 2 },
  { name: "Help & Support", pattern: /^(27|28)/, order: 3 },
];

Then build a navigation model:

export async function getNavigation() {
  const docs = await getAllDocs();
  const categoryMap = new Map();

  docs.forEach((doc) => {
    const category = CATEGORIES.find((cat) => cat.pattern.test(doc.fileName)) || { name: "Other", order: 999 };
    if (!categoryMap.has(category.name)) categoryMap.set(category.name, { name: category.name, order: category.order, items: [] });
    categoryMap.get(category.name).items.push(doc);
  });

  categoryMap.forEach((cat) => cat.items.sort((a, b) => a.order - b.order));
  return Array.from(categoryMap.values()).sort((a, b) => a.order - b.order);
}

This keeps authoring dead simple: you just drop Markdown files into content/ and follow a naming convention.

4) Routing: clean URLs without redundant prefixes

We serve docs at:

https://docs.routebot.com/welcome/

not:

https://docs.routebot.com/docs/welcome/

In Next.js App Router, that’s as simple as placing the route at:

src/app/[slug]/page.js

And for static builds, we generate params from the Markdown files:

export async function generateStaticParams() {
  const docs = await getAllDocs();
  return docs.map((doc) => ({ slug: doc.slug }));
}

5) SEO: metadata, canonical URLs, and JSON-LD structured data

We generate metadata per page using the Markdown-derived title/description, and always emit a canonical URL:

export async function generateMetadata({ params }) {
  const doc = await getDocBySlug(params.slug);
  const url = `${process.env.NEXT_PUBLIC_SITE_URL}/${params.slug}`;

  return {
    title: doc.title,
    description: doc.description,
    alternates: { canonical: url },
    openGraph: { title: doc.title, description: doc.description, url, type: "article" },
    twitter: { card: "summary", title: doc.title, description: doc.description },
  };
}

JSON-LD (TechArticle + BreadcrumbList)

Structured data helps search engines understand what your pages represent. We include:

TechArticle with publish/modified times
BreadcrumbList matching the UI

The pattern looks like:

<script
  type="application/ld+json"
  dangerouslySetInnerHTML={{ __html: JSON.stringify({ "@context": "https://schema.org", "@type": "TechArticle", headline: title }) }}
/>;

6) `sitemap.xml` + `robots.txt` generated from content

Because we already have a complete list of docs (and their timestamps), sitemap generation is trivial.

In src/app/sitemap.js we return an array of URLs:

import { getAllDocs } from "@/lib/docs";
import { SITE_URL } from "@/lib/config";

export default async function sitemap() {
  const docs = await getAllDocs();
  return [
    { url: SITE_URL, lastModified: new Date(), changeFrequency: "weekly", priority: 1.0 },
    ...docs.map((doc) => ({
      url: `${SITE_URL}/${doc.slug}`,
      lastModified: doc.lastModified,
      changeFrequency: "weekly",
      priority: doc.order <= 2 ? 1.0 : 0.8,
    })),
  ];
}

And robots.txt points to it:

export default function robots() {
  return {
    rules: { userAgent: "*", allow: "/" },
    sitemap: `${process.env.NEXT_PUBLIC_SITE_URL}/sitemap.xml`,
  };
}

7) Build-time search index + client-side search modal

To keep hosting simple, we generate a JSON search index at build time and ship it with the static output.

Search index endpoint

src/app/search-index.json/route.js returns a JSON array with caching headers:

export async function GET() {
  const searchIndex = await getSearchIndex();
  return Response.json(searchIndex, { headers: { "Cache-Control": "public, max-age=3600" } });
}

export const dynamic = "force-static";

Client search UX

On the client, a modal loads /search-index.json once, then scores matches by:

title hits (high score)
content hits (bounded)

This gives you instant, offline-ish docs search with no external services.

8) UX details that matter

Scroll to top on navigation

Static docs sites often feel “off” if the scroll position is preserved between pages. A tiny client component fixes it:

"use client";
import { useEffect } from "react";
import { usePathname } from "next/navigation";

export function ScrollToTop() {
  const pathname = usePathname();
  useEffect(() => {
    window.scrollTo({ top: 0, left: 0, behavior: "instant" });
  }, [pathname]);
  return null;
}

Copy-to-clipboard support email (no mailto)

Many users don’t want mailto: links. In the sidebar we display the email in a monospace pill and copy it on click:

await navigator.clipboard.writeText(supportEmail);

9) Static export configuration (Next.js)

In next.config.js, we enable static export:

const nextConfig = {
  output: "export",
  images: { unoptimized: true },
  trailingSlash: true,
  poweredByHeader: false,
};

module.exports = nextConfig;

This generates a fully static site in out/ — perfect for CDN hosting.

10) Deployment to Cloudflare Workers with Static Assets

Cloudflare Workers can host static sites by uploading your out/ directory as assets.

Our wrangler.jsonc is intentionally minimal:

{
  "$schema": "https://json.schemastore.org/wrangler.json",
  "compatibility_date": "2026-01-19",
  "assets": {
    "directory": "./out"
  }
}

Then deploy:

npm run build
npx wrangler deploy

Notes:

If you have multiple deployments (different domains/content variants), it can be convenient to omit a hard-coded name in wrangler.jsonc and let your Cloudflare project settings define it.
On Windows PowerShell, npm run build && npx wrangler deploy may require using ; instead of &&.

11) Multi-variant docs from one codebase (content type + language)

Even if you don’t need it today, it’s worth designing for multiple docs “variants”:

product docs vs. customer help
different domains per locale
separate SEO identities

We drive that with environment variables:

NEXT_PUBLIC_SITE_URL="https://docs.routebot.com"
NEXT_PUBLIC_LANGUAGE="en"
NEXT_PUBLIC_CONTENT_TYPE="admin"
CONTENT_DIR="admin/en"

The rest of the system (content loading, sitemap, metadata, UI strings) reads from those values.

Final notes + next improvements

If you want to take this even further:

Add syntax highlighting (e.g., rehype-pretty-code)
Add “Edit this page” links (pointing to your Git repo)
Add versioned docs (/v1/, /v2/) with separate sitemaps
Add Algolia/Meilisearch for large doc sets (1000+ pages)

If you’d like to browse the live result, start here:

RouteBot Docs: https://docs.routebot.com/

Running Transportation Operations in Production Before Going Public

Emrah G. — Fri, 19 Dec 2025 05:50:37 +0000

For most B2B software products, the public launch comes early.

A landing page, a signup form, a demo video — and then the real learning starts.

We did the opposite.

RouteBot has been running inside real, large-scale transportation operations for over three years before we ever talked about it publicly.

This post is about why we waited, what breaks first in transportation operations, and why we’re only now opening guided walkthroughs.

Excel works — until it doesn’t

Almost every transportation operation starts with Excel.

Routes, vehicles, students, drivers, schedules — all manageable at first.

But as operations grow, Excel starts to show its limits:

Files get duplicated
Versions drift
Manual coordination increases
Small mistakes turn into daily operational issues

What breaks isn’t routing algorithms first.

What breaks is coordination.

RouteBot was built to sit exactly at that breaking point — where Excel still exists, but can no longer be the system of record.

Why we didn’t launch early

For a long time, RouteBot wasn’t something you could simply “sign up” for.

There was no free trial.

No public demo.

No onboarding flow.

Instead, it was used quietly inside real operations, with real data, real constraints, and real consequences.

That time mattered.

It allowed us to:

Observe how operations actually run day to day
Understand where manual workflows fail under pressure
Design onboarding around existing Excel data instead of forcing migrations
Build the product around operational reality, not assumptions

By the time we considered opening it up, the product was already battle-tested.

Why we still don’t offer self-serve demos

Transportation operations are not self-serve problems.

Data structures differ.

Constraints differ.

Operational priorities differ.

A generic “click around” demo rarely shows what actually matters.

That’s why we’ve chosen a guided, founder-led walkthrough model instead.

Not to limit access — but to make sure what you see actually reflects how RouteBot would run in your operation.

What’s available now

We’ve recently opened two things publicly:

A fully populated live demo environment
Structured, founder-led walkthrough sessions

The live environment shows how RouteBot looks when it’s already running:

vehicles, routes, students, and daily operations — all in place.

The walkthroughs are where we:

Map your current Excel-based workflows
Show how those translate into a live operational system
Decide together whether RouteBot is a good fit

No pitching.

No generic demos.

Just a practical evaluation.

Going public — carefully

Opening something up doesn’t always mean scaling fast.

Sometimes it just means being more visible.

RouteBot is now ready to be seen more broadly — not because it’s new, but because it’s already proven.

If you’re running transportation operations and Excel is starting to feel fragile, you’ll probably recognize the problems we’ve been working on.

Founder-led walkthroughs are now open worldwide, starting January.

More details here:

👉 https://routebot.com

Opening Modals with Hash Listeners: A Simple JavaScript Pattern

Emrah G. — Wed, 10 Sep 2025 04:58:49 +0000

Sometimes you want to share a URL that opens a modal dialog immediately.

Instead of forcing users to click buttons, you can leverage hash fragments (#something) and the native hashchange event to trigger the modal.

This approach works with plain JavaScript (or any framework like React, Vue, or Svelte) and keeps your app deep-linkable.

🚀 The Core Idea

Listen for the hashchange event on window.
When the URL hash matches your trigger (#upgrade, for example), open the modal.
Clean up the hash so it can be triggered again later.

🛠️ The `handleOpenModal` Function

Here’s a simplified version of the logic:

function handleOpenModal() {
  // Only trigger if the hash includes our keyword
  if (window.location.hash.toLowerCase().includes("#upgrade")) {

    // Open the modal (pseudo-code)
    openModal();

    // Clean the hash so the same link can be used again
    const { pathname, search, hash } = window.location;
    let cleanedHash = hash.replace("#upgrade", "").trim();

    const newUrl = pathname + search + (cleanedHash ? `#${cleanedHash}` : "");

    try {
      // Replace the current history entry so the back button isn’t broken
      window.history.replaceState(window.history.state, "", newUrl);
    } catch {
      // Fallback in stricter environments
      window.location.replace(newUrl);
    }
  }
}

You would also need to attach this function:

window.addEventListener("hashchange", handleOpenModal, { passive: true });

🔑 Why This Works

Shareable deep links → In my case I send https://routebot.com + #upgrade (like mysite.com#upgrade) and the modal opens right away.

Back button safety → Cleaning the hash prevents broken navigation.

Reusable → Same link can open the modal multiple times.

🌍 Real-World Use Case

I use this exact technique in RouteBot 🚍, where admins can send deep links that trigger upgrade flows or onboarding modals instantly.

Instead of saying “click here, then press upgrade”, one URL just opens the right dialog.

✅ Wrap-Up

Hash listeners are a lightweight, framework-agnostic solution for modals triggered by links.

No extra query params

No heavy router logic

Just plain JavaScript

If you’re building SaaS, consider this pattern to simplify onboarding or upgrades.
And if you’re into transport SaaS and optimization, check out RouteBot
— we use patterns like this every day. 🚀

Building Smarter School & Staff Transportation: Lessons From RouteBot

Emrah G. — Mon, 18 Aug 2025 07:43:44 +0000

Managing school buses and staff transportation isn’t as simple as putting people on a map and drawing lines.

Behind every “bus is arriving in 3 minutes” notification, there’s a ton of logistics, optimization, and real-time data crunching.

At RouteBot, we set out with a simple but ambitious goal: make transportation intelligent, efficient, and transparent.

Why Traditional Methods Don’t Work Anymore

If you’ve ever been involved in school or employee transportation planning, you know the pain points:

Endless Excel sheets with manual route assignments.
Paper-based schedules that go out of sync the moment one student changes address.
Parents and staff constantly calling: “Where’s the bus right now?”
High costs due to inefficient routing and fuel waste.

These challenges are exactly why SaaS solutions are reshaping the industry.

From Spreadsheets to Smart SaaS

Instead of static planning, RouteBot applies intelligent route optimization algorithms that adapt to real-world conditions.

Think of it as moving from paper maps to a navigation system with live traffic updates.

Some highlights:

Route Optimization → minimize distance and fuel costs.
Live Tracking → see where every vehicle is in real-time.
Communication Built-In → SMS notifications to parents & staff, without extra steps.
Scalable Architecture → works whether you manage 5 vehicles or 500.

Developer’s Perspective

What excited me most as a builder wasn’t just “tracking buses” but designing a system that scales.

How do you handle thousands of live location updates per minute?

How do you send notifications without spamming or delays?

How do you build dashboards that are clear for schools but also flexible for enterprise fleets?

These are the kinds of questions we had to solve — and they’re what make transportation software such a unique engineering challenge.

See It in Action

We recently published a detailed breakdown of our approach, including architecture and real screenshots, on the RouteBot blog.

If you’re curious about the live demo of the system in action, check it out here:

👉 Revolutionizing Intelligent Transport With Live Demo

Final Thoughts

Transportation might sound old-school, but the truth is: it’s one of the last industries being disrupted by SaaS.

If you’re a developer, there’s a fascinating mix of algorithms, real-time systems, and UX challenges to explore.

If you’re an operator, there’s finally a way to move beyond spreadsheets and give parents, staff, and managers peace of mind.

At the end of the day, the mission is simple: safer, smarter, and more reliable rides.

✍️ Curious about the tech details or the journey behind RouteBot? Drop a comment — I’d love to geek out about routing, real-time systems, and SaaS growth stories.

Pure CSS Shine Animation & Corner Cut-Out: Shimmering Cards Without JS

Emrah G. — Thu, 14 Aug 2025 05:14:20 +0000

Shimmering cards with a diagonal shine + a rosette-friendly corner cut-out — built only with CSS.

Modern UI often needs subtle flair without sacrificing performance. In this guide we’ll combine two small but high-impact techniques:

A shine animation that softly glides across the card on hover.
A corner cut-out that creates space for a “Popular”/“Pro” badge.

Both are pure CSS, accessible, and production-friendly.

TL;DR

Animate a large, rotated overlay gradient with transform for smooth GPU-accelerated motion.
Create a corner cut-out using either a pseudo-element + box-shadow trick (broad compatibility) or a CSS mask (cleaner, modern).
Respect prefers-reduced-motion and ensure readable contrast.

Minimal HTML Skeleton

<div class="card">
  <div class="shine" aria-hidden="true"></div>
  <div class="badge">Popular</div>
  <div class="content">
    <!-- your card content -->
  </div>
  <div class="cutout" aria-hidden="true"></div>
</div>

No frameworks needed — we’ll focus on CSS only.

The Shine Animation

The shine is a large diagonal band moving across the card. We render it as an absolutely positioned overlay, then translate it from corner to corner.

.card {
  position: relative;
  overflow: hidden;
  border-radius: 22px;
  background: linear-gradient(33deg, #dff69b 0%, #95e79b 35%, #80de8e 70%, #a9f9b2 100%);
}

/* the moving band */
.shine {
  position: absolute;
  inset: 0;
  width: 200%;
  height: 200%;
  pointer-events: none;
  opacity: 0;
  transition: opacity 300ms ease;
  background: linear-gradient(
    180deg,
    rgba(248,255,228,0) 0%,
    rgba(248,255,228,0.8) 50%,
    rgba(248,255,228,0) 100%
  );
  transform: translate(-100%, -100%) rotate(45deg);
  z-index: 1;
}

.card:hover .shine {
  opacity: 1;
  animation: shine 3s linear infinite;
}

@keyframes shine {
  from { transform: translate(-100%, -100%) rotate(45deg); }
  to   { transform: translate(200%,  200%)  rotate(45deg); }
}

Why width/height: 200% and rotate(45deg)?

200% size ensures the band covers the card completely during the whole travel — no clipped edges.

45° creates a neat diagonal “sweep” that feels natural on rectangular cards.

Performance notes

Animate transform, not background-position. transform leverages GPU and remains smooth.

Keep the overlay non-interactive with pointer-events: none.

Consider will-change: transform only if you actually see performance hiccups.

Reduced motion

@media (prefers-reduced-motion: reduce) {
  .card:hover .shine {
    animation: none;
    opacity: .35; /* static highlight */
  }
}

The Corner Cut-Out

We’ll cover two approaches:

A) Pseudo-element + Box-Shadow Trick (robust, easy to theme)

We fake an “erased” corner by placing a rounded square pseudo-element and pushing a white (or page background) shadow inward, so it looks like a chunk is missing.

.cutout {
  --corner-size: 32px;
  --corner-radius: 14px;
  --offset-right: 20px;
  --offset-top: 3px;
  --shadow-1: 1px;
  --shadow-2: 4px;

  position: absolute;
  top: var(--offset-top);
  right: var(--offset-right);
  width: 85px;  /* total cut-out area (helps control the composition) */
  height: 38px;
  pointer-events: none;
  background: transparent;
  overflow: hidden;
  z-index: 2; /* above the gradient bg, below content if needed */
}

.cutout::before,
.cutout::after {
  content: "";
  position: absolute;
  width: var(--corner-size);
  height: var(--corner-size);
  top: 1px;
  right: 20px;
  border-bottom-left-radius: var(--corner-radius);
  background: transparent;
}

.cutout::before { box-shadow: -1px 1px white; }
.cutout::after  { box-shadow: -4px 5px white; }

If your page background isn’t white, replace white with a variable that matches the actual outer background.

B) Real Hole with CSS Mask (clean, modern)

Masks let you truly subtract pixels so the page background shows through.

.card {
  --r: 14px; /* radius */
  -webkit-mask: radial-gradient(
    circle var(--r) at right var(--r) top var(--r),
    transparent calc(var(--r) - 0.5px),
    #000       calc(var(--r) + 0.5px)
  );
  mask: radial-gradient(
    circle var(--r) at right var(--r) top var(--r),
    transparent calc(var(--r) - 0.5px),
    #000       calc(var(--r) + 0.5px)
  );
}

The tiny 0.5px buffer helps anti-aliasing on different pixel densities. Test on Safari; older versions might need the -webkit- prefix only.

Layering: Z-Index & Hit Testing

Keep the content above backgrounds (z-index > shine/cut-out).

The shine should be visually above the background but not clickable.

For the badge, place it near the cut-out and ensure it sits above the shine (e.g., z-index: 3).

.badge {
  position: absolute;
  top: 10px;
  right: 20px;
  font: 600 12px/1 system-ui, sans-serif;
  text-transform: uppercase;
  z-index: 3;
}
.content { position: relative; z-index: 2; }

Theming with CSS Variables

Centralize constants for easy design tweaks:

:root {
  --radius: 22px;
  --badge-h: 35px;
  --badge-w: 95px;

  /* cut-out */
  --corner-size: 32px;
  --corner-radius: 14px;

  /* shine */
  --shine-angle: 45deg;
  --shine-duration: 3s;
}

Common Pitfalls & Fixes

Band “tears” at edges: Ensure overlay is bigger than the card (200%) and fully traverses the diagonal.

Gradient banding: Use 3+ color stops or add a subtle translucent white layer (as in the examples) to smooth it out.

Wrong cut-out color: For the pseudo-element trick, make the shadow color match the actual page background.

Mask aliasing in Safari: Use a tiny ±0.5px tolerance around the radius.

Copy-Paste Snippets

Minimal Shine

.card { position: relative; overflow: hidden; border-radius: 22px; }
.shine {
  position: absolute; inset: 0; width: 200%; height: 200%;
  background: linear-gradient(180deg, transparent, rgba(255,255,255,.8), transparent);
  transform: translate(-100%,-100%) rotate(45deg);
  opacity: 0; pointer-events: none;
}
.card:hover .shine { opacity: 1; animation: shine 3s linear infinite; }
@keyframes shine {
  from { transform: translate(-100%,-100%) rotate(45deg); }
  to   { transform: translate(200%,200%)  rotate(45deg); }
}

Minimal Cut-Out (pseudo-element)

.cutout{position:absolute;top:3px;right:40px;width:85px;height:38px;pointer-events:none}
.cutout::before,.cutout::after{
  content:"";position:absolute;top:1px;right:20px;width:32px;height:32px;border-bottom-left-radius:14px;background:transparent
}
.cutout::before{box-shadow:-1px 1px white}
.cutout::after{box-shadow:-4px 5px white}

Minimal Cut-Out (mask)

.card{
  --r:14px;
  -webkit-mask:radial-gradient(circle var(--r) at right var(--r) top var(--r),
    transparent calc(var(--r) - .5px), #000 calc(var(--r) + .5px));
          mask:radial-gradient(circle var(--r) at right var(--r) top var(--r),
    transparent calc(var(--r) - .5px), #000 calc(var(--r) + .5px));
}

A Scalable Route Optimization System for School & Staff Transportation

Emrah G. — Sun, 10 Aug 2025 21:35:09 +0000

Managing transportation for schools or companies is harder than it looks.

Traditional methods like Excel sheets, manual planning, and paper-based routes are time-consuming, error-prone, and costly.

In this post, I’ll share how we engineered RouteBot, a SaaS product for school bus tracking, route optimization, and fleet management — including our tech stack, optimization challenges, and lessons learned.

🚍 The Problem

School and personnel transportation services face common challenges:

Inefficient Routes → Manual planning wastes time and increases fuel costs.
Lack of Real-Time Tracking → Parents and managers can't see where vehicles are.
Communication Delays → Delayed SMS/phone updates cause frustration.
Poor Data Management → Managing hundreds of students/employees manually leads to mistakes.

We wanted to solve all of these in a single system.

💡 Our Solution: RouteBot

RouteBot is a transportation management SaaS that combines:

Route Optimization → Using Google Maps API + custom algorithms.
Real-Time Vehicle Tracking → Live GPS data from driver mobile apps.
Multi-Role Access → Admin, driver, and passenger/parent portals.
Automated Notifications → SMS alerts for arrivals, delays, and route changes.
Scalable Architecture → Capable of handling thousands of vehicles.

We designed it to work for schools, corporations, and service providers with minimal onboarding time.

🛠 Tech Stack

We kept the tech stack JavaScript-first for speed and maintainability:

Frontend: React + Material UI
Backend: Node.js, Express, Mongoose
Database: MongoDB
Mapping & Optimization: Google Maps APIs (Directions, Distance Matrix, Geocoding)
Hosting: Heroku (planning migration to Vercel + containerized services)

🏗 Architecture Overview

While RouteBot appears simple to the end user — a web dashboard, a mobile app, and live maps — the architecture behind it is designed for high scalability, maintainability, and performance.

At a high level, the system is composed of four main layers:

Client Layer (React Frontend)
- Technology: React + Material UI
- Responsibilities:
  - Provides responsive dashboards for admins, parents, and drivers.
  - Handles real-time map rendering via Google Maps JavaScript API.
  - Uses context-based state management to keep route data, GPS updates, and notifications synchronized without redundant API calls.
  - Implements authentication flows and role-based UI components.
API Gateway & Backend Services (Node.js + Express)
- Technology: Node.js, Express, Mongoose
- Responsibilities:
  - Exposes REST and WebSocket endpoints for client communication.
  - Manages authentication, authorization, and session control.
  - Processes route optimization requests, calling Google Maps APIs and our custom clustering algorithms.
  - Acts as a central hub for events — triggering notifications, dispatching updates, and queuing background jobs.
Data Layer (MongoDB)
- Responsibilities:
  - Stores all entities — users, vehicles, routes, GPS logs, and notification history.
  - Uses geospatial indexes to quickly query nearest stops and optimize route calculations.
  - Supports time-series storage for GPS data, making historical route playback possible.
External Integrations & Services
- Google Maps APIs: Directions, Distance Matrix, Geocoding for route planning.
- SMS Provider: Sends alerts, reminders, and confirmations.
- Push Notifications Service: Delivers mobile updates instantly to parents and drivers.
- Analytics & Monitoring Tools: Tracks performance, errors, and user behavior.

Data Flow Example:

[Client (React)]
   ↓  HTTPS / WebSocket
[Backend API (Node.js + Express)]
   ↓  MongoDB Queries / Writes
[MongoDB Database] ↔ [Google Maps APIs / SMS Service / Notification System]

📏 Route Optimization at Scale

One of the hardest parts of building RouteBot was handling complex route assignments for multiple vehicles across dozens (or hundreds) of pickup points.

🚐 The Multiple Salesman Problem

In classic logistics problems, the Travelling Salesman Problem (TSP) is about finding the shortest route visiting all locations once.

In our case, we needed to solve the Multiple Salesman Problem (mTSP) — because we had multiple buses serving different passengers.

Our Approach

Input:

A list of students/employees with precise GPS coordinates.
Vehicle capacity limits.
Pickup/delivery constraints.

Process:

Cluster passengers into groups based on proximity and capacity.
Assign each group to the most efficient vehicle.
Generate stop sequences to minimize travel time.

Output:

Optimized routes for each bus.
Stop order with ETA (Estimated Time of Arrival).
Balanced workloads across vehicles.

🗺 Google Maps API + Custom Clustering

We used Google Distance Matrix API to get accurate travel times between points.

However, calling the API for every possible pair is expensive and slow.

To solve this, we implemented:

Custom clustering to reduce API calls.
Heuristic optimizations for near-real-time route generation.
Caching of distance data for recurring stops.

📡 Real-Time Tracking

Drivers use a lightweight mobile app to send GPS updates every few seconds.

Parents and managers view the live vehicle position in their dashboards.

Key Optimizations:

Compressed location payloads to reduce bandwidth usage.
WebSocket-based live updates for instant map refresh.
Idle detection to pause updates when the vehicle isn’t moving, saving battery and data.

🔔 Automated Notifications

Communication is critical in transportation. We integrated an SMS notification system to keep all stakeholders informed.

Triggers include:

Morning route reminders.
Delay alerts in case of traffic or incidents.
Drop-off confirmations for parents and managers.

Our backend event system ensures:

No redundant messages.
Minimal API cost.
Accurate, real-time triggers.

⚡ Scalability & Performance

From day one, we built RouteBot to scale:

Modular services: separate modules for authentication, routing, notifications, and tracking.
Database indexing for fast location queries.
Async job queues for notifications and heavy processing.

This allows us to handle thousands of vehicles and passengers without performance degradation.

📎 Learn More

We’re publishing more technical deep-dives on our blog:

👉 Visit RouteBot.com

If you’re working on route optimization, fleet management, or real-time tracking, I’d love to connect and exchange ideas.

How I Cleaned Up My Git History Like a Boss (a.k.a. Fixing Wrong Author Emails)

Emrah G. — Tue, 05 Aug 2025 07:25:03 +0000

Sometimes you commit code like a beast...

But sometimes you commit with the wrong identity 😅

That happened to me.

I accidentally pushed a bunch of commits to several of my GitHub repos using a secondary email identity instead of my personal one.

The result? My beautiful Git history was sprinkled with something like:

Author: John Doe <old.email@company.com>

Nope. That’s not what I want to be remembered for.

So here’s how I fixed my Git history like a time-traveling pro — and how you can do it too.

🛠️ Step 1: The Magic Script – `git filter-branch`

This little script saved my soul:

git filter-branch --env-filter '
OLD_EMAIL="old.email@company.com"
CORRECT_NAME="Correct Name"
CORRECT_EMAIL="new.email@example.com"

if [ "$GIT_COMMITTER_EMAIL" = "$OLD_EMAIL" ]
then
    export GIT_COMMITTER_NAME="$CORRECT_NAME"
    export GIT_COMMITTER_EMAIL="$CORRECT_EMAIL"
fi
if [ "$GIT_AUTHOR_EMAIL" = "$OLD_EMAIL" ]
then
    export GIT_AUTHOR_NAME="$CORRECT_NAME"
    export GIT_AUTHOR_EMAIL="$CORRECT_EMAIL"
fi
' --tag-name-filter cat -- --branches --tags

This rewrites all commits in your repo that match the old email and replaces them with the correct name/email combo.

⚠️ Step 2: Push With Caution

Since we’re rewriting history, we need to force push the updated commits:

git push --force --tags origin 'refs/heads/*'

Yes, it’s dangerous.

Yes, it breaks things if others are working on the same repo.

But in my case, it was a solo project. I made sure I wasn’t nuking anyone else's work.

👀 Before & After

Before:

commit 1234567
Author: John Doe <old.email@company.com>

After:

commit 1234567
Author: Correct Name <new.email@example.com>

Peace restored ✌️

🧠 Lessons Learned

Always check your Git config with git config user.email before committing.
Consider setting repo-specific Git configs if you use multiple identities.
If you mess up, don’t panic. Git is powerful enough to undo your mistakes — if you know how to wield it.

📚 Bonus: My Related Post

If you're into Git magic, you might also enjoy:

👉 How to Squash Like a Grand Master

Happy hacking, and may your Git logs forever reflect your true self!

Forem: Emrah G.

Why “School Bus Routing Software” Is Harder Than It Looks

Building WatchContact: An AI Chat Analyzer with OCR, Rate Limiting, and a Content Blog

What We Built

Architecture Overview

1. The AI Chat Analyzer Flow

Two Input Paths

Backend API Endpoints

Rate Limiting: IP-Based, No Auth

OpenAI Analysis

OCR with Tesseract.js

Screenshot Storage: Cloudflare R2

2. Frontend UX Decisions

Single Input Area

ChatGPT-Style Image Preview

Loading Overlay

Example Analysis Card

3. The Blog

4. SEO and Structured Data

5. Deployment Notes

Lessons Learned

Try It

HUD Overlays with Canvas 2D

Architecture Overview

Step 1: Accessing the Camera

Stream Acquisition

The Hidden Video Element

Step 2: The Draw Loop

Why statusRef Instead of status State?

The Blink Phase

Step 3: The HUD Drawing System

Responsive Scaling

The Composition Hierarchy

Theme Dispatcher

Step 4: Drawing the HUD Elements

Vignette Effect

CRT Scanlines

Film Grain / Noise

Animated Scanline Sweep

Corner Brackets

Blinking REC Indicator

Scrolling Terminal Log

Step 5: Theme Deep Dive — Mars Log

Drifting Telemetry Data

Step 6: VHS-Specific Effects

Color Bleed (Chromatic Aberration)

Jitter

Edge Wobble

Tracking Line

Step 7: Recording the Composited Output

Codec Selection

Why 30fps Capture but 60fps Draw?

Download and Share

Step 8: Device Management

Performance Considerations

Putting It All Together

Key Takeaways

Try It Out

How We Solve the Vehicle Routing Problem: Clustering, TSP Heuristics, and Real-World Constraints

The Problem, Formally

Step 1: Capacitated Clustering

Why k-means Doesn't Work Directly

Our Approach: Constrained k-means with Multi-Restart

Complexity

Step 2: Distance Matrix Computation

Haversine vs. Driving Distance

Batching API Calls

Caching Strategy

Step 3: Stop Sequencing (TSP)

Exact Solution for Small Routes

Heuristic for Larger Routes

Mapping API Waypoint Optimization

Putting It All Together: The Pipeline

The Hard Parts Aren't the Algorithms

1. Address Data Quality

2. Re-optimization vs. Full Optimization

3. The Human Override Layer

Results in Practice

Further Reading

How We Built an Instant Live Demo System for Our SaaS Product

Why `statusRef` Instead of `status` State?

6) `sitemap.xml` + `robots.txt` generated from content

🛠️ The `handleOpenModal` Function