# jiteshy/backstage-plugin-synergy architecture

> Architecture diagram of the GitHub repository jiteshy/backstage-plugin-synergy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jiteshy/backstage-plugin-synergy
- Repository: https://github.com/jiteshy/backstage-plugin-synergy

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Layers
  subgraph "Backstage Frontend (packages/app)" 
    direction TB
    F_PLUG["Synergy Plugin Frontend"]:::frontend
    subgraph "Synergy Plugin Frontend"
      direction TB
      RC["React Components"]:::frontend
      HOOKS["Hooks"]:::frontend
      ROUTES["Routes Definition"]:::frontend
      API_CLIENT["SynergyApi Client"]:::frontend
    end
    RC -->|"use"| HOOKS
    HOOKS -->|"route via"| ROUTES
    ROUTES -->|"calls"| API_CLIENT
    API_CLIENT -->|"HTTP/JSON"| BE_ENDPOINT
  end

  subgraph "Backstage Backend (packages/backend)"
    direction TB
    B_PLUG["Synergy Plugin Backend"]:::backend
    subgraph "Synergy Plugin Backend"
      direction TB
      BE_ENTRY["Backend Entry & Registration"]:::backend
      BE_BOOT["Backend Bootstrap"]:::backend
      ROUTER["Express Router"]:::backend
      CONFIG["Config Reader"]:::backend
      GH_ADAPTER["GitHub Adapter"]:::backend
      GL_ADAPTER["GitLab Adapter"]:::backend
    end
    BE_ENTRY -->|initializes| BE_BOOT
    BE_BOOT -->|registers| ROUTER
    ROUTER -->|"uses"| GH_ADAPTER
    ROUTER -->|"uses"| GL_ADAPTER
    ROUTER -->|"loads config"| CONFIG
    GH_ADAPTER -->|"REST/JSON"| GitHub
    GL_ADAPTER -->|"REST/JSON"| GitLab
  end

  %% Shared Library
  COMMON["synergy-common (Shared Types & Utils)"]:::shared
  COMMON --- RC
  COMMON --- HOOKS
  COMMON --- BE_BOOT
  COMMON --- CONFIG

  %% Frontend to Backend
  API_CLIENT -->|"/api/synergy"| BE_ENTRY
  BE_ENDPOINT(("Backend API Endpoint")):::backend
  subgraph External_APIs
    direction TB
    GitHub(("GitHub API")):::external
    GitLab(("GitLab API")):::external
  end

  %% Click Events
  click F_PLUG "https://github.com/jiteshy/backstage-plugin-synergy/blob/main/plugins/synergy/src/plugin.ts"
  click RC "https://github.com/jiteshy/backstage-plugin-synergy/tree/main/plugins/synergy/src/components"
  click HOOKS "https://github.com/jiteshy/backstage-plugin-synergy/blob/main/plugins/synergy/src/hooks/useSynergyApi.ts"
  click ROUTES "https://github.com/jiteshy/backstage-plugin-synergy/blob/main/plugins/synergy/src/routes.ts"
  click API_CLIENT "https://github.com/jiteshy/backstage-plugin-synergy/blob/main/plugins/synergy/src/api/SynergyApi.ts"
  click API_CLIENT "https://github.com/jiteshy/backstage-plugin-synergy/blob/main/plugins/synergy/src/api/SynergyClient.ts"
  click API_CLIENT "https://github.com/jiteshy/backstage-plugin-synergy/blob/main/plugins/synergy/src/api/index.ts"
  click BE_ENTRY "https://github.com/jiteshy/backstage-plugin-synergy/blob/main/plugins/synergy-backend/src/index.ts"
  click BE_BOOT "https://github.com/jiteshy/backstage-plugin-synergy/blob/main/plugins/synergy-backend/src/plugin.ts"
  click ROUTER "https://github.com/jiteshy/backstage-plugin-synergy/blob/main/plugins/synergy-backend/src/service/router.ts"
  click GH_ADAPTER "https://github.com/jiteshy/backstage-plugin-synergy/blob/main/plugins/synergy-backend/src/lib/github.ts"
  click GL_ADAPTER "https://github.com/jiteshy/backstage-plugin-synergy/blob/main/plugins/synergy-backend/src/lib/gitlab.ts"
  click CONFIG "https://github.com/jiteshy/backstage-plugin-synergy/blob/main/plugins/synergy-backend/src/lib/configReader.ts"
  click COMMON "https://github.com/jiteshy/backstage-plugin-synergy/blob/main/plugins/synergy-common/src/index.ts"
  click COMMON "https://github.com/jiteshy/backstage-plugin-synergy/blob/main/plugins/synergy-common/src/types.ts"
  click BACKEND_HOST "https://github.com/jiteshy/backstage-plugin-synergy/tree/main/packages/backend"
  click FRONTEND_HOST "https://github.com/jiteshy/backstage-plugin-synergy/tree/main/packages/app"

  %% Styles
  classDef core fill:#D0E6FF,stroke:#1E90FF,color:#000
  classDef frontend fill:#DFFFE0,stroke:#32CD32,color:#000
  classDef backend fill:#FFE5CC,stroke:#FF8C00,color:#000
  classDef shared fill:#FFF5CC,stroke:#FFD700,color:#000
  classDef external fill:#E0E0E0,stroke:#A9A9A9,color:#000

  class FRONTEND_HOST core
  class BACKEND_HOST core
  class F_PLUG frontend
  class COMMON shared
  class GitHub,GitLab external
```
