Build & Deployment

Relevant source files

• Makefile
• api/run-api-tests.sh
• apps/documentation/bun.lock
• apps/documentation/package.json
• apps/documentation/src/content/docs/specifications/backend/api-response-format.md
• apps/documentation/src/content/docs/specifications/backend/endpoints.md
• apps/documentation/src/content/docs/specifications/backend/error-handling.md
• apps/documentation/src/content/docs/specifications/frontend/routing.md
• apps/documentation/src/tailwind.css

This document covers the build and deployment process for the documentation site located in apps/documentation/. It explains how to build the static documentation site using Astro, Starlight, and the Bun runtime, including Makefile orchestration, development workflows, and static output generation.

For information about building and deploying the reference API implementation, see Build System & Workflows.

---

Build Pipeline Overview

The documentation site uses a multi-stage build pipeline that transforms Markdown content and Astro components into optimized static HTML/CSS/JS files.

Build Flow:

1. Setup installs dependencies via bun install
2. Check validates TypeScript types and Astro syntax
3. Build compiles source files into static assets
4. Output generates production-ready files in dist/
5. Preview allows local testing of built site

Sources: Makefile94-112 apps/documentation/package.json1-27

---

Makefile Build Targets

The Makefile provides convenient commands for documentation site operations. Each target is defined in Makefile94-112

Target	Command	Purpose
documentation-setup	cd apps/documentation && bun install	Install all dependencies
documentation-dev	cd apps/documentation && bun run dev	Start development server (localhost only)
documentation-dev-host	cd apps/documentation && bun run dev --host	Start development server (network accessible)
documentation-build	cd apps/documentation && bun run build	Build static site for production
documentation-preview	cd apps/documentation && bun run preview	Preview built static site locally
documentation-clean	Remove build artifacts	Delete .astro, dist, node_modules

Usage Examples

Sources: Makefile94-112

---

Bun as Package Manager & Runtime

The documentation site uses Bun instead of npm or Node.js for faster performance.

Why Bun?

• Faster installation: Bun installs dependencies significantly faster than npm
• Faster runtime: Bun executes JavaScript/TypeScript faster than Node.js
• Drop-in replacement: Compatible with npm scripts defined in package.json
• Built-in TypeScript: Native TypeScript support without transpilation

Bun Commands in Context

Makefile97 shows: cd apps/documentation && bun install

• Changes to documentation directory
• Runs bun install to install dependencies from package.json

Makefile100 shows: cd apps/documentation && bun run dev

• Executes the dev script from apps/documentation/package.json6: "dev": "astro dev"
• Starts Astro development server with hot-reloading

Sources: Makefile94-112 apps/documentation/package.json1-27

---

Build Process Steps

The production build follows a two-step validation and generation process defined in apps/documentation/package.json8

Step 1: Type Checking (astro check)

Defined in apps/documentation/package.json8: "build": "astro check && astro build"

The @astrojs/check package validates:

• TypeScript types in .astro and .ts files
• Astro component syntax and props
• Content collections schema defined in src/content/config.ts
• Import paths and module resolution

If validation fails, the build stops and error messages are displayed.

Step 2: Static Site Generation (astro build)

After successful type checking, astro build performs:

1. Content Processing

   • Parses all .md files in src/content/docs/
   • Transforms Markdown to HTML using remark/rehype
   • Applies syntax highlighting with Shiki
   • Processes frontmatter metadata

2. Component Compilation

   • Compiles .astro components to JavaScript
   • Applies Starlight theme components
   • Injects custom Tailwind CSS styles

3. Asset Optimization

   • Bundles and minifies JavaScript
   • Processes CSS with PostCSS and Tailwind
   • Optimizes images with Sharp
   • Generates CSS/JS hashes for cache busting

4. Static HTML Generation

   • Pre-renders all pages at build time
   • Generates sitemap.xml
   • Creates search index (Pagefind)
   • Outputs to dist/ directory

Sources: apps/documentation/package.json8 Makefile105-106

---

Static Site Output Structure

The astro build command generates the following directory structure in apps/documentation/dist/:

dist/
├── index.html                    # Homepage
├── specifications/
│   ├── frontend/
│   │   ├── routing/
│   │   │   └── index.html       # Each page as static HTML
│   │   └── ...
│   ├── backend/
│   │   ├── endpoints/
│   │   │   └── index.html
│   │   ├── api-response-format/
│   │   │   └── index.html
│   │   └── ...
│   └── ...
├── _astro/                       # Bundled CSS/JS with content hashes
│   ├── index.[hash].js
│   ├── styles.[hash].css
│   └── ...
├── pagefind/                     # Search index
│   ├── pagefind.js
│   ├── index/
│   └── ...
└── sitemap.xml                   # Generated sitemap

Static Output Characteristics

Property	Value
Format	Static HTML/CSS/JS
Routing	Directory-based (e.g., /specifications/backend/endpoints/)
JavaScript	Minimal client-side JS (primarily for search and navigation)
Images	Optimized with Sharp, responsive srcsets
Cache Strategy	Content-hashed filenames in _astro/
Search	Pre-built index in pagefind/

This static output can be deployed to any static hosting service (Netlify, Vercel, Cloudflare Pages, GitHub Pages, etc.) or served by any web server.

Sources: apps/documentation/package.json8 Makefile105-106

---

Development and Preview Modes

Development Mode (make documentation-dev)

Command: Makefile99-100

Features:

• Starts local development server at http://localhost:4321
• Hot Module Replacement (HMR): Changes to source files instantly reflect in browser
• No build step: Content served directly without pre-compilation
• Error overlay: Syntax errors displayed in browser
• Fast refresh: Component state preserved during updates

Network Access: Use make documentation-dev-host (Makefile102-103) to expose the server on your local network (accessible via IP address).

Preview Mode (make documentation-preview)

Command: Makefile108-109

Purpose:

• Previews the production build from dist/
• Serves static files exactly as they would appear in production
• Used to validate build output before deployment
• Runs local HTTP server (typically on http://localhost:4321)

Workflow:

Sources: Makefile99-109 apps/documentation/package.json6-9

---

Clean Operations

The documentation-clean target removes all generated files and installed dependencies.

Command: Makefile111-112

When to Clean

Scenario	Reason
Dependency issues	Corrupted node_modules, version conflicts
Build cache problems	Stale .astro cache causing incorrect builds
Disk space	Remove large node_modules directory
Fresh start	Reset to clean state before debugging

Full Reset Workflow

Sources: Makefile111-112

---

Complete Build Workflow

This diagram shows the typical workflow from setup to deployment:

Command Summary

Sources: Makefile94-112 apps/documentation/package.json1-27

---

Deployment Considerations

While this repository focuses on the build process, the static output in dist/ can be deployed to various hosting platforms:

Hosting Options

Platform	Deployment Method
Netlify	Connect GitHub repo, auto-build on push
Vercel	Connect GitHub repo, auto-deploy
Cloudflare Pages	Connect GitHub repo, configure build command
GitHub Pages	Push dist/ to gh-pages branch
AWS S3 + CloudFront	Upload dist/ to S3 bucket
Self-hosted	Copy dist/ to web server (nginx, Apache, etc.)

Build Configuration for CI/CD

For automated deployments, configure your hosting platform with:

• Build command: make documentation-build or bun run build
• Publish directory: apps/documentation/dist
• Install command: make documentation-setup or bun install

The static nature of the output ensures compatibility with virtually any hosting solution that can serve HTML files.

Sources: Makefile105-106 apps/documentation/package.json8