# greenbone/gsa architecture

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

- Interactive diagram: https://gitdiagram.com/greenbone/gsa
- Repository: https://github.com/greenbone/gsa

## Overview

##### Project type and purpose
- This is a full-client React single-page application (SPA) called Greenbone Security Assistant (GSA).
- It bundles a GMP client library (src/gmp) and a React UI (src/web) that calls a back-end API (gsad) speaking the GMP protocol.

##### File structure
- Top-level
- .github/workflows → CI/CD pipelines (lint, test, build, container, release)
- .docker/ → local Docker Compose and production Dockerfile
- package.json, vite.config.ts, tsconfig.json → Node/Vite build configuration
- public/ → static assets (index.html, locales, robots.txt, config.js template)
- src/gmp
- GMP client: HTTP layer, XML/JSON transforms, command- & model definitions, settings, i18n support
- src/web
- React app:
– pages/ → route components
– components/ → reusable UI elements
– store/ → Redux state, actions, reducers, selectors
– hooks/, utils/, wizard/ → custom hooks, helper modules
- Tests scattered alongside implementations
- Build output (`build/`) is a static bundle served by any web server (e.g. gsad, nginx)

##### Architecture overview
A. Developer & CI environment
– Code in GitHub → triggers GitHub Actions → runs ESLint, Jest/vitest, builds JS, builds Docker image, publishes release/SBOM.
– Local dev:
- Vite development server serves SPA at http://127.0.0.1:8080
- gsad (external) must run with CORS to accept calls from the SPA
– Docker Compose (in .docker/compose.yml) can spin up containers for the SPA and optionally gsad for full integration.
B. Build & release
– `npm install` + `npm run build` (Vite) → `build/` folder with HTML/CSS/JS/assets
– Production Dockerfile copies `build/` into a minimal web-server container
C. Runtime / Production
– Browser loads index.html + JS bundle + CSS + locales + config.js
– React app initializes:
- Loads `config.js` into GmpSettings
- Sets up Redux store and i18next (translations from public/locales)
- Starts React Router (Routes.jsx)
– User actions dispatch Redux actions → UI components subscribe to store
– GMP library (src/gmp) handles all API calls to `apiProtocol + apiServer` via HTTP, parses XML/JSON, returns JS objects
– Back-end API (gsad) implements GMP, communicates with Greenbone scan engine

##### Relationships & data flows
- Developer → commits → GitHub → CI → build/test → container image → registry
- Developer (local) → runs Vite → edits code → HMR reload
- Browser ↔ HTTP(S) ↔ Static server (serves SPA assets)
- Brows­er ↔ HTTP(S) ↔ gsad API
- React components → dispatch Redux actions → GMP library → HTTP calls → backend → responses → reducers → UI updates
- i18next loads JSON translation files from public/locales

##### Architectural patterns & design principles
- Flux/Redux for unidirectional data flow
- Module separation:
- src/gmp for protocol abstraction
- src/web for presentation & state
- Component hierarchy: pages at top level, UI components below
- Build vs runtime separation: Vite in dev, static build in prod
- Configuration via external `config.js` (runtime override) and environment variables in Docker

##### Including technologies & frameworks
- React, React Router, Redux, i18next
- GMP protocol client (XML/HTTP) in TypeScript/JavaScript
- Vite for bundling, ESLint, Prettier for lint/format
- Docker & Docker Compose for containerization
- GitHub Actions for CI/CD
- Jest & Vitest for testing

##### Don’t over-complicate
- Break the front end into logical components:
- Static asset serving
- Bootstrapping (config + i18n + store)
- GMP communication layer
- UI layer (pages & components)
- Separately show CI/CD and container orchestration

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer & CI Environment
    subgraph "Developer & CI Environment"
        GH["GitHub Repo"]:::blue
        CI["CI Runner"]:::blue
        click CI "https://github.com/greenbone/gsa/tree/main/.github/workflows/"
        ReleaseWF["Release & SBOM Upload"]:::blue
        click ReleaseWF "https://github.com/greenbone/gsa/blob/main/.github/workflows/release.yml"
        click ReleaseWF "https://github.com/greenbone/gsa/blob/main/.github/workflows/sbom-upload.yml"
        DevMachine["Developer Machine"]:::blue
        ViteDev["Vite Dev Server"]:::blue
        click ViteDev "https://github.com/greenbone/gsa/blob/main/vite.config.ts"
        click ViteDev "https://github.com/greenbone/gsa/blob/main/package.json"
        click ViteDev "https://github.com/greenbone/gsa/blob/main/tsconfig.json"
        Compose["Docker Compose"]:::blue
        click Compose "https://github.com/greenbone/gsa/blob/main/.docker/compose.yml"
        ProdDocker["Production Dockerfile"]:::blue
        click ProdDocker "https://github.com/greenbone/gsa/blob/main/.docker/prod.Dockerfile"
        GH --> CI
        CI --> ReleaseWF
        DevMachine --> GH
        DevMachine --> CI
        DevMachine --> ViteDev
        DevMachine --> Compose
        ViteDev --> Browser
        Compose --> ViteDev
        Compose --> APIContainer
    end

    %% Build & Release
    subgraph "Build & Release"
        NPM["npm install & build"]:::orange
        Registry["Docker Registry"]:::orange
        click NPM "https://github.com/greenbone/gsa/blob/main/package.json"
        NPM --> Registry
        CI --> NPM
    end

    %% Production Cluster
    subgraph "Production Cluster"
        WebContainer["Static Server Container"]:::green
        APIContainer["gsad API Container"]:::green
        Registry --> WebContainer
        Registry --> APIContainer
    end

    %% Browser / SPA
    subgraph "Browser / SPA"
        Static["Static Assets"]:::purple
        click Static "https://github.com/greenbone/gsa/blob/main/public/index.html"
        click Static "https://github.com/greenbone/gsa/tree/main/public/locales/"
        Boot["SPA Bootstrap"]:::purple
        click Boot "https://github.com/greenbone/gsa/blob/main/src/index.jsx"
        Settings["GmpSettings (config.js)"]:::purple
        Store["Redux Store"]:::purple
        click Store "https://github.com/greenbone/gsa/tree/main/src/web/store/"
        Router["React Router"]:::purple
        click Router "https://github.com/greenbone/gsa/blob/main/src/web/Routes.jsx"
        UI["UI Components & Pages"]:::purple
        click UI "https://github.com/greenbone/gsa/tree/main/src/web/components/"
        click UI "https://github.com/greenbone/gsa/tree/main/src/web/pages/"
        Hooks["Hooks & Utils"]:::purple
        click Hooks "https://github.com/greenbone/gsa/tree/main/src/web/hooks/"
        click Hooks "https://github.com/greenbone/gsa/tree/main/src/web/utils/"
        Wizard["Wizard Flows"]:::purple
        click Wizard "https://github.com/greenbone/gsa/tree/main/src/web/wizard/"
        GMP["GMP Client Library"]:::purple
        click GMP "https://github.com/greenbone/gsa/tree/main/src/gmp/"
    end

    %% Data Flows
    Browser -->|loads| Static
    Static --> Boot
    Boot --> Settings
    Boot --> Store
    Boot --> Router
    Store --> UI
    Router --> UI
    UI -->|dispatch actions| GMP
    GMP -->|HTTP calls| APIContainer
    APIContainer -->|responses| GMP
    GMP -->|updates| Store
    Store --> UI
    Browser -->|HTTPS| WebContainer
    Browser -->|HTTPS| APIContainer

    %% Styles
    classDef blue fill:#cce5ff,stroke:#004085,color:#004085
    classDef orange fill:#fff3cd,stroke:#856404,color:#856404
    classDef green fill:#d4edda,stroke:#155724,color:#155724
    classDef purple fill:#e2e3f3,stroke:#6f42c1,color:#6f42c1
```
