# redhat-developer/rhdh architecture

> Architecture diagram of the GitHub repository redhat-developer/rhdh, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/redhat-developer/rhdh
- Repository: https://github.com/redhat-developer/rhdh

## Overview

##### Project Type and Purpose
- This is a full-stack, enterprise-grade Internal Developer Portal (Red Hat Developer Hub) built on Backstage.
- It consists of:
- A React-based Frontend (packages/app)
- A Node.js/Express-based Backend (packages/backend)
- Dozens of Backstage plugins (plugins/*) plus a dynamic-plugin wrapper layer (dynamic-plugins/*)
- CI/CD and infra code (manifests/, .github/workflows/, .ibm/pipelines)
- E2E test suite (e2e-tests/)

##### File-Structure Highlights
- packages/app: the core Backstage UI, bootstrap logic, plugin wiring (Scalprum dynamic-root loader), UI components, API client definitions.
- packages/backend: the Backstage backend service exposing plugin routes, auth, healthchecks, transitive-group-ownership resolution, dynamic-plugin loader.
- plugins/*: standalone plugins each with frontend and/or backend modules (e.g. dynamic-plugins-info, licensed-users-info, scalprum-backend).
- dynamic-plugins: the mechanism for packaging and loading community or custom plugins at runtime via wrapper packages.
- manifests/, docker/, scripts/: Kubernetes manifests, Dockerfiles, Helm hooks, and setup scripts for Keycloak, RH SSO, etc.
- .github/workflows & .ibm/pipelines: CI/CD pipelines for building images, running e2e tests, deploying to AKS/GKE/OpenShift.
- e2e-tests: Playwright suite for verifying UI flows and integrations (Auth, Plugins, RBAC, TLS, Redis cache).

##### Key Insights from README
- The system integrates many external systems via Backstage plugins: Keycloak (OIDC), GitHub (discovery/org data), Kubernetes, OCM, ArgoCD, Tekton, SonarQube, Jira, Dynatrace, Datadog, etc.
- Authentication is delegated to Keycloak (or other OIDC providers) via the Auth plugin.
- A Postgres database backs some plugins (e.g. licensed-users-info) and health checks. Redis is used as a cache for session or plugin-data.
- The app supports dynamic loading of plugins without rebuilding the core image.

##### Main Components & Interactions
A. Frontend (React/Backstage App)
- Hosts the Backstage core UI.
- Dynamically loads plugins from dynamic-plugins root (via Scalprum).
- Communicates to Backend over REST/HTTP through AuthApi, LearningPathApi, DynamicPluginsInfoApi, and plugin-specific APIs.

B. Backend (Node.js/Express)
- Serves plugin routes (router.ts in each backend plugin).
- Handles authentication introspection, RBAC enforcement, metrics (Prometheus), corporate-proxy.
- Loads dynamic-plugin bundles, exposes routes under /api/<plugin>.

C. Data Stores & Cache
- Postgres DB: licensed-users-info plugin, plugin metadata (via manifests/deployment).
- Redis Cache: global cache for sessions or resource data (verify-redis-cache in E2E tests).

D. External Services
- Identity: Keycloak (OIDC/OAuth2) or Google/Azure/GitHub providers.
- SCM & CI: GitHub (discovery, org data, actions, issues, pull requests), GitLab, Azure DevOps, Jenkins, Tekton.
- Kubernetes Cluster: OCM, ArgoCD, topology plugin, K8s plugin.
- Monitoring/Security: SonarQube, Dynatrace, Datadog, Security Insights plugin.
- Artifact Repositories: Quay, Nexus, JFrog Artifactory.
- Notifications: PagerDuty, Signals plugin.

E. CI/CD & Infra
- GitHub Actions + IBM pipelines build Docker images, run tests, push to quay.io.
- Kubernetes manifests (manifests/) and Helm overlays handle deployment to dev/prod.
- Scripts (scripts/) for setting up Keycloak, RH SSO, database secrets, operator deployments.

##### Architectural Patterns & Principles
- Plugin-based microfrontend architecture (Backstage + Scalprum).
- Modular backend services (each plugin provides its own router).
- Dynamic plugin loading to decouple release cycles.
- Clear separation of concerns: UI layer, API layer, persistence, external integrations.
- Infrastructure as code: declarative K8s manifests, Helm, CI pipelines.

##### Don’t Overthink—Capture Everything
- Enumerate as many components as possible (core, plugins, databases, caches, external systems, CI/CD).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Users
    Users["Developers & Operators"]:::external
    Users -->|"HTTPS"| FrontendApp

    %% UI Tier
    subgraph "UI Tier" 
        direction TB
        FrontendApp["Frontend App (React/Backstage)"]:::ui
        DynamicLoader["Scalprum Dynamic Plugin Loader"]:::ui
        subgraph "Dynamic Plugins"
            direction TB
            DynamicPluginsInfoFE["Dynamic Plugins Info (Frontend)"]:::ui
        end
        FrontendApp -->|loads plugins| DynamicLoader
        DynamicLoader -->|runtime bundles| DynamicPluginsInfoFE
    end

    %% API Tier
    subgraph "API Tier"
        direction TB
        BackendService["Backend Service (Node.js/Express)"]:::api
        AuthModule["Auth Module & OIDC"]:::api
        PluginRouters["Plugin Routers"]:::api
        Healthcheck["Healthchecks & Metrics"]:::api
        DynamicLoaderBE["Dynamic Plugin Loader (Backend)"]:::api
        subgraph "Backend Plugins"
            direction TB
            DynamicPluginsInfoBE["Dynamic Plugins Info (Backend)"]:::api
            LicensedUsersInfoBE["Licensed Users Info (Backend)"]:::api
            ScalprumBackend["Scalprum Backend Plugin"]:::api
        end
        BackendService --> AuthModule
        BackendService --> PluginRouters
        BackendService --> Healthcheck
        BackendService --> DynamicLoaderBE
        PluginRouters --> DynamicPluginsInfoBE
        PluginRouters --> LicensedUsersInfoBE
        PluginRouters --> ScalprumBackend
    end

    %% Data Tier
    subgraph "Data Tier"
        direction TB
        Postgres[(Postgres DB)]:::data
        Redis[(Redis Cache)]:::data
    end
    BackendService -->|TCP| Postgres
    BackendService -->|TCP| Redis

    %% External Services
    subgraph "External Services"
        direction TB
        Keycloak[(Keycloak / OIDC)]:::external
        GitHub[(GitHub API)]:::external
        Kubernetes[(Kubernetes Cluster)]:::external
        Monitoring[(Monitoring & Security)]:::external
    end
    FrontendApp -->|REST API| BackendService
    BackendService -->|OIDC| Keycloak
    BackendService -->|REST| GitHub
    BackendService -->|REST| Kubernetes
    BackendService -->|REST| Monitoring

    %% CI/CD & Infra
    subgraph "CI/CD & Infra" 
        direction TB
        GitHubActions["GitHub Actions"]:::cicd
        IBMPipelines["IBM Pipelines"]:::cicd
        DockerRegistry["Quay.io Registry"]:::cicd
        K8sDeployment["K8s Deployment (Manifests & Helm)"]:::cicd
        Scripts["Infra Scripts"]:::cicd
        E2ETests["E2E Test Suite (Playwright)"]:::cicd
        DockerSupport["Dockerfiles & Helpers"]:::cicd
    end
    GitHubActions -->|build images| DockerRegistry
    IBMPipelines -->|build & deploy| DockerRegistry
    DockerRegistry -->|deploy| K8sDeployment
    Scripts --> K8sDeployment
    E2ETests --> FrontendApp

    %% Click Events
    click FrontendApp "https://github.com/redhat-developer/rhdh/tree/main/packages/app"
    click DynamicLoader "https://github.com/redhat-developer/rhdh/tree/main/dynamic-plugins"
    click DynamicPluginsInfoFE "https://github.com/redhat-developer/rhdh/tree/main/plugins/dynamic-plugins-info"
    click BackendService "https://github.com/redhat-developer/rhdh/tree/main/packages/backend"
    click DynamicPluginsInfoBE "https://github.com/redhat-developer/rhdh/tree/main/plugins/dynamic-plugins-info-backend"
    click LicensedUsersInfoBE "https://github.com/redhat-developer/rhdh/tree/main/plugins/licensed-users-info-backend"
    click ScalprumBackend "https://github.com/redhat-developer/rhdh/tree/main/plugins/scalprum-backend"
    click GitHubActions "https://github.com/redhat-developer/rhdh/tree/main/.github/workflows"
    click IBMPipelines "https://github.com/redhat-developer/rhdh/tree/main/.ibm/pipelines"
    click K8sDeployment "https://github.com/redhat-developer/rhdh/tree/main/manifests/base"
    click K8sDeployment "https://github.com/redhat-developer/rhdh/tree/main/manifests/overlays/dev"
    click K8sDeployment "https://github.com/redhat-developer/rhdh/tree/main/manifests/overlays/prod"
    click Scripts "https://github.com/redhat-developer/rhdh/tree/main/scripts/keycloak-setup"
    click Scripts "https://github.com/redhat-developer/rhdh/tree/main/scripts/ping-identity-setup"
    click Scripts "https://github.com/redhat-developer/rhdh/tree/main/scripts/rhdh-openshift-setup"
    click Scripts "https://github.com/redhat-developer/rhdh/blob/main/scripts/patch-package.sh"
    click Scripts "https://github.com/redhat-developer/rhdh/blob/main/scripts/update-backstage.mjs"
    click E2ETests "https://github.com/redhat-developer/rhdh/tree/main/e2e-tests"
    click DockerSupport "https://github.com/redhat-developer/rhdh/tree/main/docker/"
    click DockerSupport "https://github.com/redhat-developer/rhdh/tree/main/.ibm/images/Dockerfile"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366d6
    classDef api fill:#DFFFE0,stroke:#28A745
    classDef data fill:#FFE4B3,stroke:#E08F0C
    classDef external fill:#E2E4E6,stroke:#6A737D
    classDef cicd fill:#F3E8FF,stroke:#6F42C1
```
