Architecture Overview

Overview

my-buddy is built with Astro 5, TypeScript (strict), Tailwind CSS v4, and Bun. It’s a static site generator that renders markdown content into a keyboard-navigable dashboard with full-text search.

Tech Stack

Technology	Purpose
Astro 5	Static site generator with island architecture
TypeScript	Strict mode, Zod schema validation
Tailwind CSS v4	Utility-first styling with @tailwindcss/vite
Bun	Runtime and package manager
Biome	Linter and formatter
Pagefind	Full-text search (build-time indexing)
Zod	Content schema validation

Project Structure

src/
├── content/              # 8 markdown collections
├── content.config.ts     # Zod schemas for all collections
├── components/           # Atomic design components
│   ├── atoms/            # Badge, FilterSelect, KeyToast, SearchInput, SiblingNav
│   ├── molecules/        # Backlinks, Breadcrumb, FilterBar, RelatedContent
│   ├── organisms/        # Sidebar, HelpModal
│   └── templates/        # BaseTemplate, PageTemplate
├── pages/                # Dashboard + 16 collection pages
├── plugins/wiki-links/   # Remark plugin + index builder
├── scripts/              # Keyboard nav + client-side filtering
├── styles/global.css     # Tailwind v4 + CSS tokens
├── lib/config.ts         # buddy.config.ts schema
└── utils/display.ts      # Display name helpers

Key Systems

Content Collections

All data is stored as markdown files with YAML frontmatter, validated by Zod schemas in src/content.config.ts. See Collections Overview for details.

Wiki-Link Plugin

A custom remark plugin transforms [[slug]] syntax into HTML links with automatic backlink tracking. See Wiki Linking for details.

Keyboard Navigation

Vim-style shortcuts implemented in src/scripts/keyboard.ts. See Keyboard Navigation for the full shortcut table.

Search

Pagefind provides full-text search across all collections, indexed at build time. See Search for details.

Build Pipeline

bun build

This runs three steps:

1. Wiki-link index — Generates wiki-link-index.json and backlink-index.json
2. Astro build — Renders all pages to static HTML
3. Pagefind — Indexes the built HTML for search