I want to build an internal developer portal. What's a good foundation for a software catalog and documentation that's not Backstage?

If you want the benefits of an Internal Developer Portal (IDP)—specifically a centralized software catalog and structured documentation—without the heavy maintenance tax, plugin hell, and TypeScript overhead of running raw Backstage, you have some fantastic commercial and native alternatives.

The right foundation depends on whether you want a fully managed SaaS developer portal or a native extension of tools you already use.

1. Dedicated Managed Developer Portals (SaaS)

If your goal is to avoid running an infrastructure project just to track your microservices and docs, these platforms provide out-of-the-box software catalogs, scorecards, and action templates:

• Port : Highly praised for its infinitely flexible data model. Unlike Backstage, which forces you into its rigid Kind: Component / API / Resource entity framework, Port lets you define custom data blueprints using low-code/config schemas. It handles software catalogs, scorecards, and self-service actions exceptionally well.
• OpsLevel : Exceptional if your primary driver is service maturity, ownership, and operational readiness. It features a clean catalog, powerful microservice scorecards, and rubrics that make it straightforward to track who owns what and whether services meet security/production readiness standards.
• Cortex : Leans heavily into engineering scorecards, quality tracking, and automated action initiatives. It has robust catalog capabilities and great integrations out of the box without requiring custom React plugin development.

2. Ecosystem-Native Catalogs

If you are already deeply embedded in a specific vendor ecosystem, using their native catalog keeps maintenance near zero:

• Atlassian Compass : Atlassian's dedicated developer experience platform. It acts as a decentralized catalog for your microservices, deeply tied into Jira, Bitbucket, Confluence, and external CI/CD tools. If your engineering org lives in Jira, Compass provides a seamless catalog and component-level documentation tracking without spinning up a separate IDP stack.

3. The "Managed Backstage" Route (If you like Backstage features, but not the ops)

• Roadie : Roadie gives you pure, vanilla Backstage hosted and managed entirely as a SaaS product. You get the entire Backstage plugin ecosystem and software catalog standard without having to manage the Node.js backend, upgrades, or database migrations yourself.

To help narrow down the ideal foundation for your team, let me know:

• Are you looking strictly for open-source/self-hosted options, or is SaaS/managed on the table?
• What core toolchain do you rely on most today (e.g., GitHub, GitLab, Jira, Kubernetes)?

Yes. If you specifically want “Backstage without Backstage”, I’d separate the problem into two layers:

1. A durable software catalog/data model — services, APIs, teams, owners, repos, environments, dependencies.
2. A documentation layer — Markdown/docs-as-code, API specs, runbooks, ADRs, architecture docs.

That gives you much more freedom than adopting another monolithic portal.

My preferred foundation

1. Use OpenAPI + Git + Markdown as the underlying source of truth

I would make repositories authoritative for most metadata:

# service.yaml
name: payments-api
type: service
owner: payments
lifecycle: production
repository: github.com/acme/payments
docs: /docs
apis:
  - payments-v1
depends_on:
  - postgres-payments
  - auth-service

Then have a small catalog service ingest these descriptors and enrich them from GitHub/GitLab, Kubernetes, cloud, CI/CD, observability, etc.

The important architectural decision is:

Don't make the portal UI the system of record. The portal should be a projection of engineering data, not the place where engineers manually maintain it.

This is one of the strongest ideas worth retaining from Backstage's model: its catalog covers services, APIs, resources, ownership, etc., while TechDocs uses a docs-as-code approach.

2. For documentation, use a dedicated docs engine

I'd strongly consider:

• MkDocs + Material — excellent if you want simple Markdown/docs-as-code.
• Docusaurus — better if you want a more application-like documentation site.
• GitBook — if you prioritize ease of authoring over Git-native workflows.
• Mintlify — particularly attractive for API/developer-facing documentation.

Your portal can simply associate:

Service
 ├── Repository
 ├── Owner
 ├── APIs
 ├── Dependencies
 ├── Deployments
 ├── Dashboards
 └── Documentation → docs site

You don't need the portal itself to be the documentation system.

If you want an actual off-the-shelf portal

I'd shortlist these:

For example, opslevel.com now positions its catalog as the foundation of an internal developer portal, with automatic discovery, ownership, documentation, integrations, and service relationships.

cortex.io is particularly interesting if you want the catalog to evolve into engineering standards and scorecards rather than merely being a directory. Cortex itself emphasizes that its SaaS approach avoids the integration/plugin maintenance associated with building on Backstage.

But I'd seriously consider building a thin catalog yourself

If your requirements are primarily:

“I want to find every service, know who owns it, understand dependencies, and get to its docs.” …I wouldn't necessarily buy or deploy a full IDP.

A surprisingly good architecture is:

                  ┌───────────────────┐
                  │     Git repos     │
                  │ service.yaml      │
                  │ OpenAPI           │
                  │ Markdown docs     │
                  └─────────┬─────────┘
                            │
                  ┌─────────▼─────────┐
                  │   Catalog ingest  │
                  │                   │
                  │ GitHub/GitLab      │
                  │ Kubernetes        │
                  │ AWS/GCP/Azure     │
                  │ CI/CD             │
                  │ PagerDuty/etc.    │
                  └─────────┬─────────┘
                            │
                    ┌───────▼───────┐
                    │ Catalog DB    │
                    │               │
                    │ Services      │
                    │ Teams         │
                    │ APIs          │
                    │ Resources     │
                    │ Dependencies  │
                    └───────┬───────┘
                            │
             ┌──────────────┼──────────────┐
             ▼              ▼              ▼
        Portal UI       Docs search    Automation

You could implement the catalog API with PostgreSQL and expose a simple GraphQL/REST API. The UI can be almost embarrassingly simple initially.

The hard part isn't displaying services. It's keeping ownership, relationships and status accurate.

That's why I'd spend more effort on ingestion/reconciliation than on the portal UI.

The data model I'd start with

Keep the initial model small:

Organization
 ├── Team
 │    └── Service
 │          ├── API
 │          ├── Repository
 │          ├── Environment
 │          ├── Resource
 │          ├── Dependency
 │          └── Documentation
 │
 └── Person

For every Service, I'd want at least:

id
name
description
owner
team
lifecycle
repository
documentation
source
created_at
updated_at

Then relationships:

service → service
service → API
service → database
service → queue
service → cloud resource
service → team
service → repository

And critically, metadata should have provenance:

owner:
  value: payments-team
  source: github-codeowners
  confidence: high
  last_verified: 2026-08-29

That makes automated catalog maintenance possible.

What I'd avoid

I wouldn't start by building:

• a giant plugin framework
• a custom documentation editor
• a custom wiki
• a custom search engine
• manually maintained service records
• a portal-specific YAML format for everything
• 30 integrations

Those are how you accidentally recreate Backstage.

Instead, build a catalog API + reconciliation engine + thin UI, and let existing systems remain authoritative.

My recommendation

If you're buying, I'd evaluate Port, Cortex, and OpsLevel.

If you're building, I'd use:

Postgres + Git-based metadata + OpenAPI + Markdown/MkDocs + a small catalog API + integrations/reconciliation + a very thin React/Next.js UI.

That gives you the most important part of Backstage—the software catalog as a common engineering graph—without committing yourself to Backstage's framework/plugin architecture.

And if you tell me your stack (e.g. GitHub + Kubernetes + AWS + Terraform + Datadog) and roughly how many services/engineers you have, I can sketch a concrete architecture and data model for this approach.

…I wouldn't necessarily buy or deploy a full IDP.

A surprisingly good architecture is:

                  ┌───────────────────┐
                  │     Git repos     │
                  │ service.yaml      │
                  │ OpenAPI           │
                  │ Markdown docs     │
                  └─────────┬─────────┘
                            │
                  ┌─────────▼─────────┐
                  │   Catalog ingest  │
                  │                   │
                  │ GitHub/GitLab      │
                  │ Kubernetes        │
                  │ AWS/GCP/Azure     │
                  │ CI/CD             │
                  │ PagerDuty/etc.    │
                  └─────────┬─────────┘
                            │
                    ┌───────▼───────┐
                    │ Catalog DB    │
                    │               │
                    │ Services      │
                    │ Teams         │
                    │ APIs          │
                    │ Resources     │
                    │ Dependencies  │
                    └───────┬───────┘
                            │
             ┌──────────────┼──────────────┐
             ▼              ▼              ▼
        Portal UI       Docs search    Automation

You could implement the catalog API with PostgreSQL and expose a simple GraphQL/REST API. The UI can be almost embarrassingly simple initially.

The hard part isn't displaying services. It's keeping ownership, relationships and status accurate.

That's why I'd spend more effort on ingestion/reconciliation than on the portal UI.

The data model I'd start with

Keep the initial model small:

Organization
 ├── Team
 │    └── Service
 │          ├── API
 │          ├── Repository
 │          ├── Environment
 │          ├── Resource
 │          ├── Dependency
 │          └── Documentation
 │
 └── Person

For every Service, I'd want at least:

id
name
description
owner
team
lifecycle
repository
documentation
source
created_at
updated_at

Then relationships:

service → service
service → API
service → database
service → queue
service → cloud resource
service → team
service → repository

And critically, metadata should have provenance:

owner:
  value: payments-team
  source: github-codeowners
  confidence: high
  last_verified: 2026-08-29

That makes automated catalog maintenance possible.

What I'd avoid

I wouldn't start by building:

• a giant plugin framework
• a custom documentation editor
• a custom wiki
• a custom search engine
• manually maintained service records
• a portal-specific YAML format for everything
• 30 integrations

Those are how you accidentally recreate Backstage.

Instead, build a catalog API + reconciliation engine + thin UI, and let existing systems remain authoritative.

My recommendation

If you're buying, I'd evaluate Port, Cortex, and OpsLevel.

If you're building, I'd use:

Postgres + Git-based metadata + OpenAPI + Markdown/MkDocs + a small catalog API + integrations/reconciliation + a very thin React/Next.js UI.

That gives you the most important part of Backstage—the software catalog as a common engineering graph—without committing yourself to Backstage's framework/plugin architecture.

And if you tell me your stack (e.g. GitHub + Kubernetes + AWS + Terraform + Datadog) and roughly how many services/engineers you have, I can sketch a concrete architecture and data model for this approach.

Yes. If you want a developer portal where the software catalog and docs are the foundation, but don't want to take on Backstage's framework/plugin/maintenance model, I'd look at these options:

*Port's current positioning is primarily SaaS.

My recommendation: Port + a dedicated docs system

If I were designing this from scratch today, I'd seriously consider Port as the catalog/control plane, rather than making the portal itself responsible for being the documentation system.

Port's catalog is deliberately modeled as a flexible data layer: you define entities/blueprints such as services, APIs, databases, teams, environments, etc., and relationships between them. It can ingest data from Git, CI/CD, Kubernetes, AWS, Terraform and APIs.

Then pair it with something like:

• GitBook — polished internal documentation experience.
• Confluence — especially sensible if you're already on Atlassian.
• Docusaurus — if you want docs-as-code and complete control.
• MkDocs — similarly simple docs-as-code approach.

The important architectural distinction is:

                    Developer Portal
                          │
             ┌────────────┴────────────┐
             │                         │
       Software Catalog            Documentation
             │                         │
            Port                 GitBook / Docusaurus
             │
      ┌──────┼────────┐
      │      │        │
    GitHub  K8s      AWS
      │      │        │
    CI/CD  Runtime   Cloud

That gives you a catalog as structured data, rather than treating documentation pages as the catalog.

Why I like this approach

The catalog should answer machine-readable questions like:

Who owns payments-api? What does it depend on? Where is its repository? What Kubernetes workloads implement it? What APIs does it expose? What's its production readiness? What documentation belongs to it? What's the on-call team? That's the same core problem Backstage's catalog is designed around: centralized metadata and ownership across services, libraries, data pipelines, etc.

But I'd avoid making your portal's database the source of truth.

Instead, make the catalog an aggregation/index layer:

GitHub ────────┐
               │
Kubernetes ────┤
               ├──> Catalog
AWS ───────────┤
               │
PagerDuty ─────┤
               │
Datadog ───────┘

Docs ───────────────> Documentation platform

Ownership should come from Git/IAM/team configuration where possible. Runtime information should come from Kubernetes/cloud APIs. Deployment information should come from CI/CD. Documentation should live with the thing that owns the documentation.

The portal then joins those things together.

When I'd choose something else

Choose Cortex if your primary goal is less "developer directory" and more engineering governance: service ownership, standards, production readiness, scorecards, and maturity. Its catalog/governance model is one of its strongest differentiators.

Choose OpsLevel if the catalog itself is the product you care most about and you want strong service ownership, maturity, and operational workflows around it.

Choose Roadie if what you really mean by "not Backstage" is "I don't want to operate a Backstage instance." Roadie retains the Backstage ecosystem while providing a managed experience.

Choose Atlassian Compass if your organization already lives in Jira/Confluence. The integration advantage can outweigh having a less neutral platform.

One thing I'd avoid

I wouldn't start by building your own Backstage-like portal.

Backstage is explicitly a framework for building an IDP, with the software catalog at its center and a plugin architecture around it.

That's powerful, but it means you're effectively signing up to build and maintain an internal product.

Instead, I'd build only the thin experience layer that makes your organization's data useful:

             ┌───────────────────────────┐
             │      Developer Portal      │
             │                           │
             │  Search · Catalog · Docs  │
             │  Ownership · Dependencies │
             │  Runbooks · Links         │
             └─────────────┬─────────────┘
                           │
                    ┌──────┴──────┐
                    │   Catalog   │
                    │   Port/API  │
                    └──────┬──────┘
                           │
       ┌──────────┬────────┼─────────┬─────────┐
       ↓          ↓        ↓         ↓         ↓
     GitHub      K8s      AWS       CI/CD    PagerDuty

If you tell me roughly your stack (GitHub/GitLab, Kubernetes or not, AWS/Azure/GCP, Confluence/GitBook/etc.) and whether self-hosting is a requirement, I can narrow this down to a concrete architecture and a 3–5 component stack.

If you love the idea of a centralized software catalog and documentation hub but want to avoid the heavy engineering tax, maintenance overhead, and plugin hell of running Backstage, you have some fantastic commercial and alternative paths.

The best foundation depends on whether you want a fully-managed SaaS control plane (that sets up in an hour) or a lighter, doc-first approach.

Phase 1: Fully-Managed SaaS Developer Portals (The "Buy" Alternatives)

If your goal is to skip managing a React/TypeScript monolith, these platforms provide out-of-the-box software catalogs, scorecards, and self-service actions.

• Port : Highly customizable and data-driven. Instead of enforcing Backstage’s rigid entity model, Port uses a flexible "blueprint" system where you define your own data models (microservices, data pipelines, AWS resources, cost centers). It acts as a real-time visual database with strong self-service capabilities. Explore it on the Port Documentation.
• Cortex : Excellent if you want a polished, opinionated product immediately. It features deep out-of-the-box integrations, automated scorecards for production readiness, and strong engineering intelligence (DORA metrics, cycle times). Check features via Cortex.
• OpsLevel : Known for being straightforward, developer-friendly, and hyper-focused on service maturity, microservice catalogs, and scorecards without unnecessary bloat. Learn more at OpsLevel.
• Roadie : If you actually like Backstage’s ecosystem plugins and catalog specs, but just refuse to host and maintain it , Roadie provides fully-managed Backstage-as-a-Service. Visit Roadie.

Phase 2: Documentation-First & Git-Centric Foundations (The Lightweight Route)

If your developers live in Markdown files and git repositories and you don't need heavy cloud orchestration day one, you can stitch together a gorgeous, low-maintenance portal using documentation platforms:

1. The Catalog Layer (Notion, Backstage-Lite, or Compass)
   • Atlassian Compass : A lightweight, extensible component catalog that integrates natively with Jira, Bitbucket, GitHub, and CI/CD pipelines. It gives you a service catalog and scorecards with a fraction of Backstage's configuration overhead. Explore it on Atlassian Compass.
   • Custom Git Metadata (YAML/JSON-schema) : Keep a service.yaml inside each repository. Use a simple internal script or CI job to ingest these into a lightweight database or search index (like Elasticsearch or Postgres) and build a tiny internal frontend for it.
2. The Documentation Layer (Docs-as-Code)
   • Backstage's TechDocs is nice, but you don't need Backstage to run a great docs-as-code platform.
   • MkDocs Material or Redocly / Stoplight (for APIs): Host documentation directly in the source repos, compiled automatically via CI/CD and published to a centralized portal (using tools like GitHub Pages, Vercel, or an internal S3 bucket).

Recommendation on How to Choose

• Choose Port if you have complex, custom enterprise assets and want a completely un-opinionated, highly malleable data graph.
• Choose Cortex or OpsLevel if you want instant maturity scorecodes and standard microservice tracking out-of-the-box with zero custom modeling.
• Choose Atlassian Compass if you are already deeply embedded in the Atlassian/Jira ecosystem.
• Choose Docs-as-Code (MkDocs/Stoplight) if your primary bottleneck is lack of structured documentation rather than lack of cloud resource tracking.

If you'd like to narrow this down, let me know:

• Are you looking for Open Source / Self-Hosted options or SaaS?
• How heavily do you rely on Kubernetes/Cloud infrastructure provisioning vs. just tracking services and docs?

If you want the core benefits of an internal developer portal—a searchable software catalog, rich documentation-as-code, and golden-path templates—without taking on the heavy TypeScript/React maintenance burden of self-hosting and upgrading Backstage , you have a few distinct paths: commercial no-code platforms, managed Backstage, native ecosystem portals, or lightweight documentation-first stacks.

1. The Commercial No-Code / Config-Driven Portals

If your goal is to configure a data model rather than write code for a React frontend, commercial portals let you define entities (services, APIs, resources) and build UI dashboards via configuration.

• • Port: Highly regarded as the most direct alternative to Backstage if you want deep flexibility without coding. Instead of static YAML files pinned to repos, Port uses Blueprints to define a custom knowledge graph of your engineering ecosystem (services, cloud buckets, PagerDuty schedules, etc.) and populates it via ingestion agents. It features powerful self-service actions and scorecards out of the box. Learn more on the Port Platform Overview.
• • Cortex: Leans heavily into engineering standards and governance . If your primary driver for a catalog is enforcing scorecards, tracking production readiness, and managing microservice maturity (security patches, ownership, uptime metrics), Cortex provides an opinionated, highly polished engine without requiring custom frontend maintenance. Check out Cortex Features.
• • OpsLevel: Focused tightly on service ownership and catalog accuracy . It uses simple maturity rules, microservice tracking, and self-service actions, with a streamlined onboarding process designed to get teams up and running in days rather than the months typically required for a raw framework. Review OpsLevel Capabilities.
• • Atlassian Compass: If your organization is already deeply embedded in the Atlassian ecosystem (Jira, Confluence, Bitbucket), Compass acts as a native component catalog with scorecards and extensible developer experiences that plug seamlessly into your existing project management tools. Explore Atlassian Compass.

2. The Managed Backstage Route

If you like Backstage's specific architecture (like its TechDocs markdown handling or Scaffolder templates) but don't want your platform engineers spending half their time managing Node.js upgrades, plugin conflicts, and frontend code, you can buy it hosted.

• • Roadie: A fully managed, cloud-hosted version of open-source Backstage. Roadie runs the open-source core and handles the security patches, database management, and plugin stability so your team can just write catalog YAML and use the standard ecosystem. Learn more on Roadie.io.
• • Spotify Portal for Backstage: Spotify’s own commercial packaging of the framework they created, bundling their enterprise-grade plugins and an assembled out-of-the-box experience.

3. The Lightweight / Documentation-First Stack

If you have a smaller engineering organization or your main pain point is simply finding where documentation and service metadata live , a massive IDP might be over-engineering.

• • Backstage TechDocs alternative: Use a dedicated documentation-as-code generator like MkDocs (with the Material theme) or Redocly / Swagger UI for APIs, hosted centrally on GitHub Pages, GitLab Pages, or an internal S3/CDN bucket.
• • Registry approach: Pair your documentation site with a lightweight, structured metadata file (service.yaml ) residing in each repository, indexed via a simple cron job into a searchable internal database or even a clean Notion/Airtable board for early-stage tracking.

To help narrow down the ideal foundation, tell me:

• Roughly how many engineers and services you are supporting?
• Do you have a dedicated platform team available to manage the tool, or does it need to run completely hands-off?
• Is your primary goal service discovery, infrastructure self-service/provisioning , or enforcing engineering scorecards?

Yes. If your goal is “Backstage-like catalog + docs, but without adopting the Backstage framework,” I’d separate the problem into two foundations:

1. A software/service catalog — ownership, lifecycle, dependencies, APIs, repositories, environments, operational links.
2. A documentation system — Markdown/docs-as-code, search, versioning, API references, architecture docs.

That gives you much more architectural freedom than starting with a monolithic portal.

My shortlist

1. Port — my first choice if you don't want to build the catalog

Port's catalog is particularly interesting because it doesn't force you into Backstage's entity model. Its Blueprints let you define your own asset types—services, APIs, databases, Kubernetes resources, CI jobs, cloud environments, etc.—and Relations model dependencies between them.

That makes it a good foundation if you expect your portal to eventually become:

service catalog → ownership → scorecards → self-service → infrastructure context → automation rather than merely a nicer list of Git repositories.

I'd pick Port if: you want to get something useful in front of developers quickly and don't want your team maintaining the portal itself.

2. Cortex — if service maturity is central

Cortex is attractive if your catalog needs to answer questions like:

• Who owns this service?
• Is it production-ready?
• Does it have an SLO?
• Does it have an on-call rotation?
• Does it meet our security/reliability standards?
• Which services are missing required documentation?

Its strength is less “build any portal you can imagine” and more catalog + engineering standards + scorecards.

3. OpsLevel — similar direction, particularly strong for service maturity

OpsLevel is worth evaluating alongside Cortex if you're interested in automatically discovering services and then progressively attaching ownership, maturity checks, documentation, operational metadata, etc.

A useful mental model is:

Port: flexible internal developer platform/catalog Cortex: service catalog + engineering quality OpsLevel: service catalog + maturity/governance

Those distinctions aren't absolute, but they're useful when evaluating them.

For documentation, I wouldn't make the catalog own the docs

This is the architectural choice I'd strongly recommend.

Use a dedicated docs-as-code system such as:

• Docusaurus — excellent general-purpose documentation site
• MkDocs — extremely simple Markdown → documentation pipeline
• GitBook — polished, easier for non-engineers
• Nextra — particularly nice if your organization is already in the Next.js/React ecosystem

For example:

                    ┌─────────────────────┐
                    │   Developer Portal  │
                    └──────────┬──────────┘
                               │
              ┌────────────────┴────────────────┐
              │                                 │
      ┌───────▼────────┐               ┌────────▼────────┐
      │ Software       │               │ Documentation   │
      │ Catalog        │               │                 │
      │                │               │ Markdown/docs   │
      │ Services       │               │ API references  │
      │ APIs           │               │ Runbooks        │
      │ Teams          │               │ Architecture    │
      │ Dependencies   │               │ Tutorials       │
      │ Environments   │               │                 │
      └───────┬────────┘               └────────┬────────┘
              │                                 │
              └──────────────┬──────────────────┘
                             │
                    ┌────────▼────────┐
                    │ Git / CI /      │
                    │ Kubernetes /    │
                    │ Cloud / APIs    │
                    └─────────────────┘

The catalog should primarily answer “what is this and how does it relate to everything else?”

The docs system should answer “how do I use, operate, understand, or modify it?”

That's a cleaner boundary than trying to make one product do both.

If you want to build the catalog yourself

This can actually be a very good approach if you have a strong platform team.

I would not reproduce Backstage's architecture. Instead, make the catalog a relatively boring service with a well-defined API.

Something like:

Catalog
├── entities
│   ├── Service
│   ├── API
│   ├── Library
│   ├── Database
│   ├── Dataset
│   ├── Team
│   └── Environment
│
├── relationships
│   ├── owned_by
│   ├── depends_on
│   ├── exposes
│   ├── consumes
│   ├── deployed_to
│   └── part_of
│
└── metadata
    ├── repository
    ├── lifecycle
    ├── language
    ├── documentation_url
    ├── runbook_url
    ├── oncall
    └── links

Then ingest metadata from systems you already have:

GitHub/GitLab ──────┐
Kubernetes ─────────┤
AWS/GCP/Azure ──────┤
Datadog ────────────┼──> Catalog
PagerDuty ──────────┤
CI/CD ──────────────┤
Terraform ──────────┘

And expose a simple API:

GET /services
GET /services/{id}
GET /teams/{id}
GET /apis/{id}
GET /dependencies?service=payments
GET /search?q=payments

The portal UI then becomes a consumer of your catalog, rather than the catalog being embedded in your portal framework.

That's the part of Backstage's model I'd preserve conceptually: a central inventory containing ownership, metadata, and relationships. Backstage itself describes its catalog as a centralized inventory/software graph for services, libraries, APIs, data pipelines, ownership, and dependencies.

What I'd build today

If I were designing this from scratch in 2026, I'd choose one of these two paths:

Small/medium platform team:

Port + Docusaurus/MkDocs + GitHub/GitLab + your existing observability/incident systems You get the catalog and portal mechanics without spending your platform team's time building a portal framework.

Large platform team / strong desire for control:

Postgres-backed catalog API + Docusaurus + lightweight React/Next.js portal Make the catalog itself an independent platform service. Let integrations populate it, and let the UI be replaceable.

I particularly like the second architecture because the portal becomes disposable. If you replace your React frontend in three years, the catalog, metadata contracts, integrations, and documentation remain intact.

One thing I'd avoid

I wouldn't start by designing the UI.

Start with the catalog data model and ownership contract:

“What is a service? What is an API? Who owns it? What relationships matter? What metadata is authoritative? How does an entity get created and updated?” Once that is right, the portal UI is comparatively straightforward.

If you tell me roughly your stack (GitHub/GitLab, Kubernetes or not, cloud, language ecosystem) and company size, I can propose a concrete Backstage-free architecture—including the catalog schema, ingestion strategy, docs stack, search, and how I'd structure the first 90 days.

If you want a solid software catalog and centralized documentation without taking on the maintenance nightmare of a self-hosted TypeScript/React framework like Backstage , you have a few distinct paths. The right foundation depends on whether you want a commercial turnkey SaaS , an ecosystem-native extension , or a lightweight self-hosted alternative.

1. Commercial No-Code Portals (Buy / Managed)

If you want to skip building UI plugins and managing backend state, modern SaaS portals let you define your data model and documentation visually.

• Port (Port ): A heavily configurable, schema-driven developer portal. Instead of writing code, you define your entities (services, microservices, cloud resources, APIs) visually, and map them to your existing CI/CD pipelines . It handles the catalog, scorecards, and action workflows smoothly out of the box.
• Atlassian Compass (Atlassian Compass ): A component catalog designed to track architecture and ownership. If your engineering stack already relies deeply on Jira, Confluence, and Bitbucket, Compass integrates naturally to pull in service metadata, scorecards, and team ownership without extra overhead.
• OpsLevel (OpsLevel ): Excellent if your primary goal for a software catalog is service ownership and enforcing maturity standards via scorecards . It is fast to roll out and emphasizes automatic service discovery to prevent configuration drift.
• Cortex (Cortex ): Another robust enterprise portal focused on scorecards, cataloging, and "engineering intelligence" (tracking security scans, production readiness, and API documentation standards).

2. The GitOps / Documentation-First Approach (Lightweight & Open)

If your documentation already lives in markdown and your infrastructure lives in Git, you can pair a documentation hub with a lightweight metadata index rather than deploying a monolithic portal.

• Backstage Managed Alternatives (Hybrid) : If you actually like Backstage’s catalog model (the catalog-info.yaml spec) but hate hosting it, platforms like Roadie (Roadie ) or Spotify Portal for Backstage run the infrastructure and plugin maintenance for you as a managed service.
• MkDocs / Redocly + Git-based Registry : For many mid-sized engineering teams, standardizing on a dedicated documentation site generator (like MkDocs with the tech-docs style, or Redocly for API specs) tied to a central repository of JSON/YAML service definitions serves the exact same discoverability purpose as a heavy IDP—with zero custom frontend maintenance.

If you can share:

• Your team size and whether you have dedicated frontend/platform engineers
• Whether you prefer open-source / self-hosted or SaaS
• Your primary goal (e.g., API documentation, infrastructure self-service , or scorecards and governance)

I can help you narrow down the ideal stack.

Yes. If your goal is “software catalog + docs first, then grow into an internal developer portal”, I’d avoid starting with another Backstage-shaped framework unless you specifically want to build and maintain the portal itself.

My shortlist in 2026 would be:

My recommendation: Port if you want a portal; Git-based docs + a catalog API if you want a platform

1. Port — probably the closest answer to “Backstage without Backstage.”

Port gives you a configurable software catalog/data model rather than making you build the catalog around Backstage's entity model. It also adds scorecards, integrations, and self-service actions. Current comparisons describe it as a SaaS alternative where you configure the model rather than maintaining a portal codebase.

I'd choose this if your platform team is small and you'd rather spend engineering time on golden paths and infrastructure than on React/Node portal maintenance.

2. OpsLevel — strongest if the catalog is the centerpiece.

OpsLevel's catalog automatically pulls information from repositories, infrastructure and third-party systems, and its model is explicitly centered around services, ownership, dependencies and standards. It also has actions/service creation, so you can evolve from “where is this service?” into “do this thing for me.”

This is particularly attractive if you want catalog → ownership → scorecards → operational maturity to be the progression.

3. Cortex — good if engineering governance is a major requirement.

Cortex has explicit catalogs for services, infrastructure, domains and teams, with entities represented as YAML. docs.cortex.io It leans heavily into ownership, scorecards and engineering standards.

I'd favor it over Port when your primary question is less “where do I find things?” and more “are our services meeting the standards we've defined?”

---

But there's another architecture I'd seriously consider

If documentation is genuinely important, don't make the portal the canonical home of your docs.

I'd build:

                    ┌──────────────────────┐
                    │   Developer Portal    │
                    │                      │
                    │ Catalog │ Docs │ APIs│
                    └──────────┬───────────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
        Service catalog     Git repos       Documentation
              │                │                │
        ownership, deps,    metadata.yml     Markdown
        lifecycle, APIs,                     /docs
        environments

Make Git the source of truth for technical documentation and service metadata, then have the portal index and enrich it.

For example, a service could own:

payments-api/
├── src/
├── docs/
│   ├── overview.md
│   ├── architecture.md
│   ├── runbook.md
│   └── troubleshooting.md
└── service.yaml

And service.yaml might contain only the durable identity:

name: payments-api
owner: team-payments
lifecycle: production
repository: github.com/acme/payments-api

interfaces:
  - type: openapi
    path: docs/openapi.yaml

documentation:
  - docs/overview.md
  - docs/architecture.md
  - docs/runbook.md

Then your portal becomes a projection of engineering reality, rather than another database people have to keep synchronized.

That's an important distinction: a catalog is most valuable when it tells developers who owns something, what it depends on, where its code/docs/API live, and how it is operated.

What I'd build

If I were starting from scratch today, I'd probably do:

Port + GitHub/GitLab + Markdown/OpenAPI + your existing CI/CD, rather than attempting to recreate Backstage.

If you have a strong preference for self-hosting/open source, I'd instead build a relatively thin portal around:

• PostgreSQL for catalog metadata
• Git as the source of truth
• OpenAPI/AsyncAPI for interfaces
• Markdown/MkDocs or Docusaurus for docs
• GitHub/GitLab APIs for repository ownership/activity
• Kubernetes/cloud APIs for runtime relationships
• OpenTelemetry/your observability system for operational signals
• OIDC for identity
• a small GraphQL/REST catalog API
• a deliberately boring web UI

That latter architecture gives you much less magic and much more control, but you are taking on product ownership of the portal.

The key decision I'd make before picking a product: do you want the portal to primarily be a catalog/docs/search experience, or do you want it to become the control plane for developer self-service (create service, provision DB, deploy environment, request access, rotate credentials, etc.)? The answer changes my recommendation substantially.

Building an internal developer portal (IDP) without Spotify's Backstage often comes down to choosing tools that balance flexibility, maintenance overhead, and how your team likes to write documentation.

Here are the top foundational alternatives for a software catalog and documentation engine:

• Port - A highly customizable, SaaS-based internal developer portal designed as a modern, lightweight alternative to Backstage. It features a powerful data model for your software catalog, self-service action runners, and a clean UI without requiring you to maintain Node.js/TypeScript plugins or infrastructure.
• Cortex - A developer portal focused heavily on software catalogs, service scorecards, and action plugins. It offers robust out-of-the-box maturity assessments, ownership tracking, and integrations, making it a great turnkey alternative if you want to avoid Backstage's configuration complexity.
• Roadie - A fully managed, enterprise-ready SaaS version of Backstage itself. (Included with the caveat that while it uses Backstage under the hood, it completely removes the burden of hosting, upgrading, and maintaining the Backstage open-source framework yourself).
• Lightdash / Git-based docs + CI/CD - For a lightweight, developer-first approach, many teams use a Git repository (like GitHub or GitLab) as the source of truth for their catalog (using a standardized catalog-info.yaml or similar metadata file) paired with a modern documentation platform like Mintlify or GitBook , and an orchestrator like Temporal or simple GitHub Actions for self-service actions.
• Hinterland / OpsLevel - OpsLevel excels primarily as a microservice catalog and service maturity scorecard. Paired with a solid docs site like MkDocs (backed by Material for MkDocs) or Docusaurus , it creates a powerful developer portal without the heavy frontend/backend framework overhead of Backstage.

If you'd like to narrow this down, let me know:

• Do you prefer a fully managed SaaS or a self-hosted open-source solution?
• How are your docs and service metadata currently stored (e.g., GitHub, Notion, Kubernetes)?

I can help you design a specific stack that fits your team's workflow.

Yes. If you want Backstage-like concepts without adopting Backstage itself, I’d start with a catalog-first SaaS platform, and keep documentation docs-as-code in Git rather than making the portal your canonical content store.

My shortlist

What I'd actually build

I'd separate the architecture into three layers:

                    Internal Developer Portal
                             │
             ┌───────────────┴───────────────┐
             │                               │
       Software Catalog                 Documentation
             │                               │
       Port / OpsLevel /               Git + Markdown
          Cortex                         + docs engine
             │                               │
      ┌──────┼──────┐                  ┌─────┴─────┐
      │      │      │                  │           │
    GitHub  K8s    AWS              Service docs  Guides
      │      │      │
      └──────┼──────┘
             │
       Ownership / APIs /
       dependencies /
       environments /
       deployments /
       incidents

The important architectural decision is not to make the portal itself the source of truth.

For example:

• Service metadata: catalog
• Ownership: catalog, synced from your identity/Git systems
• Repository: Git provider
• API specification: OpenAPI in the repository
• Runbooks: Markdown in the service repository
• Architecture docs: Markdown/docs repository
• Deployments: CI/CD
• Runtime state: Kubernetes/cloud/observability
• Incidents: PagerDuty/Incident.io/etc.
• Portal: a unified view and action layer

That gives you a much healthier model than "everyone edits metadata in the portal."

Why OpsLevel is particularly interesting for this use case

If your question is specifically "what should be the foundation for my software catalog + documentation?", I'd put OpsLevel at the top of the evaluation list.

It can populate the catalog from Git and other integrations, maintain metadata through opslevel.yml, and automatically detect components.

More importantly, its documentation model aligns nicely with the architecture above: Markdown living in repositories can be surfaced alongside the corresponding catalog component, while OpenAPI documents can be pulled from source control and rendered centrally.

So a developer could see:

Payments API
Owner: Payments Platform
Repository: payments-api
Tier: 1
Runtime: Kubernetes
Dependencies: Auth, Ledger
Docs | API | Deployments | Incidents | SLOs
Last deployed: 2h ago

without requiring your team to invent a portal-specific documentation system.

Port is the one I'd evaluate alongside it

I'd choose Port over OpsLevel if you expect the portal to become a broader internal platform/workflow layer, rather than primarily a software catalog.

Port's particularly attractive because you can bring your own data model, populate the catalog through APIs, and use workflows for self-service operations. Its current documentation also supports building a technical-docs model that connects Markdown from Git to catalog entities.

So I'd frame the decision this way:

"We need a really good service catalog and engineering system of record."
→ OpsLevel

"We want to build a custom internal developer platform around a flexible catalog and workflows."
→ Port

"We care heavily about engineering standards, scorecards, and maturity."
→ Cortex

"We have a lot of platform engineering capacity and genuinely unusual requirements."
→ Build a thin custom portal, but don't build the catalog/data ingestion layer from scratch unless you have a compelling reason.

One other option I'd explicitly not put at the top: Roadie. It's a good managed Backstage offering, but if your requirement is genuinely "not Backstage," you're mostly changing the operational model rather than the underlying architecture.

If I were starting an internal portal today, my default stack would be Port or OpsLevel + Git-based Markdown/OpenAPI + GitHub/GitLab + Kubernetes/cloud integrations + SSO, with the portal treated as the presentation/action layer rather than the authoritative datastore.