Future Automation & CI/CD Plan

This document outlines the roadmap for automating our API documentation workflow using GitHub Actions and other automation tools.

🎯 Current State vs Future Vision

Current Manual Workflow

# Developer runs manually when API changes
cd daggh
npm run docs:full

Future Automated Workflow

graph TD
    A[Developer pushes to daggh/main] --> B[GitHub Action Triggered]
    B --> C[Generate OpenAPI Spec]
    C --> D[Copy to docs repo]
    D --> E[Generate API Docs]
    E --> F[Auto-commit to docs repo]
    F --> G[Docs site auto-deploys]
    G --> H[✅ Live API docs updated]

🚀 Phase 1: GitHub Actions Setup

Step 1: API Change Detection

.github/workflows/sync-api-docs.yml (in DAGGH repo):

name: Sync API Documentation

on:
  push:
    branches: [main]
    paths:
      - "src/app/api/**/*.ts"
      - "openapi/**"
  pull_request:
    branches: [main]
    paths:
      - "src/app/api/**/*.ts"

jobs:
  sync-docs:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'

    steps:
      - name: Checkout DAGGH repo
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "21"
          cache: "npm"

      - name: Install dependencies
        run: npm ci

      - name: Generate OpenAPI spec
        run: npm run generate:openapi

      - name: Checkout docs repo
        uses: actions/checkout@v4
        with:
          repository: your-org/docs
          path: docs-repo
          token: ${{ secrets.DOCS_REPO_TOKEN }}

      - name: Copy OpenAPI spec to docs
        run: |
          mkdir -p docs-repo/my-docs/static/openapi
          cp openapi/daggh-api.yaml docs-repo/my-docs/static/openapi/

      - name: Setup Node.js for docs
        working-directory: docs-repo/my-docs
        run: |
          npm ci

      - name: Generate API documentation
        working-directory: docs-repo/my-docs
        run: |
          npm run clean-api-docs
          npm run gen-api-docs

      - name: Commit and push to docs repo
        working-directory: docs-repo
        run: |
          git config user.name "API Docs Bot"
          git config user.email "bot@daggh.app"
          git add .
          if git diff --staged --quiet; then
            echo "No changes to commit"
          else
            git commit -m "🤖 Auto-update API docs from DAGGH@${{ github.sha }}"
            git push
          fi

Step 2: Deployment Automation

.github/workflows/deploy-docs.yml (in docs repo):

name: Deploy Documentation

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "21"
          cache: "pnpm"

      - name: Install dependencies
        working-directory: my-docs
        run: pnpm install

      - name: Build documentation
        working-directory: my-docs
        run: pnpm build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: my-docs/build

🔧 Phase 2: Enhanced Automation

Smart Change Detection

# Advanced change detection
- name: Check for API changes
  id: changes
  uses: dorny/paths-filter@v2
  with:
    filters: |
      api:
        - 'src/app/api/**/*.ts'
      schema:
        - 'openapi/**'

- name: Skip if no API changes
  if: steps.changes.outputs.api == 'false' && steps.changes.outputs.schema == 'false'
  run: echo "No API changes detected, skipping docs update"

Validation and Testing

- name: Validate OpenAPI spec
  run: |
    npx swagger-jsdoc --definition openapi/generate-schema.js --apis './src/app/api/**/*.ts' | \
    npx swagger-parser validate /dev/stdin

- name: Test generated docs build
  working-directory: docs-repo/my-docs
  run: pnpm build

- name: Link checker
  working-directory: docs-repo/my-docs
  run: |
    pnpm serve &
    sleep 10
    npx broken-link-checker http://localhost:3000 --recursive

Notification System

- name: Notify team on Slack
  if: failure()
  uses: 8398a7/action-slack@v3
  with:
    status: failure
    text: "❌ API docs sync failed for commit ${{ github.sha }}"
  env:
    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}

- name: Success notification
  if: success()
  uses: 8398a7/action-slack@v3
  with:
    status: success
    text: "✅ API docs updated successfully!"

📊 Phase 3: Advanced Features

Multi-Environment Support

strategy:
  matrix:
    environment: [staging, production]

steps:
  - name: Set environment
    run: |
      if [ "${{ matrix.environment }}" == "staging" ]; then
        echo "API_BASE_URL=https://staging.daggh.mikega.xyz" >> $GITHUB_ENV
      else
        echo "API_BASE_URL=https://daggh.mikega.xyz" >> $GITHUB_ENV
      fi

Version Management

- name: Generate versioned docs
  if: startsWith(github.ref, 'refs/tags/v')
  working-directory: docs-repo/my-docs
  run: |
    VERSION=${GITHUB_REF#refs/tags/}
    npm run gen-api-docs:version daggh:$VERSION

Performance Monitoring

- name: Lighthouse CI
  uses: treosh/lighthouse-ci-action@v9
  with:
    configPath: "./lighthouserc.json"
    uploadArtifacts: true

🎯 Phase 4: Developer Experience

Local Development Automation

scripts/watch-and-sync.js (in DAGGH repo):

import chokidar from "chokidar"
import { execSync } from "child_process"

console.log("👀 Watching API files for changes...")

chokidar.watch("src/app/api/**/*.ts").on("change", async (path) => {
  console.log(`🔄 API file changed: ${path}`)
  console.log("📝 Regenerating OpenAPI spec...")

  try {
    execSync("npm run generate:openapi", { stdio: "inherit" })
    execSync("npm run copy:docs", { stdio: "inherit" })

    // Auto-regenerate docs if docs repo is available
    try {
      execSync("cd ../../docs/my-docs && npm run refresh-api-docs", { stdio: "inherit" })
      console.log("✅ API docs updated successfully!")
    } catch (docsError) {
      console.log("⚠️  Docs repo not available, manual sync needed")
    }
  } catch (error) {
    console.error("❌ Error updating docs:", error.message)
  }
})

Pre-commit Hooks

.husky/pre-commit:

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

# Check if API files changed
if git diff --cached --name-only | grep -E "src/app/api/.*\.ts$"; then
  echo "🔍 API files changed, validating OpenAPI spec..."
  npm run generate:openapi

  # Add generated spec to commit
  git add openapi/daggh-api.yaml
fi

📋 Implementation Checklist

Phase 1: Basic Automation ✅

• Manual workflow documented
• Copy script created
• Package scripts configured
• GitHub Actions setup
• Repository secrets configured
• Initial deployment tested

Phase 2: Enhanced Features

• Change detection implemented
• Validation pipeline added
• Notification system configured
• Error handling improved

Phase 3: Advanced Features

• Multi-environment support
• Version management
• Performance monitoring
• Analytics integration

Phase 4: Developer Experience

• Watch mode for local development
• Pre-commit hooks
• IDE integration
• Documentation templates

🔐 Required Secrets

# GitHub repository secrets needed:
DOCS_REPO_TOKEN=github_pat_xxxxx  # Personal access token with repo access
SLACK_WEBHOOK=https://hooks.slack.com/xxxxx  # For notifications
VERCEL_TOKEN=xxxxx  # If using Vercel for deployment

📈 Success Metrics

Automation Goals

• Zero manual intervention for standard API changes
• Under 5 minute update time from code push to live docs
• 100% uptime for documentation site
• Automatic rollback on deployment failures

Quality Goals

• Zero broken links in documentation
• Valid OpenAPI spec on every update
• Consistent formatting across all endpoints
• Mobile responsive performance scores >90

🎯 Timeline

• Week 1: Phase 1 implementation and testing
• Week 2: Phase 2 enhanced features
• Week 3: Phase 3 advanced automation
• Week 4: Phase 4 developer experience improvements

This automation roadmap will transform our API documentation from a manual process to a fully automated, professional, and scalable system that grows with our platform.