Proposal: Adopting Backstage.io as a Developer Portal for FOLIO

Overview

FOLIO is a large, distributed, open-source library services platform composed of dozens of independently maintained modules across frontend (Stripes) and backend (FOLIO Spring Base, RMB). As the ecosystem grows, discoverability, onboarding, and service ownership become significant friction points for contributors and integrators alike.

This proposal recommends adopting Backstage.io — an open-source developer portal framework created by Spotify — as the central hub for the FOLIO developer experience.

What is Backstage.io?

Backstage is a framework for building internal developer portals. Its core features include:

• Software Catalog — a centralized registry of all services, libraries, APIs, and tools

• TechDocs — docs-as-code integrated into the catalog

• Scaffolder — self-service templates for creating new modules/services

• API Docs — built-in rendering of OpenAPI, AsyncAPI, GraphQL, and custom API specifications

• Dependency Graph — visual map of relationships between services and the APIs they consume or provide

• Plugins — extensible integrations with GitHub, Jira, CI/CD pipelines, observability tools, and more

Why Backstage Fits FOLIO

1. Taming Module Sprawl

FOLIO has 150+ modules hosted under the folio-org GitHub organization. Backstage's Software Catalog can index all of them via catalog-info.yaml descriptors, giving every developer a single searchable view of the ecosystem — with ownership, lifecycle status, API contracts, and links to docs.

2. Ownership and Accountability

Today, identifying who owns a given module requires tribal knowledge or hunting through GitHub. Backstage enforces explicit ownership metadata, enabling automated alerts, incident routing, and clearer contribution pathways.

3. API Documentation in One Place

Backstage has first-class support for API documentation. Each FOLIO module can expose its OpenAPI spec directly in the catalog, rendered as a browsable, interactive UI. This means:

• Developers no longer need to hunt across GitHub repos or raw JSON to find endpoint definitions

• API docs are versioned alongside the module and always in sync with the catalog

• Non-technical stakeholders (product owners, integrators) can browse available APIs without developer assistance

FOLIO Module Descriptors already define endpoints, permissions — a custom ingestion plugin could auto-generate these API doc entries combining them with RAML/OpenAPI specs.

4. API Dependency Checking and Impact Analysis

FOLIO's Module Descriptors define explicit provides and requires interface contracts. Backstage can consume this metadata to build a live dependency graph across the entire module ecosystem. This unlocks:

• Visual dependency maps — see at a glance which modules depend on a given interface

• Breaking change impact analysis — before releasing a new interface version, identify every downstream consumer

• Circular dependency detection — surface hidden coupling between modules that may cause upgrade issues

• Interface compatibility checks — validate that the version of an interface a module requires is satisfied by available providers in a given installation

This is especially valuable during FOLIO flower release planning, where coordinating upgrades across dozens of interdependent modules is a manual and error-prone process today.

5. Onboarding New Contributors

New developers joining FOLIO face a steep learning curve. Backstage's TechDocs and Scaffolder can consolidate onboarding guides and provide self-service templates (e.g., "Create a new RMB module", "Create a new Stripes UI plugin") that encode best practices and reduce setup time from days to minutes.

6. Unified Search Across the Ecosystem

Documentation is currently scattered across GitHub READMEs, GitHub Wiki, Confluence, and FOLIO Wiki. Backstage's search can federate across all these sources, surfacing relevant content from one entry point.

7. Open Source and Community-Aligned

Backstage is Apache 2.0 licensed and maintained by a large community including Spotify, American Airlines, Expedia, and hundreds of other organizations. It aligns well with FOLIO's open-source ethos and can be self-hosted under the Open Library Foundation.

Proposed Phased Rollout

Considerations and Risks

• Maintenance overhead — Backstage requires a Node.js deployment and periodic upgrades; a dedicated working group would be needed.

• Adoption — Catalog metadata (catalog-info.yaml) must be added to each module repo; this is mechanical but requires community buy-in.

• Custom plugin development — The FOLIO Module Descriptor plugin (for API docs and dependency graph ingestion) would need to be built by the community, representing the largest upfront investment.

Recommendation

Begin with a proof-of-concept cataloging the top 30 most-used FOLIO modules with their API specs and dependency relationships, hosted on a shared environment, to demonstrate value before full community commitment.