Explained with a diagram · Developer platforms
Platform engineering: what it is, with an internal developer platform diagram
In short
Platform engineering is the discipline of designing and building internal platforms that give product teams self-service access to the capabilities they need to build, deliver and run software. The result is usually called an internal developer platform: portals, APIs and golden-path templates in front of shared capabilities such as CI/CD, infrastructure, data services, observability and security. A dedicated platform team runs it as a product whose users are the organisation's own developers, with the aim of reducing their cognitive load.
Updated · by the ChartCraft team · one of the patterns and models explained with a diagram
What does platform engineering look like as an architecture diagram?
The diagram has four tiers. Product teams are at the top, the platform's interfaces come next, the capabilities the platform offers sit below them, and the providers that actually run those capabilities are at the bottom. The platform is the two middle tiers.
Mermaid code for this diagram
flowchart TD
subgraph users["Platform users"]
productTeams["Product teams (application developers)"]
end
subgraph interfaces["Platform interfaces (built by the platform team)"]
portal["Web portal and service catalog"]
apis["Self-service APIs and CLIs"]
templates["Golden path templates and docs"]
end
subgraph capabilities["Platform capabilities"]
capabilityLayer["CI/CD, infrastructure, data, security, observability"]
end
subgraph providers["Capability providers"]
backing["Cloud providers and internal infrastructure teams"]
end
productTeams --> portal
productTeams --> apis
productTeams --> templates
portal --> capabilityLayer
apis --> capabilityLayer
templates --> capabilityLayer
capabilityLayer --> backing
Paste it into any Mermaid renderer, or check and export it with the Mermaid syntax checker and Mermaid to PNG.
What are the components of an internal developer platform?
An internal developer platform has users, interfaces and capabilities, and it sits on top of capability providers. The platform team owns the interfaces and the experience; it does not have to implement every capability itself.
| Part of the diagram | What it is | What it does |
|---|---|---|
| Product teams (application developers) | The platform's users | Developers who build the organisation's products. They are the platform's customers, and its features should come from their requirements. |
| Web portal and service catalog | Interface | A web portal for observing and provisioning products and capabilities: documentation, service catalogs, project templates and telemetry. |
| Self-service APIs and CLIs | Interface | APIs and command-line tools for provisioning products and capabilities automatically, without filing a ticket. |
| Golden path templates and docs | Interface | Templated compositions of well-integrated code and capabilities for the most common use cases, so that a new service starts on the supported path. |
| CI/CD, infrastructure, data, security, observability | The capabilities the platform offers | Build, test and delivery automation; infrastructure such as compute, networks and storage; databases, caches and messaging; identity, secrets and security checks; and observability of functionality, performance and cost. The full list is below. |
| Cloud providers and internal infrastructure teams | Capability providers | The teams or vendors that maintain the implementations: public cloud services, managed services or other teams in the same enterprise. |
What capabilities does an internal developer platform provide?
The CNCF Platforms White Paper lists thirteen capability domains. The first three are the interfaces through which everything else is offered, and the rest are the services a cloud-native application typically needs.
- Web portals for observing and provisioning products and capabilities
- APIs and CLIs for provisioning them automatically
- Golden path templates and docs
- Automation for building and testing
- Automation for delivering and verifying
- Development environments, such as hosted IDEs
- Observability
- Infrastructure services: compute, network, storage
- Data services: databases, caches, object stores
- Messaging and event services
- Identity and secret management
- Security services
- Artifact storage
What is a golden path in platform engineering?
A golden path, or paved path, is a recommended and supported route from code to production that the platform team has made the easiest one to take. In practice it is a template that composes the right pipeline, infrastructure and policies for a common kind of service.
The paving analogy is deliberate: paths begin as dirt trails and are paved as more people use them. A paved path guides developers through security and compliance requirements without slowing delivery, and a platform should stay optional and composable, so a team can still use only the parts it needs.
What is the difference between platform engineering and DevOps?
Platform engineering builds on DevOps principles and does not replace them. DevOps asks product teams to build and run their own software; platform engineering gives those teams a self-service product that hides the infrastructure work this would otherwise load onto them.
The motivation is cognitive load. As responsibility for builds, delivery, infrastructure and observability shifted to product teams, they spent more time on those concerns and less on their product. A few platform teams serving many product teams move that common work into one place.
When does an organisation need platform engineering?
It pays off when many product teams repeat the same infrastructure work, or when security and compliance need to be applied consistently across them. A platform multiplies the effect of a few specialists across many teams.
Use it when
- Several product teams each maintain their own pipelines, environments and infrastructure code.
- Developers spend a large share of their time on infrastructure concerns instead of product work.
- Governance for security, compliance or cost has to be consistent across teams.
Skip it when
- You have one or two teams: start with the thinnest viable platform, which can be a wiki page linking to standard procedures.
- Nobody can own the platform as a product, with user research, a roadmap and documentation.
- Teams' needs are so different that there are no common use cases to pave.
What are common mistakes in platform engineering?
Platforms usually fail as products, not as technology: they are built without their users, or they get in those users' way.
- Treating the portal as the platform. A platform is not a tool, a portal or a dashboard; it is the set of paths its capabilities and interfaces make possible.
- Building without user research. The platform team has to learn what product teams need and keep improving against that.
- Implementing every capability in-house. A platform should be the thinnest reasonable layer over managed services and other teams' implementations.
- Making the platform an impediment. It should be optional and composable, letting teams use only parts of it.
- No self-service. If users still need a ticket to get a capability, the platform team cannot scale to many product teams.
- Skipping documentation and onboarding.
How do you draw a platform engineering architecture diagram?
Draw four tiers from top to bottom: users, interfaces, capabilities, providers. Put your own tools in each tier and connect the users to the interfaces, the interfaces to the capabilities, and the capabilities to whoever runs them.
What do real platform and delivery architecture diagrams look like?
Live diagrams from the public ChartCraft gallery, each generated from a plain-English description. Open one to see the prompt that produced it.
Questions
What is platform engineering?
Platform engineering is the discipline of designing and building internal platforms that give software teams self-service access to the capabilities they need, such as environments, deployments and security checks. Dedicated platform teams build and run these platforms as internal products.
What is an internal developer platform?
An internal developer platform is an integrated collection of capabilities, presented through consistent interfaces such as web portals, project templates and self-service APIs, that an organisation provides to its own developers. It offers recommended, supported paths to production.
What does a platform engineer do?
A platform engineer designs and builds the platform, keeps refining it and treats it as a product. That includes researching what its users need, planning its roadmap and maintaining its interfaces: portals, APIs, documentation, templates and command-line tools.
What is the difference between platform engineering and DevOps?
Platform engineering is a practice built up from DevOps principles. DevOps makes product teams responsible for running what they build; platform engineering supplies a self-service platform so that this responsibility does not overload them.
What is a golden path in platform engineering?
A golden path is a recommended, supported way to build and ship a common kind of software, packaged as a template of well-integrated code and capabilities. Following it gives a team working pipelines, infrastructure and security defaults without assembling them by hand.