Building an Internal Developer Platform: From Zero to Production

An Internal Developer Platform (IDP) is not a product you buy — it is an opinionated abstraction layer your platform team builds to standardise how software gets to production. Done well, it eliminates toil, codifies best practices, and lets product engineers focus on building features rather than configuring infrastructure.

Done poorly, it becomes another system to maintain that no one trusts.

This post covers what we learned building an IDP from scratch that now serves 80+ engineers across a fintech company — what worked, what failed, and the decisions we would make again.

What Problem Are We Actually Solving?

Before writing a single line of Terraform, we spent two weeks running a developer experience survey. The top pain points were:

1. Inconsistent environments — “it works on my machine” was the most common phrase in Slack
2. Deployment confusion — no clear process for getting code to production
3. Observability gaps — engineers found out about problems from customers, not from dashboards
4. Toil — the same manual steps repeated across every new service

An IDP solves all of these. But only if you treat it as a product with a roadmap, users, and feedback loops — not an infrastructure project.

The Golden Path

The single most important concept in platform engineering is the golden path: the recommended, paved road for building and deploying a service at your company.

A good golden path includes:

• A service template (with CI/CD, tests, Dockerfile, and manifests pre-configured)
• A self-service onboarding flow that works without raising a ticket
• Deployment that is repeatable, auditable, and rollback-capable
• Observability out of the box — logs, metrics, and traces from day one

We built ours using Backstage for the developer portal and ArgoCD for GitOps-based deployments. Engineers create a new service by filling in a form in Backstage, which scaffolds a repository from a template and registers it with our deployment system.

First deployment: under 30 minutes. Previously: 2-3 days of tickets and waiting.

The Architecture

┌─────────────────────────────────────────────────────┐
│                  Developer Portal                    │
│               (Backstage + Plugins)                  │
└─────────────────────┬───────────────────────────────┘
                      │ API calls
        ┌─────────────▼─────────────┐
        │    Platform Control Plane  │
        │  (Crossplane + Operators)  │
        └─────────┬─────────────────┘
                  │ Reconciles
    ┌─────────────▼─────────────────────────┐
    │          Kubernetes Clusters           │
    │   (ArgoCD · Istio · Prometheus stack) │
    └───────────────────────────────────────┘

The key design decision was keeping the control plane declarative. Engineers describe what they want (a service, a database, a queue), and the platform reconciles reality to match the declaration. This means the platform is self-healing and auditable.

What Would We Do Differently?

Start smaller. We built too much before getting user feedback. The first version of our IDP had 12 features. Engineers used 3 of them. We should have shipped the 3 and gathered feedback before building the other 9.

Treat docs as a first-class deliverable. The platform is only as good as its documentation. We underinvested here early and it cost us trust with engineers who couldn’t figure out what things did.

Measure adoption metrics from day one. You need to know whether engineers are using the golden path or working around it. If they’re working around it, that’s signal that the path has a problem.

Conclusion

An IDP is a force multiplier for engineering teams — but only if it genuinely reduces friction rather than adding abstraction for its own sake. The best platforms feel invisible: engineers use them because it is the easiest way to do the right thing.

If you’re starting an IDP journey or looking to improve an existing platform, we’re happy to chat. The lessons in this post came from real experience, and every situation is different.

---

Working on a platform engineering challenge? Get in touch — we offer advisory sessions and platform engineering engagements.