bsv - Backstage Entity Visualizer

A terminal UI application for exploring and visualizing Backstage software catalog entities.

Features

• Tree View: Hierarchical visualization of entities organized by Domain → System → Component
• Entity Details: View metadata, ownership, lifecycle, tags, links, annotations, and source file information
• Group Hierarchy: Display group parent/child relationships and member lists for organizational structure
• Schema Validation: Automatically validates entities against the official Backstage JSON Schema
• Relationship Graph: Visualize how entities relate to each other (dependencies, APIs, ownership)
• Documentation Browser: View TechDocs and ADR markdown files directly in the terminal
• Reference Validation: Highlights missing or invalid entity references
• Search: Filter entities by name with / search
• Live Reload: Refresh catalog data without restarting

Installation

From Source

# Clone the repository
git clone https://github.com/yourusername/bsv.git
cd bsv

# Build and install
cargo install --path .

Requirements

• Rust 1.70 or later

Usage

# Scan current directory for catalog-info.yaml files
bsv

# Scan a specific directory
bsv /path/to/backstage/catalog

# Load a specific catalog file
bsv /path/to/catalog-info.yaml

Keyboard Shortcuts

Main View

Key	Action
↑ / k	Move up
↓ / j	Move down
← / h	Collapse node
→ / l / Enter	Expand node
e	Expand all nodes
/	Start search
Esc	Clear search / Cancel
g	Toggle graph view
d	Open documentation browser (when available)
r	Reload catalog
q	Quit

Documentation Browser

Key	Action
↑ / k	Navigate up / Scroll up
↓ / j	Navigate down / Scroll down
Enter	Open selected file
PgUp / PgDn	Page scroll
Esc	Back to file list / Close browser
q	Quit

Supported Entity Types

bsv supports all standard Backstage entity types:

• Component - Individual software components (services, websites, libraries)
• API - API definitions (REST, GraphQL, gRPC)
• Resource - Infrastructure resources (databases, storage, queues)
• System - Collection of related components and APIs
• Domain - Business domain grouping systems
• Group - Teams and organizational units
• User - Individual team members
• Location - Catalog file locations

Entity Reference Format

Backstage uses a specific format for entity references:

[<kind>:][<namespace>/]<name>

Examples:

• component:default/my-service - Fully qualified
• my-service - Name only (kind and namespace inferred from context)
• group:platform-team - Kind specified, namespace inferred

bsv displays inferred parts in [brackets] with dim styling to distinguish them from explicitly specified values.

Reference Validation

bsv validates entity references and provides visual feedback:

• Green: Reference exists in catalog
• Yellow: Reference not found (might be external or missing)
• Red: Unknown entity kind

Schema Validation

bsv automatically validates all entities against the official Backstage catalog JSON Schema. Validation errors are displayed:

• In the tree view: Entities with validation errors are shown in red with a ⚠ indicator and error count
• In the details panel: Full validation error details including field path and error message

Common validation errors include:

• Missing required fields (e.g., owner, lifecycle, type for Components)
• Invalid field types or values
• Missing apiVersion or kind
• Empty or invalid entity names

This helps ensure your catalog files comply with Backstage standards before deployment.

Catalog File Format

bsv reads standard Backstage catalog-info.yaml files:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-service
  title: My Service
  description: A microservice that does things
  tags:
    - python
    - backend
spec:
  type: service
  lifecycle: production
  owner: group:platform-team
  system: my-system
  dependsOn:
    - component:other-service
  providesApis:
    - my-api

Multiple entities can be defined in a single file using YAML document separators (---).

Development

# Run in development mode
cargo run

# Run with a test catalog
cargo run -- testdata/large-catalog.yaml

# Run tests
cargo test

# Check for linting issues
cargo clippy

# Format code
cargo fmt

Documentation Browser

bsv can browse TechDocs and ADR documentation directly in the terminal. When an entity has documentation annotations, press d to open the documentation browser.

Supported Annotations

• backstage.io/techdocs-ref: TechDocs reference (e.g., dir:. or dir:./docs)
• backstage.io/adr-location: ADR location (e.g., docs/adr)

The browser provides:

• File list navigation for markdown files
• Basic markdown syntax highlighting (headers, lists, code blocks, links)
• Scrollable document viewing

Project Structure

src/
├── main.rs      # Entry point and event loop
├── app.rs       # Application state management
├── docs.rs      # Documentation browser and TechDocs/ADR support
├── entity.rs    # Entity types and reference parsing
├── parser.rs    # YAML file discovery and parsing
├── tree.rs      # Tree data structure
├── graph.rs     # Relationship graph extraction
├── validator.rs # JSON Schema validation
└── ui.rs        # Terminal UI rendering

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.