Introduction
Relevant source files
The following files were used as context for generating this wiki page:
The lukemcdonald.com project is a personal website built using the Astro web framework. It serves as a technical playground for exploring modern web technologies, including static site generation, accessible UI components, and automated testing workflows. The system emphasizes performance, type safety, and clean architecture through the use of TypeScript, TailwindCSS, and a strictly organized directory structure.
The project integrates various external services such as Netlify for hosting and daily rebuilds, Cloudflare for web analytics, and YouVersion for dynamic content like the "verse of the day." Development is governed by specific agent instructions and automated validation pipelines to ensure code quality and consistency across its domain-driven modules.
Sources: README.md:1-12, AGENTS.md:1-10
Architecture and Technology Stack
The project utilizes a modern frontend stack centered on Astro for static site generation. It avoids heavy UI runtimes like React or Headless UI, preferring native HTML elements supplemented by small vanilla TypeScript modules.
Core Technologies
| Technology | Purpose |
|---|---|
| Astro | Core framework for static site generation and routing. |
| TypeScript | Provides type safety across the entire codebase. |
| TailwindCSS | Utility-first CSS framework for styling. |
| pnpm | Package manager for dependency and script management. |
| Netlify | Hosting platform with support for daily rebuild hooks. |
| Playwright | Framework for end-to-end testing and accessibility audits. |
Sources: README.md:10-18, AGENTS.md:9-10, AGENTS.md:90-94, package.json:71-92
Directory Structure
The project follows a modular structure where code is organized by technical role and domain functionality:
src/pages/: Contains Astro routes and page components.src/layouts/: Defines reusable page shells.src/features/: Contains domain-specific modules (e.g., navigation, pages, resume).src/content/: Stores Markdown and YAML content collections.src/utils/: Houses generic utility functions.e2e/: Contains Playwright test specs and fixtures.
Sources: AGENTS.md:46-55, e2e/README.md:11-30
System Data Flow
The site generates static pages from local content collections while incorporating dynamic metadata and external data during the build process.
The diagram shows the build-time data flow where static content and configuration are processed by Astro to generate the final distribution files, with daily triggers for dynamic content updates.
Sources: README.md:10-18, AGENTS.md:83-88, src/features/verse/verse.utils.test.ts:70-90
Feature Organization
Each domain within the src/features/ directory follows a standardized internal structure to maintain consistency:
- Components: Feature-specific UI elements.
- Schemas: Zod schemas for content validation.
- Server Logic: Collection loaders and data queries.
- Types & Utils: Pure helper functions and TypeScript definitions.
- Tests: Colocated unit tests for business logic.
Sources: AGENTS.md:59-67
Development and Quality Assurance
The project enforces a rigorous validation pipeline. Developers must run pnpm validate, which executes linting, formatting checks, type checking, and unit tests.
Testing Strategy
The testing architecture is split into two distinct layers:
- Unit Tests: Located in
src/**/*.test.ts, these use the nativenode:testrunner. They focus on pure functions, utility logic, and SEO metadata generation. - End-to-End (E2E) Tests: Located in
e2e/, these use Playwright to verify browser behavior and accessibility (WCAG) compliance. The E2E suite utilizes a Page Object Model (POM) and custom fixtures.
Sources: AGENTS.md:96-112, e2e/README.md:3-9, package.json:28-31
The sequence diagram illustrates the lifecycle of a code change, from local development to the automated CI pipeline.
Sources: AGENTS.md:12-20, e2e/README.md:124-132
Content and SEO
Content is decoupled from the UI, residing in the src/content/ directory. Pages are written in Markdown, while structured data like resume details use YAML. The system automatically generates SEO metadata, including OpenGraph tags and JSON-LD schemas for Search Engine Optimization.
- JSON-LD: Builds a graph including
WebSite,WebPage, andPersonnodes. - Social Tags: Generates
og:title,og:image, andtwitter:cardmetadata based on page content.
Sources: src/utils/seo/schema.ts:50-58, src/utils/seo/social.test.ts:133-155, src/features/pages/pages.utils.test.ts:47-65
Summary
The lukemcdonald.com codebase is a highly structured Astro project designed for maintainability and technical excellence. It leverages a strictly defined architecture, automated quality gates, and a "native-first" philosophy to deliver a performant and accessible personal website. The integration of automated daily rebuilds and robust SEO utilities ensures the site remains current and discoverable.