Fediversity

Feature Specification: Applications Catalog

Created: 2026-09-22

Status: Implemented

Input: Reconstructed from the code at 0bf4ecd36 (core/applications-catalog.nix, core/checks/applications-catalog.nix, core/lib/data-model.nix), 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 name, 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.

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: build the applications-catalog package. The index share/fediversity/components.json has one entry per configurable component, and every icon that an entry names is in the output.

Acceptance Scenarios:

  1. Given a component with configurable = true, When the catalog is built, Then the index has an entry for it with title, description, homepage, optional, configurable, uiSubdomain and icon.
  2. Given a supporting component that has a UI subdomain, When the catalog is built, Then the index has an entry for it, so the operator can find its UI.
  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 that project. When the source of the package has no icon, the icon comes from another repository of the same project, pinned with npins. 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 icon = null, 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 title, description, homepage, optional, configurable, uiSubdomain and icon.
  • FR-003: The catalog MUST take the metadata from the package of the component and the icon from the source of the project, or from another repository of the project that npins pins when that source has no icon.
  • 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: share/fediversity/components.json, 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 applications-catalog check passes.

Assumptions

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

Known Deviations

None.