Designing an Internal Developer Platform

An Internal Developer Platform (IDP) is not a portal with a logo. It is the sum of golden paths, self-service APIs, documentation, and guardrails that let developers provision, deploy, and operate services without filing infra tickets for every change.

Building one at Edmingle meant meeting developers where they already work-GitHub, Slack, kubectl for power users-and reducing time from 'new microservice idea' to 'running in staging with metrics' from weeks to hours. Here is the design framework I use.

Start With Developer Journeys

Map the top five tasks developers repeat: create service, deploy to staging, promote to prod, rotate secret, view logs, scale replicas. Score each for friction (time, tickets, tribal knowledge).

Journey: New service → production
────────────────────────────────────
Before IDP:  3 weeks, 4 teams, 12 Slack threads
After IDP:   4 hours, self-service template, 0 tickets

If you cannot articulate the journey, you will build a dashboard nobody opens.

Platform Layers

Developers interact with the interface layer. Platform team owns everything below and hides complexity behind contracts.

Golden Path Service Template

One blessed way to create a Node.js API (or your stack): repo template with Dockerfile, GitHub Actions workflow, Kustomize overlays, health endpoints, OpenTelemetry bootstrap, and catalog metadata.

# Example: hemal platform create service
platform create service \
  --name enrollment-api \
  --team learning \
  --tier backend \
  --output ./enrollment-api

The template encodes decisions: port 8080, JSON logs, /health/live and /health/ready, ECR push on main merge, Argo CD Application auto-created for staging.

Escape hatches exist via RFC, not by skipping the template silently.

Self-Service vs Guardrails

Self-service: developers trigger deploys, create preview envs, scale HPA max, view their metrics dashboard-all within policy.

Guardrails: admission policy rejects privileged pods, latest image tags, missing resource limits. CI blocks merge without tests.

Balance matters. Pure self-service without guardrails causes incidents. Pure guardrails without self-service causes shadow IT.

Developer Portal and Catalog

Backstage or similar for service catalog: owner, tier, links to repo, dashboard, runbook, on-call rotation. Software templates generate repos from cookiecutter.

The portal is navigation, not the platform itself. If templates and CI work from GitHub alone, portal is optional early on.

Measuring Success

• Lead time for changes: commit to prod duration.
• Deployment frequency per team.
• Mean time to restore after failed deploy.
• Developer satisfaction survey ( quarterly ).
• Ticket volume to platform team for routine tasks (should drop).

Platform teams that only measure uptime miss half the story. Your customers are internal developers.

Rollout Strategy

Pilot with one friendly team. Fix rough edges. Expand team by team. Do not big-bang mandate before the path works.

Document migration for legacy services: strangler pattern, not 'rewrite everything for Backstage day one.'

Engineering Takeaways

• IDP success is measured in developer journeys shortened, not portal feature count.
• Golden path templates encode security, observability, and deploy defaults-copy-paste is the enemy.
• Self-service requires guardrails; policy-as-code enforces what docs alone cannot.
• Interface can be CLI + GitHub templates early; portal comes when catalog size justifies it.
• Track DORA metrics and developer NPS; platform is an internal product with customers.
• Pilot with one team, iterate, then scale adoption-mandates before readiness fail.

Trade-offs I Would Consider

Option: Buy Backstage + heavy customization

• Pros: Rich catalog ecosystem, Spotify pedigree, extensible plugins.
• Cons: Operational overhead, upgrade burden, team needs frontend + backend skills.

Option: Lightweight CLI + GitHub templates + docs

• Pros: Fast to ship, lives in existing workflows, low maintenance.
• Cons: Weaker discoverability, no unified UI, catalog drifts without enforcement.

What I Would Do in Production

Ship service template v1 before portal v1-templates deliver value immediately.

Embed platform links in PR checks: 'deploy preview URL', 'staging dashboard', 'runbook'.

Staff a platform product owner who prioritizes from developer interviews, not loudest Slack voice.

Version platform modules (Terraform, Helm) semver; communicate breaking changes.

Maintain a public platform roadmap and RFC process for new capabilities.

FAQ

Q: Do we need Backstage?

Not on day one. Needed when service count and discoverability pain exceed what README links solve.

Q: How does IDP relate to GitOps?

GitOps is often the deploy engine inside the IDP. Developers trigger via PR; Argo CD reconciles.

Q: Who pays for platform team headcount?

Leadership investment in engineering velocity. ROI shows in reduced lead time and fewer infra incidents.

Q: Can developers opt out of golden path?

For experiments yes in sandbox. For prod, supported path only-unsupported paths assume team owns full stack toil.

Q: How long to build a minimal IDP?

Useful template + CI + staging deploy: 6-10 weeks with 2-3 engineers who know your stack. Mature catalog: ongoing.