Table of Contents

The Platform Console’s Catalog is similar to a library catalog, in that it provides a list of people, teams, apps, services, APIs, forms, and infrastructure resources. These resources are known as “entities” in Backstage (the platform the Console is built on).

Through the Catalog, users can conceptualize and navigate the VA.gov ecosystem. The Catalog can connect to GitHub (and other code hosts) to display a page for every user, team, system, API, microservice, web app, form, or infrastructure resource.

The teams responsible for these entities can customize the pages with dependencies, links, monitoring tools, documentation, and more.

See example Catalog pages below (click an image to enlarge it):

View of the top portion of a team page on Catalog

Catalog team page (top)

View of the bottom portion of a team page on Catalog

Catalog team page (bottom)

View of a Component page on Catalog

Component* page

*See Entity Types in the Catalog (below) for a definition of Components.

Example list of components in Catalog

List of Components* (parts of vets-website)

Entity Types in the Catalog

The Catalog has eight (8) entity types, which can be navigated to via a submenu:

Catalog submenu on the Platform Console

Catalog submenu (click to enlarge)

Definition

Examples

Domain

A collection of systems with a common purpose or context

  • Platform

  • VFS

System

A collection of components or APIs with common purpose or context

Component

A software component or “unit of software”, typically linked to the source code that constitutes the component

Not to be confused with Design System components.

  • 10-10CG application

  • VA Profile

  • Facility Locator

API

Typically a functional portion of vets-api, but also includes external services

  • VA Notify API

  • Appeals API

Resource

A piece of infrastructure a system needs to operate

  • Amazon EKS

  • Amazon S3

Template

A Catalog entry that defines (1) the parameters that are rendered in the front end part of the scaffolding wizard, and (2) the steps that are executed when scaffolding a component. Used with the “Software Template” system

  • Create VFS App in vets-website repo

Group

A GitHub team made up of GitHub users

  • VFS VAOS

User

A GitHub user in the VA org

Information Displayed on Entity Pages

Each entity page (except Group and User pages) has multiple tabs along the top. Here is what you can find under each tab:

Overview Tab

The overview tab has overall information about the entity, such as a description, relationships to other entities, and links related to the entity.

About Card

The overview tab has an About card that includes the following:

  • A link to the entity’s source code repo (“VIEW SOURCE”)

  • A link to the entity’s technical documentation (“VIEW TECHDOCS”)

  • A description of the entity

  • The entity’s owner, system, type, lifecycle, and tags (such as programming language)

Screenshot of About card in Entity page. Includes a description, information about the owner, system, type, and lifecycle of the entity, link to GitHub source code, and a link to documentation via Tech Docs

About card in Entity page

Relations Card

The overview tab has a Relations graph that can show relationships to other entities, such as

  • Owned by / Owner of

  • Has part / Part of

  • Depends on / Dependency of

  • Has member / Member of

  • Consumes API / API Consumed By

Example Relations graph for the 10-10CG component, showing that it is owned by the VSA Caregiver Frontend group, is part of VA.gov, and consumes the Form 10-10CG API and Vets Virus Scan API

Example Relations graph for the 10-10CG component

It also links to a graph of the entire Catalog where a user can navigate the parts and relationships of the VA ecosystem and Shift+Click to see the Catalog page for any entity. The graph can also be filtered to show only certain types of relationships or entities.

Screenshot of relations graph in Catalog entry. Shows team, what the team has ownership over, consumes, or is consumed by.

Catalog Graph

Links Card

The overview tab has a Links card that can be customized to include links to anything related to the entity, such as analytics reports, monitoring tools, or anything else with a URL.

Subcomponents Card

If a component has multiple subparts, they will be listed in the Subcomponents card on the overview tab.

CI/CD Tab

This tab has a list of recent CI/CD jobs in GitHub actions.

Screen shot of recent CI CD jobs in GitHub actions for platform-console-ui team

CI/CD tab

Feature Toggles

This tab shows feature toggles for the entity. Users can see the status and go to Flipper to make changes.

Scorecards

This tab shows how complete a Catalog entry is. It checks to see if the entity’s page has a title, an owner, a link to technical documentation, and a GitHub annotation.

Creating and Updating Catalog Entity Pages

Entity pages are created via catalog-info.yaml and other metadata files that tell the Console what information to display for a given entity, including:

  • Its source code repository

  • Its relationships to other entities (e.g., dependencies)

  • Links related to the entity

  • Configuration for tools found in the entity page tabs

These catalog-info.yaml files are usually stored in an entity’s GitHub repo.

For most APIs and components (parts of vets-api and vets-website), catalog-info.yaml files have already been generated in GitHub repos to create basic pages in the Catalog. It is the responsibility of individual teams make sure their entities' catalog-info.yaml files are correct, complete, and up to date.

Instructions for creating and updating Catalog entity pages can be viewed in the Console’s documentation viewer (Docs > Tech Docs > Platform Console UI > Users > Building a Catalog Entry) or in GitHub.

Connecting Technical Documentation to Entity Pages

Once an entity’s catalog-info.yaml file is complete, a user can click View Tech Docs (or open the DOCS tab) to read documentation from the entity’s repository. Users may use the Tech Docs plugin to configure their documentation.

Instructions for setting up Tech Docs for an entity can be found in the Console (Docs > Tech Docs > Platform Console UI > Users > Setting up Technical Documentation) or in GitHub.

Screenshot of TechDocs documentation viewer in Console

The TechDocs documentation viewer

Customizing Team Pages

Entity pages for teams (“Groups” in the Catalog) can also be customized with links that are relevant to the team. Instructions for updating team pages can be found in the Console (Docs > Tech Docs > Platform Console UI > Users > Customizing your team's catalog page) or in GitHub.