Platform Engineering: Building Internal Developer Platforms

Your best engineers spend a surprising amount of their week not building product. They wait on infrastructure tickets, copy-paste YAML between repositories, debug CI pipelines that break for reasons no one fully understands, and reverse-engineer how the last team deployed a service. Every hour spent on this undifferentiated toil is an hour not spent on the features your customers actually pay for. Platform engineering exists to reclaim that time. By building an internal developer platform (IDP), platform teams turn tribal knowledge and manual processes into paved, self-service paths that let product engineers ship independently and safely. This article is a practical guide for engineering managers who want to understand what an IDP really is, how to build one, and how to avoid the expensive mistakes that sink these initiatives.

• Background / Why This Matters
• Core Concepts and Architecture
• Implementation Strategy
• Scaling and Operational Considerations
• Common Mistakes / What to Avoid
• Frequently Asked Questions
• Conclusion

Background / Why This Matters

For most of the last decade, the answer to "how do we scale engineering?" was DevOps: teach every team to own their infrastructure, embrace "you build it, you run it," and hand developers full access to the cloud console. That worked beautifully at small scale. But as organizations grew past a handful of teams, the cognitive load became crushing. Suddenly a product engineer was expected to be fluent in Kubernetes, Terraform, IAM policies, observability stacks, network security, and cost optimization — on top of actually knowing the business domain.

Research from the DevOps and platform engineering community consistently points to the same failure mode: when you distribute operational complexity to every team without abstraction, you get inconsistency, security drift, and slow onboarding. Estimates vary, but many organizations report that new engineers take weeks — not days — to ship their first production change, largely because of undocumented, bespoke setup.

Platform engineering is the correction. Instead of asking every team to solve infrastructure problems from scratch, a dedicated platform team builds an internal product — the IDP — that other engineers consume. The key mental shift is that your developers are the customers, and developer experience (DX) is the product metric that matters.

Takeaway: If your engineers are spending more than 20–30% of their time on infrastructure plumbing rather than product work, you have a platform problem worth investing in — regardless of company size.

Core Concepts and Architecture

An internal developer platform is not a single tool. It is a layered system that combines infrastructure automation, standardized workflows, and a unified interface. Three concepts define a good IDP.

Golden Paths

A golden path is the well-supported, opinionated route to accomplish a common task — creating a new microservice, provisioning a database, setting up CI/CD. The path is not mandatory, but it is so convenient and reliable that engineers choose it by default. A golden path for "new Go service" might scaffold the repository, wire up a GitHub Actions pipeline, register the service in your catalog, provision observability, and deploy a hello-world container to staging — all from a single template.

Self-Service Infrastructure

The platform exposes infrastructure as consumable capabilities, not raw primitives. Instead of writing 300 lines of Terraform to stand up a Postgres instance with the right backups, encryption, and network rules, a developer requests a database through a form or a manifest, and the platform provisions it correctly every time. Underneath, the platform team maintains vetted Terraform modules and drives deployments through GitOps with tools like ArgoCD.

The Developer Portal

The portal is the front door. Backstage, the open-source portal originally built at Spotify, is the de facto standard here. It provides a software catalog (every service, its owner, its docs, its dependencies), scaffolding templates for golden paths, and plugins that surface CI status, deployments, incidents, and API documentation in one place.

A typical reference architecture looks like this:

Layer	Purpose	Example Tooling
Developer Portal	Discovery, catalog, scaffolding, docs	Backstage
CI/CD	Build, test, and deploy pipelines	GitHub Actions
Delivery / GitOps	Declarative, auditable deployments	ArgoCD
Infrastructure Provisioning	Reproducible cloud resources	Terraform, Crossplane
Observability	Metrics, logs, traces baked in	Prometheus, Grafana, OpenTelemetry

Takeaway: Treat the portal, the pipelines, and the infrastructure modules as three parts of one product. If they don't integrate seamlessly, developers will route around them.

Implementation Strategy

The single biggest mistake in platform work is trying to build the perfect platform before shipping anything. Treat the IDP like any product: find a real pain, deliver a thin slice, measure adoption, iterate.

Step 1: Talk to your developers first

Before you write a line of code, interview 8–12 engineers across different teams. Ask what makes them slow. You will usually find one or two dominant pain points — often "creating a new service takes days" or "I never know which environment my change landed in." Start there, not with the most technically interesting problem.

Step 2: Build one golden path end to end

Pick your most common service type and build a complete path: a Backstage scaffolder template that creates the repo, commits a working GitHub Actions workflow, adds a catalog-info.yaml so the service registers itself, provisions a namespace via Terraform, and configures ArgoCD to deploy it. The goal is that an engineer clicks "Create," fills in a name, and has a running service in staging within minutes.

Step 3: Make GitOps the delivery backbone

Standardize on a GitOps model early. With ArgoCD, the desired state of every environment lives in Git, deployments are declarative, and rollbacks are a revert. This removes an entire class of "who changed prod?" incidents and gives you audit trails for free. It also decouples the platform team from every deployment — engineers merge a PR, ArgoCD does the rest.

Step 4: Abstract infrastructure behind modules

Wrap your Terraform in a small set of well-documented modules that encode your security and reliability defaults. A team requesting a queue, a bucket, or a database should not be able to accidentally create a publicly exposed, unencrypted resource. The module is where your compliance requirements live.

This is often where teams bring in outside help to accelerate. Halkwinds' Engineering practice frequently partners with platform teams to design the Terraform module library and Backstage scaffolder templates that form the backbone of a golden path, so internal teams can focus on the org-specific glue rather than reinventing the foundation.

Takeaway: Ship one complete golden path that a real team uses in production before you generalize. Adoption of a narrow, excellent path beats a broad, mediocre one every time.

Scaling and Operational Considerations

Once your first golden path proves itself, the challenge shifts from building to sustaining. An IDP is a living product with real operational demands.

Staff it like a product team

A platform that no one maintains rots quickly. Assign a dedicated team with a product manager mindset, a backlog, and a roadmap. Estimates vary by organization, but a common starting ratio is one platform engineer per roughly 8–15 product engineers, adjusted for the maturity of your tooling.

Measure developer experience

You cannot improve what you do not measure. Track a small set of meaningful signals:

• Lead time to first deploy for a new service (target: minutes, not days).
• Deployment frequency and change failure rate — the DORA metrics remain the best-validated baseline.
• Golden path adoption — what percentage of new services use the paved road versus building bespoke setups.
• Developer satisfaction — a lightweight quarterly survey often reveals friction that dashboards miss.

Plan for versioning and drift

As your Terraform modules and templates evolve, you will have hundreds of services running slightly different versions. Build a strategy for propagating updates — automated pull requests that bump module versions, deprecation timelines, and clear communication. Tools like Renovate can automate dependency updates across your fleet.

Federate ownership

The platform team should not become the bottleneck for every new capability. Allow senior engineers in product teams to contribute templates and modules back to the platform, with the platform team acting as reviewers and stewards. This is how an IDP scales without the platform team scaling linearly.

Takeaway: Budget for ongoing maintenance from day one. An unmaintained platform generates more frustration than no platform, because developers depend on it and then get blocked.

Common Mistakes / What to Avoid

Most failed platform initiatives fail for organizational, not technical, reasons. Watch for these patterns.

Building a mandatory cage instead of a paved road

If you force teams onto the platform before it is genuinely better than what they had, you breed resentment and workarounds. Golden paths win through convenience, not mandate. Make the right way the easy way.

Confusing the portal with the platform

Standing up Backstage and calling it a day is a common trap. The portal is a window into your platform; if the underlying self-service capabilities and automation don't exist, you have a beautiful catalog pointing at manual processes. Build the capabilities first, then surface them.

Ignoring the "day two" experience

Teams obsess over creating new services and neglect the ongoing lifecycle: upgrades, secret rotation, scaling, incident response, and decommissioning. A service is created once but operated for years. Design golden paths for the full lifecycle.

Not treating developers as customers

Platform teams that build in isolation, ship what they find interesting, and never gather feedback produce shelfware. Adoption is the only honest measure of success. If usage is low, the answer is almost never "the developers are wrong."

Takeaway: Audit your own initiative against these four traps quarterly. The technical work is rarely the reason platforms fail — misaligned incentives and poor developer empathy are.

Frequently Asked Questions

Do we need a platform team if we're only 30 engineers?

Not nec