System Report ─ terminal.daljeetsingh.me ─ daljeet@portfolio.sh

Overview

What it is

A terminal emulator running in the browser, built on xterm.js and Next.js 14 App Router. It presents a personal portfolio as a navigable virtual filesystem with a Bash-like command interface.

The entire content layer — projects, skills, contact, bio — is driven by a single data file. Adding a project means adding one JSON node; the terminal can immediately navigate, list, and display it without any code changes.

Design principles

Command registry pattern — each module exports a typed command definition array
Single source of truth — all portfolio content from one data file
ANSI formatting abstracted into a helper — no raw escape strings in business logic
Minimal React state: cwd, theme, history, busy flag via Zustand
Dual input: xterm.js for desktop, companion HTML input for mobile compatibility
GitHub data cached server-side and revalidated periodically — no blocking fetch on load

Browser
  ┌────────────────────────────────────────────────────────────┐
  │  page.tsx (RSC)                                            │
  │   ├─ prefetch GitHub snapshot  (ISR cache, server-side)    │
  │   └─ <TerminalWorkbench>  (client component)               │
  │       ├─ xterm.js  →  input handler  →  command parser     │
  │       ├─ HTML input  (mobile / fallback)                   │
  │       ├─ useTerminalStore (Zustand)                        │
  │       └─ executeCommand() → CommandResult                  │
  │           ├─ portfolio module  (whoami / projects / ...)  │
  │           ├─ filesystem module (ls / cd / cat / ...)      │
  │           ├─ github module     (github / ask)              │
  │           │   ├─ GitHub integration  (server-side)        │
  │           │   └─ AI streaming integration (server-side)   │
  │           ├─ theme module      (theme)                     │
  │           ├─ easter-eggs module (neofetch / matrix / ...)  │
  │           └─ utility module    (history / tree / date ...) │
  └────────────────────────────────────────────────────────────┘

Command Reference (30 total)

portfolio(5)filesystem(6)github(2)theme(1)easter-eggs(8)utility(8)

cmd	module	usage	description
help	portfolio	help [cmd]	List every available command with short descriptions
whoami	portfolio	whoami	Display profile — name, title, location, tagline, links
projects	portfolio	projects	Formatted table of all projects with name, stack, URL
skills	portfolio	skills	Skill chart grouped by domain with proficiency bars
contact	portfolio	contact	Show email, GitHub, LinkedIn, and social links
ls	filesystem	ls [path]	List contents of current or target directory
cd	filesystem	cd <path>	Change working directory; supports '..' and absolute paths
pwd	filesystem	pwd	Print current working directory
cat	filesystem	cat <file>	Print file contents; handles binary stubs (resume.pdf)
open	filesystem	open <file>	Open a .url file in a new browser tab
tabhint	filesystem	tabhint	Internal: renders directory listing for Tab autocomplete
github	github	github	Fetch & display live GitHub stats — repos, stars, followers, top repos
ask	github	ask "<question>"	Stream an AI answer grounded in portfolio data (Vercel AI SDK)
theme	theme	theme [name]	Toggle or set a theme; default, matrix, cyber, minimal, dracula
clear	easter-eggs	clear	Clear the terminal buffer (also: Ctrl+L)
neofetch	easter-eggs	neofetch	Detailed system info card with ANSI art (like the real tool)
matrix	easter-eggs	matrix	Full-terminal matrix rain animation (column-drop katakana)
hack	easter-eggs	hack	Theatrical hacking simulation with progress bars
cowsay	easter-eggs	cowsay [message]	Classic ASCII cowsay with dynamic bubble scaling
curl	easter-eggs	curl	Parody curl response mimicking wttr.in weather
sudo	easter-eggs	sudo <cmd>	Access-denied easter egg
rm	easter-eggs	rm -rf <path>	Safe rm -rf stub (no files harmed)
history	utility	history	Show command history for the current session (capped at 50)
tree	utility	tree [path]	Recursive ASCII directory tree from current path
echo	utility	echo <text>	Print arguments to terminal output
date	utility	date	Print current date and time in ISO format
banner	utility	banner <text>	Print ASCII-art banner text
uptime	utility	uptime	Show session uptime since page load
man	utility	man <cmd>	Show manual page for a command
grep	utility	grep <pattern> <file>	Pattern-match lines in a virtual file

Virtual Filesystem

The virtual filesystem is a nested JSON structure — directories are plain objects, files are strings. The terminal traverses it for ls, cd, cat, and Tab autocomplete.

~/
├── bio.txt            — personal introduction text
├── now.txt            — what I'm working on right now
├── resume.pdf         — stub: opens resume URL when using cat
├── projects/
│   ├── janus/
│   │   ├── readme.md
│   │   └── link.url
│   ├── drishti/
│   │   ├── readme.md
│   │   └── link.url
│   ├── sp500-dashboard/
│   │   ├── readme.md
│   │   └── link.url
│   └── ... (more projects)
├── skills/
│   ├── languages.md
│   ├── frameworks.md
│   ├── tools.md
│   └── learning.md
├── contact/
│   ├── email.txt
│   ├── github.url
│   └── linkedin.url
├── secret/
│   └── .credits       — hidden easter egg
└── .config/
    ├── theme.txt
    └── aliases.sh

Theme System

Themes are CSS-variable records. Switching a theme updates both the xterm.js renderer and the page CSS variables simultaneously. Use theme [name] in the terminal, or click a theme name in the sidebar.

default

Deep blue-grey — the base dark theme

bg #060c17·accent #36c8b4

matrix

Classic green phosphor on black

bg #001100·accent #00ff41

cyber

Cyberpunk magenta on near-black

bg #0a0014·accent #ff00ff

minimal

Low-contrast neutral grey palette

bg #111111·accent #888888

dracula

Dracula color scheme — purple+pink

bg #282a36·accent #ff79c6

Tech Stack

package	role
next	Full-stack framework, App Router, ISR, API routes
react	UI with startTransition + useDeferredValue for smooth typing
typescript	Strict mode throughout; zero any casts in library code
@xterm/xterm	VT100/ANSI terminal emulator rendered in Canvas
@xterm/addon-fit	Auto-resize xterm to container dimensions
@xterm/addon-webgl	WebGL renderer; falls back to canvas on unsupported GPU
zustand	Terminal state store: cwd, theme, history, busy flag
ai	Vercel AI SDK — streaming responses for ask command
@ai-sdk/google	Google Gemini 2.0 Flash provider for grounded AI answers
octokit	GitHub REST API — fetch repos, stars, followers
next-pwa	PWA manifest + service worker; installable as desktop app
tailwindcss	Utility CSS; CSS-variable theme system; custom tokens

Live Integrations

GitHub

Live GitHub stats — public repos, total stars, and follower count — are fetched server-side and cached for performance. The github command refreshes data on demand.

AI Assistant

The ask command streams AI-generated answers grounded in portfolio content — projects, skills, and background — for accurate, context-aware responses.

Keyboard Shortcuts

TabAutocomplete command or path

↑Previous command in history

↓Next command in history

EnterExecute current command

Ctrl+LClear terminal buffer

Ctrl+CCancel current input