Architecture

Capability map

A capability is a stable statement of what the platform does, so it survives refactoring. Nine of them cover APIHUB, broken down into 60 sub-capabilities. Switch on the technology overlay and the map becomes a functional-technical view: every entry names the service that implements it.

Nine capabilities, three tiers

Core

The reason the product exists
C1

API Catalog Management

Own the registry of workspaces, packages and versions

6 sub-capabilities

C2

API Publishing & Build

Turn uploaded sources into normalized, indexed API versions

7 sub-capabilities

C3

API Change Management

Understand what changed between versions and how risky it is

6 sub-capabilities

C4

API Documentation & Consumption

Let consumers read, try and export APIs

7 sub-capabilities

C5

API Quality & Governance

Enforce standards and measure API quality

7 sub-capabilities

C6

API Discovery (runtime)

Find APIs running in Kubernetes and bring them into the catalog

6 sub-capabilities

Differentiating

Rare in an API registry
C7

AI & Ecosystem Integration

Expose the catalog to AI tools and manage non-API contracts

8 sub-capabilities

Supporting

Needed to operate
C8

Identity & Access

Authenticate users, machines and agents; authorize actions

6 sub-capabilities

C9

Platform Operations

Run, scale, observe and maintain the platform

7 sub-capabilities

All 60 sub-capabilities

The full functional picture. The two overlays are the point of this map: one tells you which container to open when you need to change something, the other tells you how much production history that area has.

APIHUB Backend APIHUB UI TypeScript libraries Build Task Consumer API Linter Service Agents Backend APIHUB Agent Platform / Helm Java Task Consumer Design only
C1

API Catalog Management

6
  • C1.1 Workspace / group / package hierarchy

    BE + UI Core / mature

    PackageService, go-pg, Portal catalog pages

  • C1.2 Version & revision lifecycle

    BE + UI Core / mature

    VersionService / PublishedService, status promotion, revisions

  • C1.3 Dashboards & references

    BE + UI Core / mature

    Dashboard packages, version references, recursive resolution

  • C1.4 Search & navigation

    BE + UI Core / mature

    SearchController v3/v4, PostgreSQL full-text

  • C1.5 Favorites & activity history

    BE + UI Core / mature

    ActivityTracking, favorites, publish history

  • C1.6 Soft delete & transitions

    BE Core / mature

    TransitionService, soft-deleted cleanup, package move

C2

API Publishing & Build

7
  • C2.1 Publish via UI / REST / CI

    BE + UI Core / mature

    PublishController, api-key / PAT auth, ZIP or multipart sources

  • C2.2 Build task queue & workers

    BE + BTC Core / mature

    BuildService DB queue, RegistryService polling, N stateless replicas

  • C2.3 Parsing & type detection

    BTC + LIB Core / mature

    PackageVersionBuilder, 7 ApiBuilders, resolveSpec()

  • C2.4 Normalization

    BTC + LIB Core / mature

    api-unifier RULES per SpecType, $ref resolution, allOf merge

  • C2.5 Operation extraction & indexing

    BTC + BE Core / mature

    buildOperations, build-result-index, BuildResultService

  • C2.6 Document groups & transformations

    BE + BTC Evolving

    TransformationService, merged / reduced specs, prefix groups

  • C2.7 Java API builds

    JTC Planned / partial

    jdiff-engine, japicmp, jdeps; backend java-builders queue pending

C3

API Change Management

6
  • C3.1 Version & operation comparison

    BTC + LIB + BE Core / mature

    api-diff COMPARE_ENGINES_MAP, ComparisonService, compare pages

  • C3.2 Change classification

    LIB Core / mature

    breaking / risky / non-breaking / semi-breaking / annotation / deprecated

  • C3.3 Changelog & summaries

    BTC + BE + UI Core / mature

    ChangelogStrategy, changes/summary endpoints, export of changes

  • C3.4 Backward-compatibility validation

    BTC + LIB Evolving

    components/compare/*.bwc.validation (rest, graphql, async, ddl)

  • C3.5 Deprecation tracking

    BE + UI + LIB Core / mature

    deprecated items per operation, deprecated summaries

  • C3.6 Contract diff (DDL, Java)

    LIB + JTC New (2026)

    compareDdlApi (ddlapi-1.0); ApiDiffPipeline for jars (planned)

C4

API Documentation & Consumption

7
  • C4.1 Operation documentation rendering

    UI + LIB Core / mature

    <apispec-view>, <operation-view>, api-doc-viewer

  • C4.2 Schema & model views

    UI + LIB Core / mature

    JsonSchemaViewer, GraphQLOperationViewer, api-data-model trees

  • C4.3 Class / UML diagrams

    UI + LIB Core / mature

    <class-view-component> (D3 + ELK)

  • C4.4 Interactive playground

    UI + BE + LIB Core / mature

    <rest-playground>, PlaygroundProxyController, allowed hosts

  • C4.5 Markdown & text documents

    UI + BTC Core / mature

    textApiBuilder, MarkdownViewer with Mermaid

  • C4.6 Export (HTML, xlsx, ZIP)

    BE + BTC Evolving

    ExportService / ExcelService (excelize), export strategies, templates

  • C4.7 Document shareability

    BE + UI New (2026)

    shareability flags, bulk update, shareability report xlsx

C5

API Quality & Governance

7
  • C5.1 Specification linting

    LNT Core / mature

    SpectralExecutor (bundled CLI), Olric event trigger

  • C5.2 AI-assisted linting

    LNT Evolving

    AIOasExecutor, OpenAI-compatible LLM, rate limits

  • C5.3 Ruleset management

    LNT + UI Core / mature

    RulesetService CRUD / activation, Portal settings

  • C5.4 Version quality scoring

    LNT + UI New (2026)

    ScoringService, api-quality page

  • C5.5 Bulk validation

    LNT Evolving

    bulkValidation jobs

  • C5.6 Operation groups & tagging

    BE + UI Core / mature

    OperationGroupService, groups per apiType, templates

  • C5.7 Release readiness & statuses

    BE + UI Core / mature

    version statuses (draft/release/archived), promote permissions

C6

API Discovery (runtime)

6
  • C6.1 Agent registration & health

    AGT + ABE Core / mature

    RegistrationService heartbeat ~30 s, AgentService registry

  • C6.2 Namespace & service discovery

    AGT Core / mature

    CloudService (client-go), caches, workspace-scoped v2/v3 APIs

  • C6.3 Specification probing

    AGT Core / mature

    DiscoveryRunners: REST, GraphQL, AsyncAPI, Markdown, JSON Schema, generic

  • C6.4 Snapshots & promotion to Portal

    ABE + BE Core / mature

    SnapshotService → publish dashboard versions

  • C6.5 Namespace security checks

    ABE + AGT Evolving

    NamespaceSecurityService auth-check, Excel report

  • C6.6 Service proxy

    ABE + AGT Core / mature

    proxy controllers, ServiceProxy to in-cluster services

C7

AI & Ecosystem Integration

8
  • C7.1 MCP server (catalog tools)

    BE Evolving

    mcp-go Streamable HTTP, search / spec / diff / document tools, resources, prompts

  • C7.2 AI chat assistant

    BE + UI New (2026)

    AiChatTurnService, openai-go, SSE, tool loop, ephemeral files

  • C7.3 IDS document authoring

    BE New (2026)

    IDS authoring kit prompt + chat tools (MCP assets)

  • C7.4 MCP catalog contracts

    BE + BTC + UI New (2026)

    mcpBuilder, MCPContractController, Contracts tab

  • C7.5 DDL (database) contracts

    BE + BTC + LIB + UI New (2026)

    ddlBuilder, ddlapi-1.0 SpecType, DDLContractController

  • C7.6 Linter MCP endpoint

    LNT New (2026)

    list_linter_issues_for_package_version

  • C7.7 CLI & local MCP tooling

    LIB Evolving

    aux-tools/apihub-api-diff CLI + MCP subcommand

  • C7.8 API gateway sync (Tyk)

    design only Planned / partial

    qubership-apihub-tyk-adapter — design only

C8

Identity & Access

6
  • C8.1 SSO authentication

    BE Core / mature

    SAML 2.0 (crewjam), OIDC (go-oidc), IDPManager, LDAP lookup

  • C8.2 Local accounts & sessions

    BE Core / mature

    local auth (non-prod), JWT access + refresh, cookie / bearer

  • C8.3 API keys & personal access tokens

    BE + UI Core / mature

    ApihubApiKeyService, PersonalAccessTokenService, scopes

  • C8.4 Role-based access control

    BE + UI Core / mature

    RoleService: system, package, custom roles; permissions API

  • C8.5 Token propagation to satellites

    LNT + ABE + AGT Core / mature

    JWT public key validation, api-key / PAT strategies in each service

  • C8.6 User & admin management

    BE + UI Core / mature

    UserController, SysAdminController, avatars, zero-day admin

C9

Platform Operations

7
  • C9.1 Deployment & configuration

    OPS Core / mature

    Helm chart, values.yaml, config.yaml per service, docker-compose variants

  • C9.2 Data storage

    BE + LNT + ABE Core / mature

    PostgreSQL per service, optional S3 / MinIO cold storage

  • C9.3 Distributed cache & events

    BE + LNT Core / mature

    Olric embedded (cache, locks, DTopic version-published)

  • C9.4 Scheduled maintenance

    BE + LNT + ABE Core / mature

    robfig/cron cleanup jobs, VACUUM, ephemeral files, chat retention

  • C9.5 Schema & data migrations

    BE + LNT + ABE Core / mature

    migration framework, operations migration FSM

  • C9.6 Observability

    BE + OPS Evolving

    Prometheus metrics, ServiceMonitor, Grafana dashboards, business metrics

  • C9.7 CI/CD & E2E testing

    OPS Core / mature

    qubership-apihub-ci workflows, Newman, Playwright, screenshot tests

Where the weight sits

Sub-capabilities per container

  • APIHUB Backend 34
  • APIHUB UI 24
  • TypeScript libraries 13
  • Build Task Consumer 12
  • API Linter Service 11
  • Agents Backend 8
  • APIHUB Agent 6
  • Platform / Helm 3
  • Java Task Consumer 2

Maturity across all sixty

  • Core / mature 41

    Stable for several releases, full test coverage (E2E, Newman / Playwright)

  • Evolving 9

    Actively changed in 2026 (new endpoints, renamed tools, partial coverage)

  • New (2026) 8

    Landed in the last release cycle; limited production history

  • Planned / partial 2

    Specified or partially implemented; not usable end-to-end yet

Cross-check — capability × container, bubble size is the number of sub-capabilities
Bubble matrix of the nine APIHUB capabilities against the nine containers, sized by the number of contributing sub-capabilities

The backend appears in 34 of the 60 sub-capabilities and the UI in 24. The micro-monolith shape is visible here, and it is the main argument for any future split.

The same model in ArchiMate

For readers who need to import this into an enterprise-architecture repository: business services on top, application services and components in the middle, technology underneath. Realization runs upward.

ArchiMate view — four layers, realization running upward
The APIHUB model expressed as four ArchiMate layers: business, application services, application components and technology