# ansible/ansible-backstage-plugins architecture

> Architecture diagram of the GitHub repository ansible/ansible-backstage-plugins, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ansible/ansible-backstage-plugins
- Repository: https://github.com/ansible/ansible-backstage-plugins

## Overview

This monorepo delivers Ansible self-service and AAP capabilities inside a Backstage developer portal. Developers enter through the Backstage app, browse cataloged automation resources, and use self-service screens or scaffolder workflows to create and launch automation; catalog providers synchronize AAP and SCM content for those experiences. Shared clients connect backend features to AAP and source-control services. The README documents authentication, RBAC, catalog integration, scaffolder actions, and dynamic-plugin deployment. Some subsystem links below are documented capabilities rather than verified calls; the source excerpts are incomplete.

Main entry points: [`packages/app/src/App.tsx`](https://github.com/ansible/ansible-backstage-plugins/blob/main/packages/app/src/App.tsx) (Backstage app), [`plugins/catalog-backend-module-rhaap/src/router.ts`](https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/catalog-backend-module-rhaap/src/router.ts) (Catalog sync API), [`plugins/backstage-rhaap-common/src/AAPService/AAPService.ts`](https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/backstage-rhaap-common/src/AAPService/AAPService.ts) (AAP service), [`plugins/self-service/src/components/notifications/syncPollingService.ts`](https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/self-service/src/components/notifications/syncPollingService.ts) (Sync notifications)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portal["Backstage portal"]
  node_app["Backstage app<br/>[App.tsx]"]
  node_header["Global header<br/>[GlobalHeader.tsx]"]
  node_catalog_ui["Catalog UI<br/>[EntityPage.tsx]"]
end

subgraph group_experience["Ansible experiences"]
  node_ansible_ui["Ansible portal<br/>[AnsiblePage.tsx]"]
  node_selfservice["Self-service UI<br/>[LandingPage.tsx]"]
  node_job_templates["Job templates<br/>[Home.tsx]"]
  node_collections["Collections catalog"]
  node_ee["Execution environments<br/>[EERoutesPage.tsx]"]
  node_git_repos["Git repositories"]
  node_task_create["Create workflows<br/>[CreateTask.tsx]"]
  node_task_run["Run workflows<br/>[RunTask.tsx]"]
  node_notifications["Sync notifications"]
end

subgraph group_backend["Automation backend"]
  node_catalog_backend["Catalog sync API<br/>[router.ts]"]
  node_aap_providers["AAP catalog providers"]
  node_git_provider["SCM content provider"]
  node_entity_parser["Entity parsing<br/>[entityParser.ts]"]
  node_scaffolder_actions["AAP scaffolder actions"]
  node_auth["AAP authentication<br/>[authenticator.ts]"]
  node_user_templates["User template API"]
  node_aap_service["AAP service<br/>[AAPService.ts]"]
  node_aap_client["AAP API client<br/>[AAPClient.ts]"]
  node_scm_client["SCM client<br/>[ScmClient.ts]"]
end

subgraph group_integrations["External services"]
  node_aap{{"Ansible Automation Platform"}}
  node_scm{{"GitHub / GitLab"}}
end

node_developer(("Developer"))

node_developer -->|"opens portal"| node_app
node_app -->|"routes to"| node_ansible_ui
node_app -->|"routes to"| node_selfservice
node_app -->|"routes to"| node_catalog_ui
node_app -->|"renders"| node_header
node_developer -.->|"browses and launches"| node_job_templates
node_developer -.->|"browses"| node_collections
node_developer -.->|"manages"| node_ee
node_developer -.->|"browses"| node_git_repos
node_developer -->|"creates workflows"| node_task_create
node_developer -->|"triggers automation"| node_task_run
node_catalog_backend -->|"routes sync"| node_aap_providers
node_catalog_backend -->|"routes sync"| node_git_provider
node_aap_providers -.->|"parses entities"| node_entity_parser
node_git_provider -.->|"parses entities"| node_entity_parser
node_aap_providers -.->|"reads AAP resources"| node_aap_service
node_git_provider -.->|"reads repositories"| node_scm_client
node_catalog_backend -->|"syncs resources"| node_aap
node_scaffolder_actions -->|"interacts with AAP"| node_aap_service
node_auth -->|"authenticates"| node_aap
node_user_templates -->|"fetches templates"| node_aap_service
node_aap_service -->|"delegates requests"| node_aap_client
node_aap_client -->|"calls API"| node_aap
node_scm_client -->|"reads source"| node_scm
node_notifications -.->|"polls sync status"| node_catalog_backend
node_notifications -->|"invalidates catalog cache"| node_collections
node_notifications -->|"invalidates repository cache"| node_git_repos

click node_app "https://github.com/ansible/ansible-backstage-plugins/blob/main/packages/app/src/App.tsx"
click node_header "https://github.com/ansible/ansible-backstage-plugins/blob/main/packages/app/src/components/GlobalHeader/GlobalHeader.tsx"
click node_catalog_ui "https://github.com/ansible/ansible-backstage-plugins/blob/main/packages/app/src/components/catalog/EntityPage.tsx"
click node_ansible_ui "https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/backstage-rhaap/src/components/AnsiblePage/AnsiblePage.tsx"
click node_selfservice "https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/self-service/src/components/LandingPage/LandingPage.tsx"
click node_job_templates "https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/self-service/src/components/Home/Home.tsx"
click node_collections "https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/self-service/src/components/CollectionsCatalog/CollectionsCatalogPage.tsx"
click node_ee "https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/self-service/src/components/ExecutionEnvironments/EERoutesPage.tsx"
click node_git_repos "https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/self-service/src/components/GitRepositories/GitRepositoriesPage.tsx"
click node_task_create "https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/self-service/src/components/CreateTask/CreateTask.tsx"
click node_task_run "https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/self-service/src/components/RunTask/RunTask.tsx"
click node_notifications "https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/self-service/src/components/notifications/syncPollingService.ts"
click node_catalog_backend "https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/catalog-backend-module-rhaap/src/router.ts"
click node_aap_providers "https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/catalog-backend-module-rhaap/src/providers/AAPEntityProvider.ts"
click node_git_provider "https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/catalog-backend-module-rhaap/src/providers/AnsibleGitContentsProvider.ts"
click node_entity_parser "https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/catalog-backend-module-rhaap/src/providers/entityParser.ts"
click node_scaffolder_actions "https://github.com/ansible/ansible-backstage-plugins/tree/main/plugins/scaffolder-backend-module-backstage-rhaap/src/actions"
click node_auth "https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/auth-backend-module-rhaap-provider/src/authenticator.ts"
click node_user_templates "https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/auth-backend-module-rhaap-provider/src/userJobTemplatesRouter.ts"
click node_aap_service "https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/backstage-rhaap-common/src/AAPService/AAPService.ts"
click node_aap_client "https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/backstage-rhaap-common/src/AAPClient/AAPClient.ts"
click node_scm_client "https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/backstage-rhaap-common/src/ScmClient/ScmClient.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_header,node_catalog_ui toneBlue
class node_ansible_ui,node_selfservice,node_job_templates,node_collections,node_ee,node_git_repos,node_task_create,node_task_run,node_notifications toneAmber
class node_catalog_backend,node_aap_providers,node_git_provider,node_entity_parser,node_scaffolder_actions,node_auth,node_user_templates,node_aap_service,node_aap_client,node_scm_client toneMint
class node_aap,node_scm toneRose
class node_developer toneIndigo
```

## Components

### Backstage portal

- [Backstage app](https://github.com/ansible/ansible-backstage-plugins/blob/main/packages/app/src/App.tsx): `packages/app/src/App.tsx`
- [Global header](https://github.com/ansible/ansible-backstage-plugins/blob/main/packages/app/src/components/GlobalHeader/GlobalHeader.tsx): `packages/app/src/components/GlobalHeader/GlobalHeader.tsx`
- [Catalog UI](https://github.com/ansible/ansible-backstage-plugins/blob/main/packages/app/src/components/catalog/EntityPage.tsx): `packages/app/src/components/catalog/EntityPage.tsx`

### Ansible experiences

- [Ansible portal](https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/backstage-rhaap/src/components/AnsiblePage/AnsiblePage.tsx): `plugins/backstage-rhaap/src/components/AnsiblePage/AnsiblePage.tsx`
- [Self-service UI](https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/self-service/src/components/LandingPage/LandingPage.tsx): `plugins/self-service/src/components/LandingPage/LandingPage.tsx`
- [Job templates](https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/self-service/src/components/Home/Home.tsx): `plugins/self-service/src/components/Home/Home.tsx`
- [Collections catalog](https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/self-service/src/components/CollectionsCatalog/CollectionsCatalogPage.tsx): `plugins/self-service/src/components/CollectionsCatalog/CollectionsCatalogPage.tsx`
- [Execution environments](https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/self-service/src/components/ExecutionEnvironments/EERoutesPage.tsx): `plugins/self-service/src/components/ExecutionEnvironments/EERoutesPage.tsx`
- [Git repositories](https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/self-service/src/components/GitRepositories/GitRepositoriesPage.tsx): `plugins/self-service/src/components/GitRepositories/GitRepositoriesPage.tsx`
- [Create workflows](https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/self-service/src/components/CreateTask/CreateTask.tsx): `plugins/self-service/src/components/CreateTask/CreateTask.tsx`
- [Run workflows](https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/self-service/src/components/RunTask/RunTask.tsx): `plugins/self-service/src/components/RunTask/RunTask.tsx`
- [Sync notifications](https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/self-service/src/components/notifications/syncPollingService.ts): `plugins/self-service/src/components/notifications/syncPollingService.ts`

### Automation backend

- [Catalog sync API](https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/catalog-backend-module-rhaap/src/router.ts): `plugins/catalog-backend-module-rhaap/src/router.ts`
- [AAP catalog providers](https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/catalog-backend-module-rhaap/src/providers/AAPEntityProvider.ts): `plugins/catalog-backend-module-rhaap/src/providers/AAPEntityProvider.ts`
- [SCM content provider](https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/catalog-backend-module-rhaap/src/providers/AnsibleGitContentsProvider.ts): `plugins/catalog-backend-module-rhaap/src/providers/AnsibleGitContentsProvider.ts`
- [Entity parsing](https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/catalog-backend-module-rhaap/src/providers/entityParser.ts): `plugins/catalog-backend-module-rhaap/src/providers/entityParser.ts`
- [AAP scaffolder actions](https://github.com/ansible/ansible-backstage-plugins/tree/main/plugins/scaffolder-backend-module-backstage-rhaap/src/actions): `plugins/scaffolder-backend-module-backstage-rhaap/src/actions`
- [AAP authentication](https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/auth-backend-module-rhaap-provider/src/authenticator.ts): `plugins/auth-backend-module-rhaap-provider/src/authenticator.ts`
- [User template API](https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/auth-backend-module-rhaap-provider/src/userJobTemplatesRouter.ts): `plugins/auth-backend-module-rhaap-provider/src/userJobTemplatesRouter.ts`
- [AAP service](https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/backstage-rhaap-common/src/AAPService/AAPService.ts): `plugins/backstage-rhaap-common/src/AAPService/AAPService.ts`
- [AAP API client](https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/backstage-rhaap-common/src/AAPClient/AAPClient.ts): `plugins/backstage-rhaap-common/src/AAPClient/AAPClient.ts`
- [SCM client](https://github.com/ansible/ansible-backstage-plugins/blob/main/plugins/backstage-rhaap-common/src/ScmClient/ScmClient.ts): `plugins/backstage-rhaap-common/src/ScmClient/ScmClient.ts`

### External services

- **Ansible Automation Platform**
- **GitHub / GitLab**

### Other components

- **Developer**

## Connections

- Developer → Backstage app: opens portal
- Backstage app → Ansible portal: routes to (evidence: `packages/app/src/App.tsx`)
- Backstage app → Self-service UI: routes to (evidence: `packages/app/src/App.tsx`)
- Backstage app → Catalog UI: routes to (evidence: `packages/app/src/App.tsx`)
- Backstage app → Global header: renders (evidence: `packages/app/src/App.tsx`)
- Developer → Job templates: browses and launches
- Developer → Collections catalog: browses
- Developer → Execution environments: manages
- Developer → Git repositories: browses
- Developer → Create workflows: creates workflows
- Developer → Run workflows: triggers automation
- Catalog sync API → AAP catalog providers: routes sync (evidence: `plugins/catalog-backend-module-rhaap/src/router.ts`)
- Catalog sync API → SCM content provider: routes sync (evidence: `plugins/catalog-backend-module-rhaap/src/router.ts`)
- AAP catalog providers → Entity parsing: parses entities
- SCM content provider → Entity parsing: parses entities
- AAP catalog providers → AAP service: reads AAP resources
- SCM content provider → SCM client: reads repositories
- Catalog sync API → Ansible Automation Platform: syncs resources
- AAP scaffolder actions → AAP service: interacts with AAP
- AAP authentication → Ansible Automation Platform: authenticates
- User template API → AAP service: fetches templates (evidence: `plugins/auth-backend-module-rhaap-provider/src/userJobTemplatesRouter.ts`)
- AAP service → AAP API client: delegates requests (evidence: `plugins/backstage-rhaap-common/src/AAPService/AAPService.ts`)
- AAP API client → Ansible Automation Platform: calls API (evidence: `plugins/backstage-rhaap-common/src/AAPClient/AAPClient.ts`)
- SCM client → GitHub / GitLab: reads source
- Sync notifications → Catalog sync API: polls sync status
- Sync notifications → Collections catalog: invalidates catalog cache (evidence: `plugins/self-service/src/components/notifications/syncPollingService.ts`)
- Sync notifications → Git repositories: invalidates repository cache (evidence: `plugins/self-service/src/components/notifications/syncPollingService.ts`)
