How jiteshy/backstage-plugin-synergy works
Project Type and Purpose
• This is a Backstage.io plugin called “backstage-plugin-synergy” packaged in a monorepo.
• It extends a Backstage full-stack application with both a frontend (React) plugin and a backend (Node/Express) plugin.
• Purpose: surfacing Inner-Source project and issue data (from GitHub/GitLab) inside a Backstage app.
File-Structure Analysis
• Root contains monorepo configs (lerna.json, yarn workspaces), CI/CD workflows, global lint/prettier settings, app- and backend-level configs (app-config.yaml, backstage.json).
• packages/app → Backstage frontend app (React/TypeScript).
• packages/backend → Backstage backend service (Express, Node).
• plugins/synergy → plugin’s frontend code (React components, API client, plugin registration).
• plugins/synergy-backend → plugin’s backend code (router, services, GitHub/GitLab integration, config reader).
• plugins/synergy-common → shared types and utilities used by both the frontend and backend plugin.
README Insights
• Confirms the plugin’s dual nature (frontend + backend).
• Supports GitHub and GitLab integrations.
• Requires the “new backend system” (modern Backstage backend plugin model).
Main Components
a. Backstage Core
• packages/app (Frontend host)
• packages/backend (Backend host)
b. Synergy Plugin Frontend
• React components, hooks, SynergyApi client
• Entry via plugins/synergy/src/plugin.ts
c. Synergy Plugin Backend
• Express router (plugins/synergy-backend/src/service/router.ts)
• Service layer modules (github.ts, gitlab.ts)
• Config reader (configReader.ts)
d. Shared Library
• plugins/synergy-common (types, utilities)
e. External Services
• GitHub API
• GitLab API
Component Relationships and Data Flow
1. User → Browser → Backstage UI (packages/app)
2. Backstage UI routes to Synergy plugin pages (React Router)
3. React pages call SynergyApi client (frontend)
4. SynergyApi performs HTTP calls to Backstage backend on plugin’s mount point
5. Backend router (synergy-backend) receives requests
6. Router invokes service modules (GitHub/GitLab adapters)
7. Service modules call external GitHub/GitLab APIs, parse results
8. Results propagate back through router → frontend → UI
Architectural Patterns and Principles
• Monorepo with Yarn Workspaces + Lerna for modularity.
• Clear separation of concerns between host app, plugin frontend, plugin backend, and shared code.
• Plugin-based architecture as per Backstage’s extension model.
• Adapter pattern for external API integrations (GitHub/GitLab).
• Configuration via YAML (app-config.yaml) and JSON schemas.
Detailed Steps for Creation
• Left: Backstage Frontend (packages/app)
• Right: Backstage Backend (packages/backend)
• React components → SynergyApi client → HTTP call to backend.
• Router → Service Layer → GitHub/GitLab adapter modules.