internal-developer-platform

What this skill does

# Internal Developer Platform

Comprehensive guide to designing and building Internal Developer Platforms (IDPs) that improve developer productivity and experience.

## When to Use This Skill

- Designing an Internal Developer Platform
- Building or restructuring platform teams
- Improving developer experience (DevEx)
- Evaluating platform technologies (Backstage, Port, etc.)
- Creating self-service capabilities for developers
- Measuring platform adoption and success

## Platform Engineering Fundamentals

### What is an Internal Developer Platform?

```text
Internal Developer Platform (IDP):
A layer on top of infrastructure that provides self-service
capabilities to development teams while maintaining governance.

┌─────────────────────────────────────────────────────────────┐
│                    DEVELOPERS                                │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐       │
│  │ Team A  │  │ Team B  │  │ Team C  │  │ Team D  │       │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘       │
│       │            │            │            │              │
│       └────────────┴─────┬──────┴────────────┘              │
│                          │                                   │
│  ┌───────────────────────┴───────────────────────────────┐  │
│  │              INTERNAL DEVELOPER PLATFORM               │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │  │
│  │  │ Service  │ │ Template │ │ Self-    │ │ Docs &   │ │  │
│  │  │ Catalog  │ │ Library  │ │ Service  │ │ Discovery│ │  │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘ │  │
│  └───────────────────────────────────────────────────────┘  │
│                          │                                   │
│  ┌───────────────────────┴───────────────────────────────┐  │
│  │                  INFRASTRUCTURE                        │  │
│  │  Kubernetes │ Cloud │ CI/CD │ Observability │ Security │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Key Value Propositions:
├── Self-service: Developers can provision without tickets
├── Standardization: Consistent patterns across teams
├── Guardrails: Security and compliance built-in
├── Visibility: Centralized service catalog and docs
└── Efficiency: Reduce cognitive load on developers
```

### Platform vs Infrastructure

```text
Infrastructure Team (Traditional):
- Ticket-based requests
- Manual provisioning
- Bespoke solutions per team
- Ops handles deployments
- Documentation scattered

Platform Team (Modern):
- Self-service capabilities
- Automated provisioning
- Standardized templates
- Developers own deployments
- Centralized documentation

Key Shift:
"You Build It, You Run It" + "Platform Handles the How"
```

## Platform Core Components

### Service Catalog

```text
Service Catalog:
Centralized registry of all services with ownership, docs, and metadata.

┌─────────────────────────────────────────────────────────────┐
│                    SERVICE CATALOG                           │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │ Payment Service                                [API]     │ │
│  │ Owner: Payments Team     │ Tier: Critical              │ │
│  │ Tech: Node.js, PostgreSQL │ Dependencies: 4            │ │
│  │ [Docs] [API Spec] [Runbook] [Alerts] [Deploy]          │ │
│  └─────────────────────────────────────────────────────────┘ │
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │ User Service                                 [Backend]   │ │
│  │ Owner: Identity Team     │ Tier: High                  │ │
│  │ Tech: Go, MongoDB        │ Dependencies: 2             │ │
│  │ [Docs] [API Spec] [Runbook] [Alerts] [Deploy]          │ │
│  └─────────────────────────────────────────────────────────┘ │
│                                                              │
│  Service Metadata:                                           │
│  ├── Owner team and contacts                                │
│  ├── Technical stack                                        │
│  ├── Service tier/criticality                               │
│  ├── Dependencies (upstream/downstream)                     │
│  ├── API specifications                                     │
│  ├── Documentation links                                    │
│  ├── Deployment information                                 │
│  └── Observability dashboards                               │
└─────────────────────────────────────────────────────────────┘
```

### Template Library

```text
Template Library:
Pre-built templates for common patterns that encode best practices.

Template Categories:
├── Application Templates
│   ├── REST API (Go, Node.js, .NET, Python)
│   ├── GraphQL Service
│   ├── gRPC Service
│   ├── Event Consumer
│   ├── Scheduled Job
│   └── Frontend (React, Vue, Angular)
│
├── Infrastructure Templates
│   ├── Database (PostgreSQL, MySQL, MongoDB)
│   ├── Cache (Redis, Memcached)
│   ├── Message Queue (Kafka, RabbitMQ)
│   └── Storage (S3, GCS)
│
└── Integration Templates
    ├── Third-party API client
    ├── Authentication flow
    └── Webhook handler

Template Contents:
┌─────────────────────────────────────────────────────────────┐
│ Template: node-rest-api                                      │
├─────────────────────────────────────────────────────────────┤
│ ├── src/                    │ Application code              │
│ ├── tests/                  │ Test setup                    │
│ ├── Dockerfile              │ Container image               │
│ ├── helm/                   │ Kubernetes deployment         │
│ ├── .github/workflows/      │ CI/CD pipelines               │
│ ├── docs/                   │ Documentation templates       │
│ ├── catalog-info.yaml       │ Backstage registration        │
│ └── terraform/              │ Infrastructure as Code        │
│                                                              │
│ Built-in:                                                    │
│ ✓ Health checks             ✓ Structured logging            │
│ ✓ OpenTelemetry tracing     ✓ Prometheus metrics           │
│ ✓ Security headers          ✓ Input validation             │
│ ✓ Error handling            ✓ API documentation            │
└─────────────────────────────────────────────────────────────┘
```

### Self-Service Portal

```text
Self-Service Capabilities:
Actions developers can perform without tickets or approvals.

┌─────────────────────────────────────────────────────────────┐
│                  SELF-SERVICE PORTAL                         │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Create New Service     [5 min setup, no tickets]           │
│  ├── Choose template                                        │
│  ├── Configure options                                      │
│  ├── Generate repository                                    │
│  ├── Create CI/CD pipeline                                  │
│  ├── Provision infrastructure                               │
│  └── Register in catalog                                    │
│                                                              │
│  Common Self-Service Actions:                               │
│  ┌────────────────┬────────────────┬────────────────┐      │
│  │ Environments   │ Databases      │ Secrets        │      │
│  │ ├── Create env │ ├── Provision  │ ├── Create     │      │
│  │ ├── Clone env  │ ├── Scale      │ ├── Rotate     │      │
│  │ └── Destroy    │ └── Backup     │ └── Access     │      │
│  └────────────────┴────────────────┴────────────────┘      │
│  ┌────────────────┬────────────────┬────────────────┐      │
│  │ Deployments    │ Domains        │ Acce