Skip to main content

Example Dashboard

This dashboard tracks the completion status of all interactive examples in the documentation.

Quick Stats​

Run npm run check-health locally to see current statistics:

npm run check-health

Coverage Report​

View the automatically generated coverage report:

npm run coverage-report

Or save it to a file:

npm run coverage-report -- --output COVERAGE.md

What Gets Checked​

Each example is checked for these required files:

  1. Stage File (*-full.stages.ts) - Pipeline stage definitions
  2. Explorer Page (explorer.mdx) - Interactive DataPipelineExplorer
  3. Index Page (index.mdx) - Introduction and overview
  4. Setup Guide (setup.mdx) - Environment setup instructions

Completion Levels​

  • Complete (100%): All 4 files present
  • Partial (50-99%): 2-3 files present
  • Minimal (below 50%): Only 1 file present

Categories​

Examples are organized into 4 categories:

Data Routing​

Circuit breakers, content routing, fan-out patterns, priority queues

Data Security​

PII removal, encryption patterns, schema enforcement, data sanitization

Data Transformation​

Time windows, deduplication, format conversion, data enrichment

Log Processing​

Log filtering, parsing, enrichment, production pipelines

Automated Monitoring​

The Example Health workflow runs:

  • On every PR - Posts health status comment
  • On push to main - Updates coverage report
  • Daily at 9am UTC - Tracks progress over time
  • On demand - Manual workflow dispatch

Workflow Outputs​

  1. PR Comments - Health status with progress bar
  2. Coverage Report - Markdown report as artifact (30-day retention)
  3. Auto-commit - Updates docs/internal/COVERAGE.md on main branch

Contributing Examples​

To create a new interactive example:

  1. Generate boilerplate:

    npm run create-explorer -- \
      --name "your-example" \
      --category "data-routing" \
      --stages 4 \
      --title "Your Example Title"

  2. Implement stage definitions in the generated *-full.stages.ts file

  3. Customize the explorer page with descriptions and learning outcomes

  4. Create supporting pages:

    • index.mdx - Introduction
    • setup.mdx - Setup guide
    • Tutorial steps and complete solution

  5. Validate your work:

    npm run validate-stages  # Check stage file format
    npm run check-health     # Check file completeness
    npm run build            # Verify build succeeds

See CONTRIBUTING.md for detailed guidelines.

Health Check Details​

Local Health Check​

# Check all examples
npm run check-health

# Check specific category
npm run check-health -- --category data-routing

# Get JSON output for automation
npm run check-health -- --format json

Exit Codes​

  • 0 - All examples are 100% complete
  • 1 - One or more examples are incomplete

This makes the health check suitable for CI/CD pipelines.

Coverage Report Features​

The coverage report includes:

  • Overall statistics and progress bar
  • Category-by-category breakdown with tables
  • Detailed list of missing files
  • Prioritized next steps (high priority vs needs significant work)

Example Coverage Table​

ExampleStage FileExplorerIndexSetupCompletion
circuit-breakers✅✅✅✅✅ 100%
remove-pii✅✅⚠️❌⚠️ 50%

Validation Scripts​

Stage Validation​

Checks that stage files follow the correct format:

npm run validate-stages

Validates:

  • Stage type imports
  • Proper Stage[] exports
  • Sequential stage IDs
  • All required properties
  • New format (not legacy)
  • Valid JsonLine objects

Type Checking​

Ensures TypeScript compilation succeeds:

npm run typecheck
  • CONTRIBUTING.md - Complete contributor guide
  • scripts/README.md - CLI tool documentation
  • Stage Type Reference - TypeScript types

Questions?​

  • How do I create a new example? Use npm run create-explorer - see CONTRIBUTING.md
  • How do I fix incomplete examples? Run npm run check-health to see what's missing
  • How do I validate my changes? Run npm run validate-stages && npm run check-health && npm run build
  • Where are the coverage reports? Check workflow artifacts or docs/internal/COVERAGE.md on main branch

This dashboard helps maintainers and contributors track example completion and ensure documentation quality.