Developer Portal, Service Catalog, and Golden Paths
Treat the software factory as an internal product that developers and agents can discover, understand, and use safely.
A rapid review of the chapter’s existing Quick Read, principles, definitions, lessons, and review material.
The chapter in one pass.
- Purpose: Treat the software factory as an internal product that developers and agents can discover, understand, and use safely.
- Best for: Platform leaders, product managers, architects, and engineering executives.
- Prerequisites: Enterprise Adoption and Factory Maturity.
- Reading time: 14 minutes.
- You will learn: How portals, catalogs, templates, and golden paths create self-service without hiding authority or flexibility.
- Keep three ideas: the portal is a view, not the source of truth; golden paths are supported products; and adoption is an outcome measure.
Reconstruct and defend this chapter’s architecture.
Reconstruct the architecture, name each boundary, and defend the tradeoffs.
Open the source exercise
Design the portal journey for onboarding a repository and running its first low-risk workflow. Map every page action to an authoritative API, state, permission, evidence requirement, owner, and recovery path.
3. Enduring Principle
Operate the factory as an internal product
Define target users, journeys, service levels, adoption measures, support, feedback, and roadmap. The platform team owns ease of safe use; consuming teams retain responsibility for product intent and domain risk.
Use one catalog for human and agent discovery
The catalog connects services, repositories, owners, workflows, capabilities, environments, APIs, schemas, runbooks, evidence, maturity, and dependencies. Humans browse through a portal; agents query governed APIs. Both resolve to the same authoritative records and permissions.
Build golden paths around outcomes
A golden path is a supported, paved route with templates, defaults, automated checks, observability, documentation, and an escape mechanism. Useful paths include repository onboarding, bounded feature delivery, dependency remediation, incident investigation, and progressive release.
Golden paths should expose their contract:
- supported scenarios and non-goals;
- required inputs and owners;
- generated or selected capabilities;
- authority and approval boundaries;
- expected evidence and service level;
- common failures and recovery; and
- extension points with compatibility obligations.
Preserve an escape path
Teams need explicit extension and exception mechanisms. Extensions are versioned and tested; exceptions have owner, reason, scope, expiry, and compensating controls. Silent forks create platform fragmentation.
8. Notes and lessons learned
Platform adoption is evidence about product fit. Requiring training and support may be reasonable; requiring specialists for routine use is a platform defect.
9. Interview and discussion questions
- When does a portal become a shadow control plane?
- What makes a golden path a product rather than a template?
- How should teams extend a path safely?
- Which adoption metrics reveal real value?
- How do agents and humans share the same catalog?
Review this chapter.
Challenge a claim, boundary, missing failure mode, unclear term, or unsupported evidence statement.
- Claim
- Boundary
- Failure
- Evidence