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.

Platform engineering diagram: product teams use portal, API and template interfaces to reach platform capabilities backed by cloud providers and internal teamsPlatform usersPlatform interfaces (built by the platform team)Platform capabilitiesCapability providersProduct teams(applicationdevelopers)Web portal and servicecatalogSelf-service APIs andCLIsGolden path templatesand docsCI/CD, infrastructure,data, security,observabilityCloud providers andinternalinfrastructure teams
An internal developer platform bridges from capability providers to product teams, following the structure in the CNCF Platforms White Paper. Rendered by ChartCraft's layout engine.

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 diagramWhat it isWhat it does
Product teams (application developers)The platform's usersDevelopers who build the organisation's products. They are the platform's customers, and its features should come from their requirements.
Web portal and service catalogInterfaceA web portal for observing and provisioning products and capabilities: documentation, service catalogs, project templates and telemetry.
Self-service APIs and CLIsInterfaceAPIs and command-line tools for provisioning products and capabilities automatically, without filing a ticket.
Golden path templates and docsInterfaceTemplated 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, observabilityThe capabilities the platform offersBuild, 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 teamsCapability providersThe 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.

  1. Web portals for observing and provisioning products and capabilities
  2. APIs and CLIs for provisioning them automatically
  3. Golden path templates and docs
  4. Automation for building and testing
  5. Automation for delivering and verifying
  6. Development environments, such as hosted IDEs
  7. Observability
  8. Infrastructure services: compute, network, storage
  9. Data services: databases, caches, object stores
  10. Messaging and event services
  11. Identity and secret management
  12. Security services
  13. 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

Skip it when

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.

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.

Opens the studio with your text · or start from the Architecture diagram generator

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.

More patterns and models explained with a diagram

Describe the system in plain English and get the diagram.

Architecture diagram generator →