Docs

Repository map

Where everything lives and how to extend it without guesswork.

Know the terrain

The repo is split into content, UI, data, and automation. This map shows what each folder owns and where new work should land so changes stay predictable.

Content UI Data Automation

Top-level layout

Path	Purpose	Notes
`pages/`	Routes and API handlers	Next.js pages router + serverless API routes.
`components/`	Reusable UI surfaces	Cards, headers, telemetry views, layout shells.
`lib/`	Core logic + helpers	Markdown pipeline, caching, telemetry stores.
`data/`	Typed content lists	Navigation, tools, projects, hobbies.
`docs/`	Documentation source	Rendered at `/docs`.
`posts/`	Blog content	Markdown + frontmatter for posts.
`scripts/`	Automation helpers	Metrics refresh, syndication, adapters.
`schemas/`	JSON schemas	Validation for syndication config and state.
`styles/`	Global styling	Shared CSS variables and utilities.
`utils/`	Build helpers	Feed generation and MDX utilities.
`public/`	Static assets	Icons, images, and generated feeds.
`tests/` + `__tests__/`	Automated checks	Playwright E2E + Jest unit/component tests.

Core runtime layers

Rendering Pages + layout

Routing lives in pages/ with shared layout in components/layout.tsx.

Content Markdown pipeline

Parsing and rendering lives in lib/markdown* and lib/docs.ts.

Telemetry API + cache

Server cache lives in lib/cacheStore.ts and telemetry APIs under pages/api.

State Metrics store

Metrics history uses lib/metricsStore.ts with file or DB adapters.

Configuration + schemas

package.json holds scripts, dependencies, and automation entry points.
next.config.js configures build-time behavior and runtime settings.
vercel.json declares Vercel cron schedules.
.releaserc.json defines semantic-release rules.
.syndication.config.json configures publishing filters and platform settings.
schemas/ stores JSON schemas for syndication config/state.

Generated and stateful files

State and generated artifacts

data/githubMetricsHistory.json stores historical GitHub metrics snapshots.
data/nuget-packages.json stores auto-detected NuGet package mappings.
data/projects.generated.ts stores generated repo entries from GitHub.
.syndication-state.json tracks external publication URLs.
public/rss.xml, public/atom.xml, public/rss.json are generated feeds.

Where to add new work

Add a new page

Create a file in pages/ and reuse layout + section hooks.
Add content

Drop markdown into posts/ or docs/.
Add data

Extend data/ lists (including nugetPackages in data/projects.ts) and re-render UI cards.
Add an API

Create pages/api handlers and cache with lib/cacheStore.ts.
Add automation

Create a script in scripts/ and wire it in GitHub Actions.

System map Architecture

See how layers connect at runtime.

Content Content pipeline

Follow how markdown becomes pages.

Signals Telemetry + APIs

Endpoints, caching, and refresh logic.

Ops Automation

CI/CD workflows and scheduled jobs.