Phase 2: Backend Service & GitHub Integration for Component Schema PR Authoring

[GarthDB]

Component Schema PR Authoring - Phase 2

This issue tracks Phase 2+ of the Component Schema PR Authoring feature, building on the completed Phase 1 schema conversion library.

✅ Phase 1 Complete

The @adobe/component-schema-converter package has been implemented with:

• Pure functions for bidirectional conversion between plugin format and official JSON Schema
• Comprehensive validation (plugin format, official schema, JSON Schema 2020-12)
• 135 passing tests with >95% coverage
• Full documentation with API reference and examples

Package Location: packages/component-schema-converter/
Plan Document: .cursor/plans/component_schema_pr_integration_38e21d48.plan.md

🎯 Phase 2: Backend Service & PR Creation

Overview

Enable the Component Options Editor Figma plugin to create pull requests against packages/component-schemas with schema changes via a backend service.

Components Needed

1. Backend Service (Node.js/Express)

• Endpoint: POST /api/convert-and-create-pr
• Responsibilities:
  • Receive plugin format JSON from Figma plugin
  • Convert to official schema using @adobe/component-schema-converter
  • Create changeset file following repo conventions
  • Create branch, commit changes, and open PR via GitHub API
  • Return PR URL to plugin

Technical Requirements:

• Use ES modules (matches project standards)
• Follow monorepo tooling standards (pnpm, moon, AVA)
• Implement rate limiting and error handling
• Add comprehensive logging

2. GitHub App Setup & OAuth

• Create GitHub App for authentication

  • Configure OAuth flow
  • Set required permissions (contents: write, pull_requests: write)
  • Generate and securely store app credentials

• OAuth Implementation:

  • Backend handles OAuth callback
  • Issues temporary tokens to plugin
  • Token refresh mechanism
  • Secure token storage

Alternative: Support Personal Access Token (PAT) flow as fallback

3. Figma Plugin Integration

• UI Updates:

  • Add "Create PR" button to plugin interface
  • Authentication flow (GitHub App or PAT input)
  • PR creation progress indicator
  • Success screen with PR link
  • Error handling and user feedback

• Communication:

  • Plugin sends schema data to backend service
  • Backend returns PR URL or error details
  • Store auth state in Figma plugin storage

4. Changeset Generation

• Auto-generate changeset files following .changeset/ conventions:
  • Template: "Add {component-name} component schema" for new components
  • Template: "Update {component-name} component schema" for existing
  • Semver type: minor for new components, patch for updates
  • Include detailed change description

5. File Conflict Resolution

• Scenarios to handle:

  • New component schema (straightforward)
  • Update existing schema (check for conflicts)
  • Schema already exists with different structure
  • Branch naming conflicts

• Strategy:

  • Generate unique branch names: component-schema/{component-name}-{timestamp}
  • Detect file conflicts before PR creation
  • Provide clear error messages to user

Acceptance Criteria

• Backend service deployed and accessible from Figma plugin
• GitHub App created and OAuth flow functional
• Figma plugin can authenticate users via GitHub
• Plugin successfully converts and submits schema changes
• Backend creates properly formatted PRs with:
  • Converted schema file in packages/component-schemas/schemas/components/
  • Generated changeset file in .changeset/
  • Descriptive PR title and body
  • Proper branch naming
• Error handling covers all failure scenarios
• Documentation updated with:
  • Backend service setup instructions
  • GitHub App configuration guide
  • Figma plugin usage guide for PR creation
• Tests added for:
  • Backend endpoints (unit + integration)
  • Changeset generation
  • Error scenarios

Architecture Diagram

flowchart TD
    FigmaPlugin[Figma Plugin UI]
    Backend[Backend Service]
    Converter[Schema Converter Library]
    GitHub[GitHub API]
    
    FigmaPlugin -->|1. Authenticate| Backend
    Backend -->|2. OAuth Flow| GitHub
    FigmaPlugin -->|3. Submit Schema| Backend
    Backend -->|4. Convert| Converter
    Backend -->|5. Generate Changeset| Backend
    Backend -->|6. Create Branch & PR| GitHub
    Backend -->|7. Return PR URL| FigmaPlugin

Loading

Implementation Notes

Security Considerations:

• Never expose GitHub App secrets in client code
• Use HTTPS for all backend communication
• Implement CSRF protection
• Rate limit API endpoints
• Validate all input data

Testing Strategy:

• Unit tests for backend endpoints
• Integration tests with GitHub API (using test repos)
• E2E tests from Figma plugin through PR creation
• Mock GitHub API for fast test execution

Deployment:

• Backend service needs to be hosted (consider: Vercel, AWS Lambda, Azure Functions)
• Environment variables for GitHub App credentials
• CI/CD pipeline for automatic deployment

Related Files

• Schema converter library: packages/component-schema-converter/
• Figma plugin: tools/component-options-editor/
• Component schemas: packages/component-schemas/
• Changesets config: .changeset/config.json
• Plan document: .cursor/plans/component_schema_pr_integration_38e21d48.plan.md

Dependencies

• @adobe/component-schema-converter (Phase 1 - ✅ Complete)
• GitHub API client (e.g., @octokit/rest)
• Express or similar web framework
• Authentication library for GitHub OAuth

Future Enhancements (Phase 3+)

• Preview schema changes before PR creation
• Batch PR creation for multiple components
• Schema validation against existing components
• Automated tests in PR for schema changes
• Integration with design review process
• Metrics and analytics for schema submissions

---

Started: Phase 1 completed on 2026-01-21
Estimated Effort: Phase 2 is a substantial undertaking requiring backend infrastructure setup