ilkayurlu

Architecture Documentation

Comprehensive technical documentation of the GitHub Workflow Blueprint system architecture, design decisions, and implementation details

Table of Contents

  1. System Architecture Overview
  2. Technology Stack
  3. Design Principles
  4. Component Interactions
  5. Data Flow
  6. Design Decisions
  7. Security Model
  8. Scalability Considerations
  9. Performance Optimization
  10. Technical Constraints
  11. Future Enhancements

System Architecture Overview

High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     USER INTERFACE LAYER                         │
│                                                                   │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │ Slash Commands  │  │ Setup Wizard    │  │ Documentation   │ │
│  │ (8 commands)    │  │ (Interactive)   │  │ (8 guides)      │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                    AUTOMATION LAYER                              │
│                                                                   │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │ Agents          │  │ Composite       │  │ Validators      │ │
│  │ (4 specialized) │  │ Actions (5)     │  │ & Helpers       │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                      WORKFLOW LAYER                              │
│                                                                   │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐           │
│  │Bootstrap│  │PR Checks│  │Plan→    │  │Status   │           │
│  │         │  │         │  │Issues   │  │Sync     │ ...       │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘           │
│                   (8 Core Workflows)                             │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                    INTEGRATION LAYER                             │
│                                                                   │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐           │
│  │ GitHub  │  │ GitHub  │  │ Claude  │  │ External│           │
│  │ REST API│  │ GraphQL │  │ Code    │  │ Tools   │           │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘           │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                     FOUNDATION LAYER                             │
│                                                                   │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐           │
│  │   Git   │  │ GitHub  │  │ Project │  │ Issue   │           │
│  │         │  │ Actions │  │ Board   │  │ Tracking│           │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘           │
└─────────────────────────────────────────────────────────────────┘

Layer Responsibilities

User Interface Layer

Automation Layer

Workflow Layer

Integration Layer

Foundation Layer

Technology Stack

Core Technologies

Component Technology Version Rationale
CI/CD GitHub Actions Latest Native integration, free for public repos
Package Manager pnpm 9.x Fast, efficient, workspace support
Runtime Node.js 20 LTS Stable, long-term support, modern features
Project Management GitHub Projects v2 Latest GraphQL API, flexible, native GitHub
AI Automation Claude Code Action v1 GA Official Anthropic integration, stable API
Version Control Git 2.40+ Industry standard, ubiquitous

Supporting Technologies

Purpose Technology Usage
JSON Validation jq Parse and validate plan JSON
Path Filtering dorny/paths-filter@v3 Smart workflow triggers
Semantic PR amannn/action-semantic-pull-request@v5 Conventional commit validation
Script Execution actions/github-script@v7 JavaScript in workflows
Caching actions/cache@v4 Speed up builds

Why These Choices?

GitHub Actions over Jenkins/CircleCI:

pnpm over npm/yarn:

Projects v2 over Classic Projects:

Claude Code Action v1 GA over Beta:

Design Principles

1. Simplicity First

Principle: Prefer simple, obvious solutions over clever ones.

Examples:

Rationale: Lower cognitive load for users, easier debugging, fewer edge cases.

2. Safety by Default

Principle: Fail safe, not fail fast. Prevent destructive operations.

Examples:

Rationale: Protects users from mistakes, prevents cascading failures.

3. Progressive Disclosure

Principle: Show simple options first, advanced options on demand.

Examples:

Rationale: Lowers barrier to entry, doesn’t overwhelm beginners.

4. DRY (Don’t Repeat Yourself)

Principle: Extract common patterns into reusable components.

Examples:

Rationale: Easier maintenance, consistent behavior, fewer bugs.

5. Idempotency

Principle: Operations should be safe to retry.

Examples:

Rationale: Transient failures shouldn’t cause permanent issues.

6. Fail-Fast Validation

Principle: Validate inputs early, fail with clear messages.

Examples:

Rationale: Fast feedback, clear error messages, saves compute time.

7. Observable Operations

Principle: Every operation should be visible and debuggable.

Examples:

Rationale: Easier debugging, better user experience, builds trust.

Component Interactions

Workflow ↔ Composite Actions

┌──────────────────────┐
│   pr-into-dev.yml    │
│                      │
│  1. Fork check   ────┼────→ .github/actions/fork-safety
│  2. Rate limit   ────┼────→ .github/actions/rate-limit-check
│  3. Quality     ────┼────→ .github/workflows/reusable-pr-checks.yml
│                      │         │
└──────────────────────┘         │
                                 ├────→ .github/actions/setup-node-pnpm
                                 └────→ .github/actions/quality-gates

Flow:

  1. PR event triggers pr-into-dev.yml
  2. Workflow calls composite actions for reusable logic
  3. Composite actions perform atomic operations
  4. Results aggregate back to workflow
  5. Workflow generates summary report

Benefits:

Slash Commands ↔ Workflows

User runs: /blueprint-init
     ↓
Claude Code executes command
     ↓
Command prompts user (interactive)
     ↓
Command calls: gh workflow run bootstrap.yml
     ↓
Workflow executes in GitHub Actions
     ↓
Results displayed to user

Integration Points:

  1. Command → Workflow: Commands trigger workflows via gh workflow run
  2. Workflow → Status: Workflows post results to PR/issue comments
  3. Command → Validation: Commands validate before triggering workflows

Design Decision: Commands are thin wrappers around workflows, not duplicating logic.

Agents ↔ GitHub API

User runs: /plan-to-issues plan.json
     ↓
plan-converter agent (Claude Code)
     ↓
Agent validates plan structure
     ↓
Agent calls: gh workflow run claude-plan-to-issues.yml
     ↓
Workflow processes via GitHub REST API:
  - Create milestone (if specified)
  - Create issues (max 10)
  - Apply labels
  - Link dependencies
     ↓
Workflow syncs to Project Board via GraphQL
     ↓
Agent displays summary to user

API Usage:

Rate Limit Strategy:

Project Board ↔ Issues

Issue Created (#123)
     ↓
Labels: claude-code + status:ready
     ↓
create-branch-on-issue.yml triggers
     ↓
GraphQL Mutation:
  - Add issue to project
  - Set Status: "Ready"
     ↓
Developer works on branch
     ↓
PR Created → dev
     ↓
pr-status-sync.yml updates:
  - Issue Status: "In Review"
  - Project Board: "In Review"
     ↓
PR Merged
     ↓
pr-status-sync.yml updates:
  - Issue Status: "To Deploy"
  - Project Board: "To Deploy"
     ↓
Release to main
     ↓
release-status-sync.yml closes:
  - Issue closed
  - Project Board: "Done"

Bidirectional Sync:

Status Mapping:

Issue Labels          Project Board Status
─────────────────     ────────────────────
status:ready      →   Ready
status:in-progress →  In Progress
status:in-review   →  In Review
status:to-deploy   →  To Deploy
[closed]           →  Done

Data Flow

Complete Lifecycle: Plan → Production

1. PLANNING PHASE
   ┌─────────────────────┐
   │ Claude Code Plan    │
   │ (JSON, max 10 tasks)│
   └──────────┬──────────┘
              ↓
   ┌─────────────────────┐
   │ /plan-to-issues     │
   │ (command)           │
   └──────────┬──────────┘
              ↓
   ┌─────────────────────┐
   │ claude-plan-to-     │
   │ issues.yml          │
   │ (workflow)          │
   └──────────┬──────────┘
              ↓
   ┌─────────────────────┐
   │ GitHub Issues       │
   │ (10 issues created) │
   │ Labels: claude-code │
   │         status:ready│
   └──────────┬──────────┘
              ↓
   ┌─────────────────────┐
   │ Project Board       │
   │ Status: Ready       │
   └─────────────────────┘

2. DEVELOPMENT PHASE
   ┌─────────────────────┐
   │ Issue #123 labeled  │
   │ claude-code +       │
   │ status:ready        │
   └──────────┬──────────┘
              ↓
   ┌─────────────────────┐
   │ create-branch-on-   │
   │ issue.yml           │
   └──────────┬──────────┘
              ↓
   ┌─────────────────────┐
   │ Branch created:     │
   │ feature/issue-123-  │
   │ description         │
   └──────────┬──────────┘
              ↓
   ┌─────────────────────┐
   │ Developer commits   │
   │ to feature branch   │
   └──────────┬──────────┘
              ↓
   ┌─────────────────────┐
   │ /commit-smart       │
   │ (quality checks)    │
   └──────────┬──────────┘
              ↓
   ┌─────────────────────┐
   │ /create-pr          │
   │ PR → dev            │
   └─────────────────────┘

3. REVIEW PHASE
   ┌─────────────────────┐
   │ PR opened to dev    │
   └──────────┬──────────┘
              ↓
   ┌─────────────────────┐
   │ pr-into-dev.yml     │
   │ - Validate branch   │
   │ - Validate title    │
   │ - Check linked issue│
   │ - Run quality gates │
   └──────────┬──────────┘
              ↓
   ┌─────────────────────┐
   │ reusable-pr-checks  │
   │ - Lint              │
   │ - Typecheck         │
   │ - Unit tests        │
   └──────────┬──────────┘
              ↓
   ┌─────────────────────┐
   │ pr-status-sync.yml  │
   │ Issue: In Review    │
   │ Board: In Review    │
   └──────────┬──────────┘
              ↓
   ┌─────────────────────┐
   │ /review-pr          │
   │ (optional)          │
   └──────────┬──────────┘
              ↓
   ┌─────────────────────┐
   │ PR approved & merged│
   └─────────────────────┘

4. DEPLOYMENT PHASE
   ┌─────────────────────┐
   │ PR merged to dev    │
   └──────────┬──────────┘
              ↓
   ┌─────────────────────┐
   │ pr-status-sync.yml  │
   │ Issue: To Deploy    │
   │ Board: To Deploy    │
   │ Branch deleted      │
   └──────────┬──────────┘
              ↓
   ┌─────────────────────┐
   │ /release            │
   │ PR: dev → main      │
   └──────────┬──────────┘
              ↓
   ┌─────────────────────┐
   │ dev-to-main.yml     │
   │ - Build prod        │
   │ - Smoke tests       │
   │ - Security scan     │
   └──────────┬──────────┘
              ↓
   ┌─────────────────────┐
   │ PR merged to main   │
   └──────────┬──────────┘
              ↓
   ┌─────────────────────┐
   │ release-status-     │
   │ sync.yml            │
   │ - Close issues      │
   │ - Board: Done       │
   │ - Create release    │
   └─────────────────────┘

5. PRODUCTION
   ┌─────────────────────┐
   │ GitHub Release      │
   │ v1.2.3              │
   │ - Changelog         │
   │ - Artifacts         │
   └─────────────────────┘

Status Propagation Flow

Issue Label Change
     ↓
GitHub Webhook
     ↓
Workflow Triggered (pr-status-sync.yml)
     ↓
┌─────────────────────────────────────┐
│ Determine New Status                │
│ - PR opened → "In Review"           │
│ - PR draft → "In Progress"          │
│ - PR merged → "To Deploy"           │
│ - PR closed (not merged) → reset   │
└─────────────┬───────────────────────┘
              ↓
┌─────────────────────────────────────┐
│ Update Issue Labels                 │
│ - Remove old status label           │
│ - Add new status label              │
└─────────────┬───────────────────────┘
              ↓
┌─────────────────────────────────────┐
│ Update Project Board (GraphQL)      │
│ - Query project ID                  │
│ - Query status field ID             │
│ - Mutate status value               │
└─────────────┬───────────────────────┘
              ↓
┌─────────────────────────────────────┐
│ Post Comment (if applicable)        │
│ "Status updated to: In Review"      │
└─────────────────────────────────────┘

Debouncing: 10-second delay between status updates prevents infinite loops.

Design Decisions

1. Why Max 10 Tasks per Plan?

Decision: Hard limit of 10 tasks per Claude Code plan.

Rationale:

Technical:

User Experience:

Performance:

Alternative Considered: No limit

Customization: Users can change limit in workflow (see CUSTOMIZATION.md)

2. Why GraphQL for Projects v2?

Decision: Use GitHub GraphQL API for project board operations.

Rationale:

Projects v2 Requirement:

GraphQL Advantages:

GraphQL Challenges:

Mixed Approach:

Example GraphQL Query:

query($owner: String!, $repo: String!, $number: Int!) {
  repository(owner: $owner, name: $repo) {
    issue(number: $number) {
      id
      projectItems(first: 10) {
        nodes {
          project {
            id
            title
          }
        }
      }
    }
  }
}

3. Why Three Branching Strategies?

Decision: Support Simple, Standard, and Complex branching strategies.

Rationale:

Flexibility:

User Personas:

Solo Developer (Simple):

Small Team (Standard):

Enterprise (Complex):

Implementation Cost:

Alternative Considered: Force Standard strategy

4. Why pnpm over npm?

Decision: Default to pnpm for package management.

Rationale:

Performance:

Reliability:

Modern Features:

Adoption:

Backwards Compatibility:

Trade-offs:

Override: Users can switch to npm/yarn (see CUSTOMIZATION.md)

5. Why Node.js 20 LTS?

Decision: Default to Node.js 20 (LTS).

Rationale:

Long-Term Support:

Modern Features:

Ecosystem Compatibility:

Trade-offs:

Override: Users can specify different version (see CUSTOMIZATION.md)

uses: ./.github/actions/setup-node-pnpm
with:
  node-version: '22'  # Use Node 22 instead

6. Why Rate Limiting with Circuit Breakers?

Decision: Check API rate limits before operations, fail-fast if too low.

Rationale:

Problem: GitHub API rate limits

Without Rate Limiting:

With Circuit Breakers:

Thresholds:

Implementation:

- name: Check rate limit
  uses: ./.github/actions/rate-limit-check
  with:
    minimum-remaining: 100

Benefits:

7. Why Squash-Only Merges?

Decision: Enforce squash merges (no merge commits, no rebase).

Rationale:

Linear History:

Simplified Commits:

Review Efficiency:

Trade-offs:

Alternatives Considered:

Override: Change branch protection settings if needed

8. Why Fork Safety (Read-Only for Forks)?

Decision: Fork PRs run checks but skip write operations.

Rationale:

Security Risk:

GitHub Security Model:

Our Implementation:

Example:

- name: Check if PR is from fork
  id: fork-safety
  uses: ./.github/actions/fork-safety

- name: Update project board
  if: steps.fork-safety.outputs.is-fork != 'true'
  run: |
    # Only runs for non-fork PRs

User Experience:

Security Model

Secret Handling

Secrets Required:

  1. ANTHROPIC_API_KEY - Claude Code integration
  2. PROJECT_URL - GitHub Projects v2 board
  3. GITHUB_TOKEN - Auto-provided by GitHub Actions

Storage:

Best Practices:

# ✅ Good: Secret only in workflow
env:
  ANTHROPIC_API_KEY: $

# ❌ Bad: Secret in code
env:
  API_KEY: "sk-ant-..."  # Never hardcode!

# ✅ Good: Validate secret format
- name: Validate API key
  run: |
    if [[ ! "$" =~ ^sk-ant- ]]; then
      echo "Invalid API key format"
      exit 1
    fi

Rotation:

Permission Model (Least Privilege)

Workflow Permissions:

# Default: Read-only
permissions:
  contents: read

# Add permissions as needed
permissions:
  contents: read        # Read repository content
  pull-requests: write  # Create PR comments
  issues: write         # Create/update issues
  statuses: write       # Update commit statuses

Progressive Permissions:

Examples:

bootstrap.yml (setup):

permissions:
  contents: write   # Create labels, configure repo
  issues: write     # Create milestone

pr-into-dev.yml (validation):

permissions:
  contents: read        # Read code
  pull-requests: write  # Post comments
  issues: read          # Validate linked issues

release-status-sync.yml (deployment):

permissions:
  contents: write   # Create GitHub release
  issues: write     # Close issues
  pull-requests: read  # Read merged PRs

Fork Safety Implementation

Detection:

- name: Check if PR is from fork
  id: fork-check
  run: |
    IS_FORK=$
    echo "is-fork=$IS_FORK" >> $GITHUB_OUTPUT

Conditional Execution:

- name: Update project board
  if: steps.fork-check.outputs.is-fork != 'true'
  run: |
    # Safe to run write operations

User Communication:

- name: Log fork status
  run: |
    if [[ "$IS_FORK" == "true" ]]; then
      echo "⚠️  Fork PR detected - write operations disabled"
    fi

Rate Limiting Strategy

Circuit Breaker Pattern:

- name: Check API rate limit
  id: rate-limit
  uses: ./.github/actions/rate-limit-check
  with:
    minimum-remaining: 100

- name: Fail if rate limit too low
  if: steps.rate-limit.outputs.can-proceed != 'true'
  run: |
    echo "❌ Rate limit too low: $"
    echo "Resets at: $"
    exit 1

Exponential Backoff:

- name: Retry with backoff
  uses: nick-invision/retry@v2
  with:
    timeout_minutes: 10
    max_attempts: 3
    retry_wait_seconds: 30
    command: gh api /repos/$REPO/issues

Batching:

// Create issues in batches of 3 with delays
for (let i = 0; i < issues.length; i += 3) {
  const batch = issues.slice(i, i + 3);
  await Promise.all(batch.map(createIssue));
  await sleep(1000); // 1 second between batches
}

Idempotency Guarantees

Principle: Operations should be safe to retry without side effects.

Implementation Examples:

Label Creation (bootstrap.yml):

# Check if label exists before creating
if ! gh label list | grep -q "claude-code"; then
  gh label create "claude-code" --color "0e8a16"
else
  echo "Label already exists, skipping"
fi

Issue Creation (claude-plan-to-issues.yml):

// Check for existing issue with same title
const existing = await github.rest.issues.listForRepo({
  state: 'all'
}).then(({data}) => data.find(i => i.title === task.title));

if (existing) {
  console.log(`Issue already exists: #${existing.number}`);
  continue; // Skip creation
}

Branch Creation (create-branch-on-issue.yml):

# Check if branch exists
if git rev-parse --verify "feature/issue-$NUMBER" 2>/dev/null; then
  echo "Branch already exists"
  exit 0
fi

# Create branch
git checkout -b "feature/issue-$NUMBER"

Scalability Considerations

API Rate Limits

GitHub API Limits:

Mitigation Strategies:

1. Caching:

- name: Cache API responses
  uses: actions/cache@v4
  with:
    path: ~/.gh-cache
    key: api-cache-$

2. Conditional Requests (ETags):

# Use ETags to avoid fetching unchanged data
ETAG=$(gh api /repos/$REPO/issues --include | grep -i etag)
gh api /repos/$REPO/issues --header "If-None-Match: $ETAG"
# Returns 304 Not Modified if unchanged (doesn't count against rate limit)

3. Batching:

// GraphQL allows multiple queries in one request
query {
  issue1: repository(...) { issue(number: 1) { ... } }
  issue2: repository(...) { issue(number: 2) { ... } }
  issue3: repository(...) { issue(number: 3) { ... } }
}

4. Pagination:

// Use pagination for large result sets
const allIssues = await github.paginate(
  github.rest.issues.listForRepo,
  { owner, repo, per_page: 100 }
);

Concurrent Workflow Execution

Challenge: Multiple workflows can run simultaneously.

Concurrency Control:

# Cancel in-progress runs for same PR
concurrency:
  group: pr-checks-$
  cancel-in-progress: true

Benefits:

Grouping Strategies:

By PR:

group: pr-$

By Branch:

group: branch-$

By Workflow:

group: $-$

Caching Strategy

What to Cache:

Implementation:

pnpm Cache:

- name: Cache pnpm store
  uses: actions/cache@v4
  with:
    path: ~/.pnpm-store
    key: $-pnpm-$
    restore-keys: |
      $-pnpm-

Build Cache:

- name: Cache Next.js build
  uses: actions/cache@v4
  with:
    path: .next/cache
    key: $-nextjs-$

Cache Hit Rate:

Performance Optimization

Workflow Execution Time:

Target:

Optimizations:

1. Parallel Jobs:

jobs:
  lint:
    runs-on: ubuntu-latest
  test:
    runs-on: ubuntu-latest
  build:
    runs-on: ubuntu-latest
# All run in parallel

2. Matrix Strategy:

strategy:
  matrix:
    node-version: [18, 20, 22]
# Tests run in parallel across versions

3. Path Filtering:

- uses: dorny/paths-filter@v3
  id: changes
  with:
    filters: |
      frontend:
        - 'src/**'

- name: Frontend tests
  if: steps.changes.outputs.frontend == 'true'
  run: npm run test:frontend
# Only run frontend tests if frontend code changed

4. Fail-Fast:

strategy:
  fail-fast: true
# Stop all jobs if one fails (for validation)

Technical Constraints

GitHub Actions Limitations

Workflow Limits:

Runner Limits:

Workarounds:

Long Workflows:

Storage:

Concurrency:

GitHub Projects v2 Constraints

GraphQL Only:

Rate Limiting:

Field Types:

Workarounds:

Complex Queries:

Custom Fields:

Claude Code Action v1 GA

Capabilities:

Limitations:

Best Practices:

Future Enhancements

Planned Improvements

1. Visual Workflow Designer

2. Advanced Analytics

3. Multi-Repository Support

4. Enhanced AI Integration

5. Mobile App Integration

Potential Optimizations

1. Workflow Deduplication

2. Smart Caching

3. Advanced Concurrency

4. Cost Optimization

Experimental Features

1. Feature Flags Integration

2. Automated Dependency Updates

3. Deployment Previews

4. Code Coverage Tracking

Summary

Architecture Strengths

✅ Modular: Clear separation of concerns ✅ Scalable: Handles growth in users and workflows ✅ Secure: Multiple layers of protection ✅ Performant: Optimized for speed ✅ Maintainable: DRY principles, well-documented ✅ Flexible: Supports multiple workflows and strategies ✅ Observable: Clear logging and error messages

Key Takeaways

  1. Simplicity Over Cleverness: Easy to understand = easy to maintain
  2. Safety First: Multiple layers prevent destructive operations
  3. Progressive Disclosure: Simple defaults, advanced options available
  4. Idempotency: Safe to retry operations
  5. Observable: Clear feedback at every step
  6. Flexible: Supports solo developers to enterprises
  7. Future-Proof: Built on stable, well-supported technologies

This architecture is designed to scale from solo developers to enterprise teams while maintaining simplicity, security, and performance.

Last Updated: 2025-11-06 Version: 1.0.0