Skip to content

Developer Guide

System Overview

This is a static website hosted on AWS—there is no server-side rendering or backend application. We use the StaticWebsite CDK construct to deliver the site via CloudFront, which also handles Okta authentication, ensuring users must authenticate before accessing the documentation.

Important: All infrastructure is deployed to the us-east-1 region (required by the StaticWebsite construct for CloudFront edge lambdas).

Architecture Overview

How Content Gets Updated

Content updates flow through an automated pipeline triggered by GitHub events:

  1. GitHub Push Event: A developer commits changes to a repository's /docs folder
  2. GitHub App Webhook: GitHub sends a webhook notification to our API Gateway endpoint
  3. Webhook Lambda: Validates the webhook signature and inspects the event to determine if /docs files were modified
  4. Rebuilder Lambda: If relevant changes are detected, triggers a rebuild process that:
    • Runs the aggregator to pull updated docs from all repositories
    • Builds the MkDocs static site
    • Uploads the generated site to S3
  5. CloudFront Distribution: Serves the updated content to users (cache may need invalidation for immediate visibility)

Available Scripts

The following npm scripts are available to help with development, deployment, and operations:

Build & Development

# Build all TypeScript packages (aggregator, webhook-handler, cdk)
pnpm build

# Install Python dependencies in virtual environment
pnpm install:python

# Build the MkDocs static site locally
pnpm mkdocs:build

Content Aggregation

# Run the aggregator to pull /docs from all repositories
pnpm aggregate

# Generate only the search index (without full aggregation)
pnpm generate-index

Deployment

# Deploy the complete infrastructure stack to AWS
pnpm deploy:infra

This builds all packages and deploys the CDK stack. See Deployment for details.

Operations

# Trigger a manual rebuild of all documentation
pnpm rebuild-docs

# View CloudWatch logs for the rebuilder Lambda
pnpm logs

# Follow logs in real-time (with AWS CLI options)
pnpm logs -- --follow
pnpm logs -- --follow --since 10m
pnpm logs -- --filter-pattern "ERROR"

The logs and rebuild-docs scripts automatically resolve the correct Lambda function name from CloudFormation outputs, so you don't need to look it up manually. Any additional flags after -- are passed directly to the underlying AWS CLI command.

See Monitoring for more operational commands.

Last updated: March 31, 2026 at 11:02
By: Axel Tetzlaff