An internal developer portal (IDP) is a centralized platform that provides developers with self-service access to infrastructure, documentation, and operational tools. It's the front door to your platform engineering efforts.
Without a portal, developers rely on tribal knowledge, ad-hoc Slack questions, and manual processes to deploy services, request infrastructure, and find documentation. This slows everyone down and creates bottlenecks.
A well-designed developer portal provides:
Self-service — Developers provision infrastructure, deploy services, and request access without opening a ticket.
Discovery — Find services, APIs, documentation, and team ownership information in one place.
Standardization — Golden paths and templates enforce best practices automatically.
Visibility — See the health, ownership, and dependencies of every service in your organization.
Platform engineering is the practice of building a curated set of tools, capabilities, and processes for your development teams. The developer portal is the user-facing interface to that platform. The portal doesn't replace platform engineering — it surfaces the platform's capabilities in a developer-friendly way.
Backstage is the most widely adopted open-source developer portal framework. This product is inspired by Backstage's architecture: a software catalog at the core, with plugins for CI/CD, monitoring, documentation, and infrastructure.
The key concepts are:
Whether you use Backstage or build a custom portal, these concepts apply.
The service catalog is the heart of your developer portal. It models every software component in your organization — services, libraries, APIs, and infrastructure — along with their relationships and ownership.
Each entity in the catalog has:
Kind — The type of entity: Component, API, Resource, System, or Domain.
Metadata — Name, description, annotations, tags, and links. Annotations connect entities to external tools (CI/CD, monitoring, documentation).
Spec — Type-specific fields. A Component spec includes the type (service, library, website) and lifecycle (production, experimental, deprecated). An API spec includes the protocol (OpenAPI, GraphQL, gRPC) and definition.
Relations — Connections between entities: API is provided by Component, Component is part of System, System belongs to Domain.
Organize your catalog around real organizational boundaries:
Domain — The broadest grouping. "Payments" or "Customer Experience" are domains. Domains contain systems.
System — A collection of components that work together to provide functionality. "Checkout Flow" is a system containing components for the shopping cart API, payment processing, and order confirmation.
Component — An individual deployable unit. A microservice, a frontend application, or a shared library. This is the entity developers interact with most.
API — A published interface between components. APIs can be consumed by multiple components across different systems.
Every entity must have an owner — a team or individual responsible for its maintenance and operation. Clear ownership prevents orphaned services and ensures accountability. Use annotations to link to team contact information, Slack channels, and on-call schedules.
The included Python catalog validator checks:
Run the validator in CI to prevent invalid catalog entries from being merged.
Get the full Platform Developer Portal and unlock everything.
Get the complete guide with every chapter unlocked, including code samples, diagrams, and best practices.
Access all interactive tools with complete data, all workload profiles, and the full scenario library.
Downloadable source code, configuration files, and working examples from every chapter.
Free updates for life. Every new chapter, tool, and improvement included.