Docs

Architecture

How pages, components, and content sources fit together.

System overview

The site is a layered system: routing and layout at the top, content and data in the middle, and telemetry APIs at the edge. This page shows how those layers stay aligned.

Pages router Static shells Shared hooks Telemetry edges

Routing map

Route family	Source	Purpose
/	pages/index.tsx	Live overview, hero, and status surfaces.
/projects	pages/projects.tsx	Project cards with expandable detail panels.
/projects#pipeline-metrics	pages/projects.tsx	Repo activity and pipeline telemetry.
/docs	docs/*.md	Markdown-driven documentation.

Page structure

Core layout

components/layout.tsx provides the global header, navigation, and page shell.
Theme switching is handled by a dedicated toggle component.
Reveal, grid tracking, and glow hotspots are shared hooks in lib/hooks.

Telemetry and data

Telemetry APIs live under pages/api for build and repo status.
lib/cacheStore.ts centralizes caching, inflight dedupe, and rate limits.
Project detail panels fetch on demand and hydrate into expanded cards.
data/githubMetricsHistory.json stores historical commit and LOC snapshots.
lib/metricsStore.ts can swap the JSON file for a database adapter.

Request journey

01. Route match

Next.js serves the correct page and shared layout shell.
02. Content hydrate

Static data and markdown output render into the page.
03. Telemetry sync

Client hooks request cached API data and update surfaces.

Pages + Layout

Data + Markdown

Hooks + UI

Telemetry APIs

External APIs

Content inputs

posts/ stores markdown-based blog posts.
docs/ stores markdown documentation that is published to the site.
data/ holds structured content for projects, tools, navigation, and hobbies. See Repository map for the full directory guide.

Consistency conventions

Prefer declarative, data-driven rendering from data/ and lib/ helpers.
Keep side effects in shared hooks instead of in-page ad hoc effects.
Normalize cross-cutting logic (tag matching, key handling, scroll lock) into utilities.
Treat markdown pipelines and search index builders as pure functions with explicit inputs.

Build output

public/ serves static assets, RSS feeds, and the generated sitemap endpoint.
Next.js handles static generation for content pages and server-side rendering only where needed.

Projects Interactive cards

See how data-driven rendering looks in practice.

Telemetry Pipeline status

Live signals from GitHub and Vercel.

Stack Core technologies

Frameworks and services that shape the architecture.

Content Pipeline flow

Follow how markdown becomes pages.