Fediversity

Feature Specification: Applications catalog

Created: 2026-09-22

Status: Implemented

Input: Reconstructed from the catalog of core at 0bf4ecd36, commit 8f22117c6 (rename of the data-model catalog to components), and api/specification.md.

User Scenarios & Testing (mandatory)

User Story 1 - Show the applications an operator can use (Priority: P1)

A front end shows the applications of a deployment with a title, a description, a link to the project and an icon. It gets these from one catalog that core builds, and does not keep its own list. The catalog also lists each supporting component that has a UI, so the operator can find that UI.

Why this priority: without the catalog, each front end keeps a copy of the names and artwork, and the copies go out of date when a component is added.

Independent Test: a check that builds the catalog. The index has one entry per configurable component, and each icon that an entry names is in the output.

Acceptance Scenarios:

  1. Given a configurable component, When the catalog is built, Then the index has an entry for it.
  2. Given a supporting component that has a UI subdomain, When the catalog is built, Then the index has an entry for it.
  3. Given a component that is not configurable and has no UI subdomain, When the catalog is built, Then the index has no entry for it.

User Story 2 - Take the facts from the project itself (Priority: P2)

The description, the homepage and the icon of an application come from the package of the component and from the source of the project. When that source has no icon, the icon comes from another repository of the same project, at a pinned version. The repository does not store copies of them.

Independent Test: change the description in the metadata of a package in a test module. The catalog entry shows the new description.

Edge Cases

  • A component has no icon. Its entry has no icon, and the catalog still builds.
  • A front end folds extra components into the group. The catalog includes them when they match the membership rule.
  • The index names no component. The check fails.

Requirements (mandatory)

Functional Requirements

  • FR-001: The catalog MUST have an entry for each component that is configurable or has a UI subdomain, and for no other component.
  • FR-002: Each entry MUST have the title, description, homepage, the optional and configurable flags, the UI subdomain and the icon of the component.
  • FR-003: The catalog MUST take the metadata from the package of the component, and the icon from the source of the project or, when that source has no icon, from a pinned repository of the project.
  • FR-004: Each icon that an entry names MUST be in the catalog output.
  • FR-005: The catalog MUST accept the extra modules of a front end, the same as the data model.

Key Entities

  • Catalog index: the list of entries, keyed by component name.
  • Catalog entry: how one component is shown.
  • Icon: an SVG file from the source of the project.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: A new operator-facing component shows in the catalog with no change to the catalog code.
  • SC-002: The catalog check passes.

Assumptions

  • api serves the catalog and its icons. This specification describes only what core builds.

Known Deviations

None.