GateForge

Migration Pipeline (kuadrantctl + AI Verification)

flowchart TD
  Analyze["POST /api/migration/analyze"] --> FetchOAS{"Fetch OpenAPI\nfrom backend?"}
  FetchOAS -->|Found| KuadrantCtl["kuadrantctl generate\nhttproute / authpolicy / ratelimitpolicy"]
  FetchOAS -->|Not found| BuildOAS["Build synthetic OpenAPI\nfrom 3scale mapping rules"]
  BuildOAS --> KuadrantCtl
  KuadrantCtl -->|Success| PostProcess["Post-process: namespace,\ngateway, labels"]
  KuadrantCtl -->|Fail| Fallback["Fallback:\nimproved Java templates"]
  PostProcess --> Consolidate{"Rules > 16?"}
  Consolidate -->|Yes| Merge["Consolidate to\nPathPrefix matches"]
  Consolidate -->|No| AIVerify
  Merge --> AIVerify["MigrationAgent:\nverify & recommend"]
  Fallback --> AIVerify
  AIVerify --> Plan["Store plan + AI analysis"]
  Plan --> DB["Persist to PostgreSQL"]
  Plan --> SELECT["Select Target Cluster"]
  SELECT --> APPLY["Apply to Target\n(editable YAML)"]
  APPLY --> AUDIT["Record in Audit Log"]
        

Developer Hub — 3scale Auto-Discovery + GateForge Plugin

sequenceDiagram
  participant ThreeScale as 3scale Admin API
  participant Plugin3s as RHDH 3scale Plugin
  participant Catalog as RHDH Catalog
  participant GateForge as GateForge Backend
  participant Scaffolder as RHDH Scaffolder
  participant K8s as OpenShift Cluster
  participant PluginGF as GateForge Frontend Plugin
  participant THANOS as Thanos Querier

  Plugin3s->>ThreeScale: Poll products (every 5 min)
  ThreeScale-->>Plugin3s: Product list
  Plugin3s->>Catalog: Create/update API entities

  GateForge->>K8s: Apply Kuadrant resources
  GateForge->>GateForge: Generate Component catalog-info.yaml
  GateForge->>Scaffolder: POST /api/scaffolder/v2/tasks (gateforge-register-component)
  Scaffolder->>Catalog: catalog:register (from GateForge URL)
  Note over GateForge,Scaffolder: On timeout → error to user

  PluginGF->>K8s: Fetch policies (AuthPolicy, RateLimitPolicy, etc.)
  PluginGF->>PluginGF: Render Policy Topology tab
  PluginGF->>THANOS: Proxy metrics query
  PluginGF->>PluginGF: Render Observability tab
        

Generated CRDs per Product (Connectivity Link 1.3)

flowchart LR
  Product["3scale Product"] --> Gateway["Gateway"]
  Product --> HTTPRoute["HTTPRoute"]
  Product --> AuthPolicy["AuthPolicy"]
  Product --> RateLimit["RateLimitPolicy"]
  Product --> APIProduct["APIProduct\n(devportal.kuadrant.io)"]
  Product --> Route["OpenShift Route"]

  Plans["Application Plans"] --> PlanPolicy["PlanPolicy\n(extensions.kuadrant.io)"]
  Keys["Application Keys"] --> APIKey["Secret\n(api_key from 3scale user_key)"]

  Observability{"Observability\nenabled?"} -->|Yes| TelemetryPolicy["TelemetryPolicy\n(extensions.kuadrant.io)"]
  Observability -->|No| Skip["Skipped"]

  style APIProduct fill:#e6f5e0,stroke:#2d6b24
  style PlanPolicy fill:#e0ecff,stroke:#0066cc
  style APIKey fill:#e0ecff,stroke:#0066cc
  style TelemetryPolicy fill:#fff3e0,stroke:#e65100
  style Skip fill:#f5f5f5,stroke:#999
        

AI Chat FAQ Cache Flow

flowchart LR
  User[User Question] --> Normalize[Normalize text]
  Normalize --> CacheCheck{FAQ Cache Hit?}
  CacheCheck -->|Yes| Instant["Return cached response (ms)"]
  CacheCheck -->|No| LLM["Call LLM (30-60s)"]
  LLM --> Response[Return AI response]
  Startup[App Startup] --> WarmUp["Background: send FAQ prompts to LLM"]
  WarmUp --> DataGrid["Store in Data Grid (gateforge-faq)"]
        

AI / MCP Tool Calling Flow

sequenceDiagram
  participant U as User
  participant Chat as ChatComponent
  participant Agent as MigrationAgent
  participant LLM as LiteLLM (deepseek-r1)
  participant Tools as GateForgeTools
  participant Svc as Backend Services

  U->>Chat: Ask question
  Chat->>Agent: POST /api/chat
  Agent->>LLM: Chat completion + tool definitions
  LLM-->>Agent: tool_call: listThreeScaleProducts()
  Agent->>Tools: invoke listThreeScaleProducts
  Tools->>Svc: ThreeScaleService.listProducts()
  Svc-->>Tools: Product list (all sources)
  Tools-->>Agent: Formatted product data
  Agent->>LLM: Tool result + continue
  LLM-->>Agent: Final answer with real data
  Agent-->>Chat: Response
  Chat-->>U: Display answer
        

Migration in 4 Steps

graph LR
    Discover["1. Discover APIs"] --> Analyze["2. AI Analysis"]
    Analyze --> Review["3. Review & Apply"]
    Review --> Verify["4. Verify in DevHub"]

    style Discover fill:#e0ecff,stroke:#0066cc,stroke-width:2px
    style Analyze fill:#fce4ec,stroke:#880e4f,stroke-width:2px
    style Review fill:#e6f5e0,stroke:#2d6b24,stroke-width:2px
    style Verify fill:#fff3e0,stroke:#e65100,stroke-width:2px
        

sequenceDiagram
  participant User as Platform Admin
  participant FE as GateForge Frontend
  participant BE as GateForge Backend
  participant SCF as RHDH Scaffolder
  participant CAT as RHDH Catalog
  participant K8s as OpenShift

  User->>FE: Click "Apply Migration"
  FE->>BE: POST /api/migration/plans/{id}/apply
  BE->>K8s: Apply Kuadrant resources
  BE-->>FE: Resources applied (editable Component YAML)
  User->>FE: Review/edit Component YAML
  User->>FE: Click "Register in Developer Hub"
  FE->>BE: POST /api/migration/plans/{id}/confirm-registration
  BE->>SCF: POST /api/scaffolder/v2/tasks (gateforge-register-component)
  SCF->>BE: GET /api/migration/plans/{id}/catalog-info/{product}
  BE-->>SCF: catalog-info.yaml (Component definition)
  SCF->>CAT: catalog:register
  CAT-->>SCF: entityRef
  SCF-->>BE: 201 Created (task ID)
  BE-->>FE: {status: "registered"}
        

ArgoCD Hub-Spoke Topology

flowchart TB
  subgraph HubCluster["Hub Cluster (OpenShift)"]
    ARGO["ArgoCD\n(openshift-gitops)"]
    GF["GateForge\n(Helm chart)"]
    RHDH["Developer Hub\n(dynamic plugins)"]
    PG[("PostgreSQL")]
  end

  subgraph SpokeA["Spoke Cluster A"]
    CLA["Connectivity Link\n(Kuadrant)"]
    GWA["Gateway + HTTPRoute\nAuthPolicy + RateLimitPolicy"]
  end

  subgraph SpokeB["Spoke Cluster B"]
    CLB["Connectivity Link\n(Kuadrant)"]
    GWB["Gateway + HTTPRoute\nAuthPolicy + RateLimitPolicy"]
  end

  ARGO -->|deploy chart| GF
  GF --> PG
  GF -->|apply resources| CLA
  GF -->|apply resources| CLB
  GF -->|Scaffolder API| RHDH
  ARGO -.->|cluster secrets\nauto-discovery| GF

  style HubCluster fill:#fce4ec,stroke:#c62828,stroke-width:2px
  style SpokeA fill:#e8f5e9,stroke:#2e7d32,stroke-width:1px
  style SpokeB fill:#e8f5e9,stroke:#2e7d32,stroke-width:1px
        

Hub-spoke architecture

flowchart TB
  subgraph Hub["Hub cluster"]
    GF["GateForge\n(Backend + Frontend)"]
    PG[("PostgreSQL\nplans + audit")]
    DG["Red Hat Data Grid\nFAQ + product cache"]
  end

  subgraph Sources["Multiple 3scale sources"]
    S1["3scale instance A\nAdmin API + CRDs"]
    S2["3scale instance B\nAdmin API + CRDs"]
    S3["3scale instance N\n..."]
  end

  subgraph Targets["Target clusters"]
    C1["OpenShift cluster 1\nConnectivity Link"]
    C2["OpenShift cluster 2\nConnectivity Link"]
    CN["OpenShift cluster N\n..."]
  end

  GF --> PG
  GF --> DG
  GF --> S1
  GF --> S2
  GF --> S3
  GF --> C1
  GF --> C2
  GF --> CN

  style Hub fill:#fce4ec,stroke:#c62828,stroke-width:2px
  style Sources fill:#fff3e0,stroke:#e65100,stroke-width:1px
  style Targets fill:#e8f5e9,stroke:#2e7d32,stroke-width:1px
        

Chat request path

flowchart LR
  A["User POST /api/chat"] --> B["Normalize input"]
  B --> C{"FAQ cache hit?\n(Data Grid)"}
  C -->|Yes| R["Return cached answer"]
  C -->|No| D["Build context:\n3scale products,\ncluster status,\nkuadrantctl version"]
  D --> E["Inject context\ninto user message"]
  E --> F["LLM chat completion\n(OpenAI-compatible)"]
  F --> G["Strip <redacted_thinking> blocks\nfrom reasoning models"]
  G --> H["Response to client"]

  style C fill:#e3f2fd,stroke:#1565c0
  style F fill:#fff3e0,stroke:#e65100
        

kuadrantctl in the migration pipeline

flowchart TD
  OAS["OpenAPI spec\n(fetched or synthetic)"] --> KH["kuadrantctl generate\nhttproute --oas -"]
  KH -->|success| PP["Post-process:\nnamespace, gateway, labels"]
  KH -->|failure| FB["Fallback:\nJava template generation"]
  PP --> RL{"Rules > 16?\nGateway API limit"}
  RL -->|yes| CO["Consolidate\nprefix matches"]
  RL -->|no| JV["Java builds\nAuthPolicy + RateLimitPolicy"]
  CO --> JV
  FB --> JV
  JV --> AI["AI verification\nof generated plan"]

  style KH fill:#e3f2fd,stroke:#1565c0
  style JV fill:#fff3e0,stroke:#e65100
  style FB fill:#ffebee,stroke:#c62828