# ansible/ansible-ui architecture

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

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

## Overview

##### Project Type and Purpose
- This is a monorepo full-stack UI project that ships three React/TypeScript client applications—AWX UI, EDA UI, and HUB UI—backed by a shared “framework” component library.
- It does not contain the backend services themselves; rather, each UI calls out to its corresponding backend (AWX server, EDA server, Galaxy HUB server) as configured by environment variables.

##### File Structure Highlights
- Top-level:
- frontend/awx, frontend/eda, frontend/hub – the three separate client apps
- framework/ – the shared PatternFly-based component library
- cypress/ – end-to-end and component test suites
- nginx/ – production Nginx configuration files
- Dockerfile, .github/workflows/ – CI/CD definitions
- Each client subfolder is a conventional React app (src, assets, tsconfig, etc.) using shared “framework” via an internal package reference.
- Cypress sits at the root and in each app folder to drive E2E and component tests against locally running servers.
- Dockerfile and Nginx configs show that apps get containerized and served behind Nginx with API proxying.

##### Key README Insights
- Scripts like `npm run awx`, `npm run hub`, `npm run eda` launch each UI on a different port locally.
- Environment variables AWX_SERVER, EDA_SERVER, HUB_SERVER define API backends.
- CI runs TypeScript checks, ESLint, Prettier, and Cypress tests in GitHub Actions workflows.

##### Main Components
a. Developer / CI Environment
– Local Node/NPM build & dev servers for each app
– Cypress test runner (E2E + component tests)
– GitHub Actions (lint → tsc → build → test → Docker build → deploy)
b. Shared Library
– framework package (shared React components, hooks, utilities)
c. Client Applications
– AWX UI (React app served on http://localhost:4101)
– EDA UI (React app served on http://localhost:4103)
– HUB UI (React app served on http://localhost:4102)
d. Production Web Tier
– Docker container with Nginx serving static assets and reverse-proxying API calls
e. Backend Services (External)
– AWX server REST/WebSocket API
– EDA server REST API
– Galaxy HUB server API (galaxykit)

##### Interactions and Data Flow
- Browser → HTTP GET (static JS/CSS) → Nginx
- Browser JS → AJAX/Fetch or WebSocket → Nginx API proxy → Backend
- Cypress tests → HTTP to local dev server → run UI flows → validate responses
- CI pipeline → builds + tests + Docker image → deploy to staging/production

##### Architectural Patterns & Principles
- Monorepo with multiple client packages and a shared UI library
- Component library / design system (framework) for consistency
- Separation of concerns: UI layer (React + PatternFly) vs. API backends
- CI/CD pipeline with automated lint, build, test, containerization
- Environment‐driven configuration for backends and API prefixes

##### Essential Elements to Capture
- Monorepo structure → shared framework + three client apps
- Developer vs. CI vs. production environments
- Data flow: browser → static assets → API calls → backends
- Cypress/E2E test integration
- Docker + Nginx containerization and proxy configuration

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer & CI Environment
    subgraph "Developer & CI Environment"
        direction TB
        GH_PR["GitHub Actions: pull-request.yml"]:::ci
        GH_Component["GitHub Actions: component.yml"]:::ci
        GH_Sync["GitHub Actions: sync-downstream.yml"]:::ci
        Husky["Pre-commit Hooks"]:::ci
        DockerfileNode["Dockerfile"]:::ci
        PackageJSON["package.json"]:::ci
        DevServerAWX["AWX Dev Server (localhost:4101)"]:::service
        DevServerEDA["EDA Dev Server (localhost:4103)"]:::service
        DevServerHUB["HUB Dev Server (localhost:4102)"]:::service
        CypressRunner["Cypress Test Runner"]:::ci
    end

    %% Shared Framework Library
    subgraph "Shared Framework Library"
        direction TB
        Framework["framework/"]:::codeLib
        FrameworkIndex["index.ts"]:::codeLib
        PageFramework["PageFramework.tsx"]:::codeLib
    end

    %% Client Applications
    subgraph "Client Applications"
        direction TB
        AWXClient["AWX UI"]:::service
        AwxApp["AwxApp.tsx"]:::codeLib
        AwxRoutes["AwxRoutes.tsx"]:::codeLib
        EDAClient["EDA UI"]:::service
        EdaApp["EdaApp.tsx"]:::codeLib
        EdaRoutes["EdaRoutes.tsx"]:::codeLib
        HUBClient["HUB UI"]:::service
        HubApp["HubApp.tsx"]:::codeLib
        HubRoutes["HubRoutes.tsx"]:::codeLib
    end

    %% Production Web Tier
    subgraph "Production Web Tier"
        direction TB
        Nginx["Nginx Container"]:::service
        NginxConf["nginx.conf"]:::service
    end

    %% External Backend Services
    subgraph "External Backend Services"
        direction TB
        AWXServer["AWX Server API"]:::external
        EDAServer["EDA Server API"]:::external
        HUBServer["Galaxy HUB Server API"]:::external
    end

    %% Connections
    GH_PR -->|"triggers build"| GH_Component
    GH_Component -->|"runs CI steps"| GH_Sync
    GH_Sync -->|"invokes"| DockerfileNode
    Husky -->|"pre-commit"| GH_PR
    DockerfileNode -->|"build image"| Nginx
    PackageJSON -->|"defines scripts"| DevServerAWX
    PackageJSON -->|"defines scripts"| DevServerEDA
    PackageJSON -->|"defines scripts"| DevServerHUB
    DevServerAWX -->|"serves AWX UI"| AWXClient
    DevServerEDA -->|"serves EDA UI"| EDAClient
    DevServerHUB -->|"serves HUB UI"| HUBClient
    CypressRunner -->|"tests via HTTP"| DevServerAWX
    CypressRunner -->|"tests via HTTP"| DevServerEDA
    CypressRunner -->|"tests via HTTP"| DevServerHUB

    AWXClient -->|"imports"| Framework
    EDAClient -->|"imports"| Framework
    HUBClient -->|"imports"| Framework

    AWXClient -->|"HTTP/WebSocket"| Nginx
    EDAClient -->|"HTTP"| Nginx
    HUBClient -->|"HTTP"| Nginx

    Nginx -->|"proxy HTTP/WS"| AWXServer
    Nginx -->|"proxy HTTP"| EDAServer
    Nginx -->|"proxy HTTP"| HUBServer

    %% Click Events
    click GH_PR "https://github.com/ansible/ansible-ui/blob/main/.github/workflows/pull-request.yml"
    click GH_Component "https://github.com/ansible/ansible-ui/blob/main/.github/workflows/component.yml"
    click GH_Sync "https://github.com/ansible/ansible-ui/blob/main/.github/workflows/sync-downstream.yml"
    click Husky "https://github.com/ansible/ansible-ui/tree/main/.husky/pre-commit"
    click DockerfileNode "https://github.com/ansible/ansible-ui/tree/main/Dockerfile"
    click PackageJSON "https://github.com/ansible/ansible-ui/blob/main/package.json"
    click Framework "https://github.com/ansible/ansible-ui/tree/main/framework/"
    click FrameworkIndex "https://github.com/ansible/ansible-ui/blob/main/framework/index.ts"
    click PageFramework "https://github.com/ansible/ansible-ui/blob/main/framework/PageFramework.tsx"
    click AwxApp "https://github.com/ansible/ansible-ui/blob/main/frontend/awx/main/AwxApp.tsx"
    click AwxRoutes "https://github.com/ansible/ansible-ui/blob/main/frontend/awx/main/AwxRoutes.tsx"
    click EdaApp "https://github.com/ansible/ansible-ui/blob/main/frontend/eda/main/EdaApp.tsx"
    click EdaRoutes "https://github.com/ansible/ansible-ui/blob/main/frontend/eda/main/EdaRoutes.tsx"
    click HubApp "https://github.com/ansible/ansible-ui/blob/main/frontend/hub/main/HubApp.tsx"
    click HubRoutes "https://github.com/ansible/ansible-ui/blob/main/frontend/hub/main/HubRoutes.tsx"
    click NginxConf "https://github.com/ansible/ansible-ui/blob/main/nginx/nginx.conf"

    %% Styles
    classDef codeLib fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef service fill:#d4edda,stroke:#333,stroke-width:1px
    classDef external fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef ci fill:#e2e3e5,stroke:#333,stroke-width:1px
```
