Internal Developer Platform Architecture

📖 Introduction

Building an Internal Developer Platform (IDP) is one of the most impactful investments an engineering organization can make—and also one of the most complex. I've seen teams spend months building elaborate platforms that developers never adopted, and I've seen lightweight solutions that transformed productivity almost overnight.

The difference wasn't technical sophistication—it was architecture. A well-architected IDP grows with your organization, while a poorly designed one becomes technical debt.

---

🎯 What is an Internal Developer Platform?

An Internal Developer Platform is the sum of all the technology and tools that a platform engineering team binds together to pave golden paths for developers. It's not a single product you buy—it's an integrated system you build.

---

🏗️ IDP Reference Architecture

The Five Planes Model

Modern IDPs can be understood through five interconnected planes:

┌─────────────────────────────────────────────────────────────────┐
│                     DEVELOPER CONTROL PLANE                      │
│         Portal, CLI, API, IDE Plugins, GitOps Interface         │
├─────────────────────────────────────────────────────────────────┤
│                    INTEGRATION & DELIVERY PLANE                  │
│          CI/CD Pipelines, Artifact Management, GitOps           │
├─────────────────────────────────────────────────────────────────┤
│                       RESOURCE PLANE                             │
│     Kubernetes, Cloud Resources, Databases, Message Queues     │
├─────────────────────────────────────────────────────────────────┤
│                      OBSERVABILITY PLANE                         │
│          Logging, Metrics, Tracing, Cost Tracking               │
├─────────────────────────────────────────────────────────────────┤
│                       SECURITY PLANE                             │
│          Policies, Secrets, Identities, Compliance              │
└─────────────────────────────────────────────────────────────────┘

Detailed Component Architecture

---

📋 Core Components

1. Developer Portal

The developer portal is the single pane of glass for all platform interactions.

# Developer Portal Responsibilities
developer_portal:
  primary_functions:
    - Service catalog: Browse all services and owners
    - Software templates: Create new services
    - Documentation: Centralized tech docs
    - API documentation: Auto-generated from OpenAPI
    - Search: Find anything in the ecosystem
    
  secondary_functions:
    - Cost tracking: Resource costs per team
    - Dependency visualization: Service relationships
    - Health dashboards: SLO status per service
    - Scaffolding: Generate new components

2. Platform API

The API layer provides programmatic access to all platform capabilities.

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Optional
import uuid

app = FastAPI(title="Platform API")


class ServiceRequest(BaseModel):
    """Request to create a new service."""
    name: str
    template: str  # e.g., "python-fastapi", "node-express"
    owner_team: str
    description: Optional[str] = None
    resources: dict = {}  # Database, cache, etc.


class ServiceResponse(BaseModel):
    """Response after service creation."""
    id: str
    name: str
    repository_url: str
    namespace: str
    endpoints: dict


@app.post("/api/v1/services", response_model=ServiceResponse)
async def create_service(request: ServiceRequest):
    """
    Create a new service with all required infrastructure.
    
    This endpoint:
    1. Creates Git repository from template
    2. Provisions Kubernetes namespace
    3. Sets up CI/CD pipeline
    4. Configures monitoring
    5. Provisions requested resources (DB, cache, etc.)
    """
    service_id = str(uuid.uuid4())[:8]
    
    # Orchestrate service creation
    # (In reality, this would call multiple backends)
    
    return ServiceResponse(
        id=service_id,
        name=request.name,
        repository_url=f"https://github.com/org/{request.name}",
        namespace=f"{request.owner_team}-{request.name}",
        endpoints={
            "dev": f"https://{request.name}.dev.platform.io",
            "staging": f"https://{request.name}.staging.platform.io",
        }
    )


@app.get("/api/v1/services/{service_id}")
async def get_service(service_id: str):
    """Get service details including health and resources."""
    pass


@app.post("/api/v1/services/{service_id}/deploy")
async def deploy_service(service_id: str, environment: str):
    """Trigger deployment to specified environment."""
    pass

3. Software Templates

Templates enable consistent, repeatable service creation.

# Example Backstage Software Template
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: python-fastapi-service
  title: Python FastAPI Microservice
  description: Production-ready Python microservice with FastAPI
  tags:
    - python
    - fastapi
    - recommended
spec:
  owner: platform-team
  type: service
  
  parameters:
    - title: Service Information
      required:
        - name
        - description
      properties:
        name:
          title: Name
          type: string
          pattern: '^[a-z0-9-]+$'
        description:
          title: Description
          type: string
        owner:
          title: Owner Team
          type: string
          ui:field: OwnerPicker
          
    - title: Infrastructure Options
      properties:
        database:
          title: Database
          type: string
          enum: ['none', 'postgresql', 'mysql']
          default: 'none'
        cache:
          title: Cache
          type: string
          enum: ['none', 'redis']
          default: 'none'
        
  steps:
    - id: fetch-template
      name: Fetch Template
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          description: ${{ parameters.description }}
          
    - id: create-repo
      name: Create Repository
      action: github:repo:create
      input:
        repoUrl: github.com?owner=org&repo=${{ parameters.name }}
        
    - id: register-catalog
      name: Register in Catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.create-repo.output.repoContentsUrl }}
        catalogInfoPath: '/catalog-info.yaml'
        
    - id: provision-infra
      name: Provision Infrastructure
      action: crossplane:create
      input:
        resources:
          database: ${{ parameters.database }}
          cache: ${{ parameters.cache }}

4. Infrastructure Orchestration

Infrastructure orchestration handles the complexity of provisioning resources.

# Crossplane Composite Resource Definition
apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: xservices.platform.example.com
spec:
  group: platform.example.com
  names:
    kind: XService
    plural: xservices
  versions:
    - name: v1
      served: true
      referenceable: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                name:
                  type: string
                team:
                  type: string
                size:
                  type: string
                  enum: ["small", "medium", "large"]
                database:
                  type: boolean
                  default: false
---
# Composition that defines what resources are created
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: xservice-aws
spec:
  compositeTypeRef:
    apiVersion: platform.example.com/v1
    kind: XService
  resources:
    - name: namespace
      base:
        apiVersion: kubernetes.crossplane.io/v1alpha1
        kind: Object
        spec:
          forProvider:
            manifest:
              apiVersion: v1
              kind: Namespace
      patches:
        - fromFieldPath: spec.name
          toFieldPath: spec.forProvider.manifest.metadata.name
          
    - name: database
      base:
        apiVersion: rds.aws.upbound.io/v1beta1
        kind: Instance
        spec:
          forProvider:
            instanceClass: db.t3.micro
            engine: postgres
      patches:
        - fromFieldPath: spec.size
          toFieldPath: spec.forProvider.instanceClass
          transforms:
            - type: map
              map:
                small: db.t3.micro
                medium: db.t3.small
                large: db.t3.medium

---

🎯 The Thinnest Viable Platform

Start Small, Grow Incrementally

One of the biggest mistakes is trying to build everything at once. Instead, start with a Thinnest Viable Platform (TVP).

TVP Components

Priority	Component	Why It's Essential
Must Have	Service templates	Consistent new services
Must Have	Basic CI/CD	Automated builds and deploys
Must Have	Environment provisioning	Dev/staging/prod
Should Have	Developer portal	Central discovery
Should Have	Self-service databases	Remove common bottleneck
Nice to Have	Full observability stack	Can use existing tools initially

Building the TVP

from dataclasses import dataclass
from enum import Enum
from typing import Optional


class Maturity(Enum):
    """Platform capability maturity levels."""
    NONE = "none"
    MANUAL = "manual"  # Documented process, requires tickets
    ASSISTED = "assisted"  # Some automation, some manual
    SELF_SERVICE = "self-service"  # Fully automated
    OPTIMIZED = "optimized"  # Self-service + insights


@dataclass
class PlatformCapability:
    """Track platform capability maturity."""
    name: str
    current: Maturity
    target: Maturity
    effort_days: int
    business_value: str
    
    @property
    def priority_score(self) -> float:
        """Higher score = higher priority."""
        value_map = {"low": 1, "medium": 2, "high": 3, "critical": 4}
        maturity_gap = list(Maturity).index(self.target) - list(Maturity).index(self.current)
        return (value_map.get(self.business_value, 1) * maturity_gap) / self.effort_days


# Example: Prioritizing TVP components
capabilities = [
    PlatformCapability(
        name="Service Creation",
        current=Maturity.MANUAL,
        target=Maturity.SELF_SERVICE,
        effort_days=10,
        business_value="critical"
    ),
    PlatformCapability(
        name="Environment Provisioning",
        current=Maturity.MANUAL,
        target=Maturity.SELF_SERVICE,
        effort_days=15,
        business_value="high"
    ),
    PlatformCapability(
        name="Database Provisioning",
        current=Maturity.NONE,
        target=Maturity.SELF_SERVICE,
        effort_days=20,
        business_value="medium"
    ),
    PlatformCapability(
        name="Cost Dashboards",
        current=Maturity.NONE,
        target=Maturity.SELF_SERVICE,
        effort_days=8,
        business_value="low"
    ),
]

# Sort by priority
prioritized = sorted(capabilities, key=lambda c: -c.priority_score)
for cap in prioritized:
    print(f"{cap.name}: {cap.priority_score:.2f}")

---

🔧 Build vs. Buy vs. Open Source

Decision Framework

Common Components Comparison

Component	Open Source Options	Commercial Options	Recommendation
Developer Portal	Backstage	Port, Cortex, OpsLevel	OSS for flexibility, commercial for speed
Infrastructure Orchestration	Crossplane, Pulumi	Terraform Cloud, Spacelift	OSS + cloud-managed state
CI/CD	Argo CD, Tekton, Jenkins	GitHub Actions, GitLab CI	Cloud-native preferred
Secrets Management	Vault (OSS)	Vault Enterprise, AWS Secrets Manager	Depends on scale
Policy Enforcement	OPA/Gatekeeper, Kyverno	Styra DAS	OSS usually sufficient
Observability	Prometheus, Grafana, Jaeger	Datadog, New Relic	Cost vs. convenience

The Integration Challenge

Whatever you choose, the real work is integration:

# Platform integration points
integrations:
  git_provider:
    - GitHub
    - GitLab
    triggers:
      - Repository created
      - Pull request merged
      - Tag pushed
      
  container_registry:
    - Harbor
    - ECR
    events:
      - Image pushed
      - Vulnerability scan complete
      
  kubernetes:
    - EKS clusters
    - GKE clusters
    events:
      - Deployment updated
      - Pod unhealthy
      - Resource quota exceeded
      
  observability:
    - Prometheus
    - Grafana
    - Jaeger
    data:
      - Metrics per service
      - SLO status
      - Trace data
      
  security:
    - Vault
    - OPA
    - Trivy
    enforcement:
      - Secret injection
      - Policy validation
      - Image scanning

---

📊 Architecture Patterns

Pattern 1: GitOps-Centric

Everything is defined in Git, changes through pull requests.

Pros: Audit trail, review process, rollback via git Cons: Learning curve, everything must be declarative

Pattern 2: API-Centric

Platform API orchestrates all operations.

Pros: Simpler UX, abstraction flexibility Cons: API becomes critical path, less git-native

Pattern 3: Hybrid

Combine GitOps for runtime with API for orchestration.

This is the recommended pattern for most organizations.

---

🔒 Security Considerations

Security Architecture Layers

┌─────────────────────────────────────────────────────────────────┐
│                     IDENTITY & ACCESS                            │
│            SSO, RBAC, Service Accounts, Workload Identity       │
├─────────────────────────────────────────────────────────────────┤
│                      SECRETS MANAGEMENT                          │
│              Vault, External Secrets, SOPS, Sealed Secrets      │
├─────────────────────────────────────────────────────────────────┤
│                      POLICY ENFORCEMENT                          │
│             OPA/Gatekeeper, Kyverno, Admission Controllers      │
├─────────────────────────────────────────────────────────────────┤
│                     SUPPLY CHAIN SECURITY                        │
│          Image Signing, SBOM, Vulnerability Scanning            │
├─────────────────────────────────────────────────────────────────┤
│                      NETWORK SECURITY                            │
│            Service Mesh, Network Policies, mTLS                 │
└─────────────────────────────────────────────────────────────────┘

Security Integration Example

# Example: Kyverno policy for platform standards
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: platform-standards
spec:
  validationFailureAction: enforce
  rules:
    - name: require-labels
      match:
        resources:
          kinds:
            - Deployment
      validate:
        message: "Deployments must have team and service labels"
        pattern:
          metadata:
            labels:
              team: "?*"
              service: "?*"
              
    - name: deny-privileged
      match:
        resources:
          kinds:
            - Pod
      validate:
        message: "Privileged containers are not allowed"
        pattern:
          spec:
            containers:
              - securityContext:
                  privileged: false
                  
    - name: require-resource-limits
      match:
        resources:
          kinds:
            - Deployment
      validate:
        message: "Resource limits are required"
        pattern:
          spec:
            template:
              spec:
                containers:
                  - resources:
                      limits:
                        memory: "?*"
                        cpu: "?*"

---

📈 Evolution Path

Platform Maturity Model

Level	Characteristics	Typical Timeline
Level 0: None	Manual processes, tickets	Starting point
Level 1: Basic	Templates, basic CI/CD	3-6 months
Level 2: Standardized	Developer portal, self-service	6-12 months
Level 3: Automated	Full self-service, policies as code	12-18 months
Level 4: Optimized	Insights, recommendations, AI-assist	18+ months

Growth Pattern

---

📝 Summary

A well-architected Internal Developer Platform is built on layers—from developer-facing interfaces down to infrastructure automation. Success comes from starting with a Thinnest Viable Platform and growing based on actual developer needs.

Key Takeaways

Concept	Description
Five Planes	Developer Control, Integration, Resource, Observability, Security
TVP	Start with minimal viable platform, grow based on feedback
Build vs Buy	Build glue, buy/use commodity components
GitOps + API	Hybrid pattern recommended for most organizations
Security First	Integrate security into every layer

---

🔗 References

• CNCF Platforms White Paper

• Backstage.io Documentation

• Crossplane Documentation

• Humanitec Reference Architecture

• Microsoft Platform Engineering

---

➡️ Next Steps

Continue to Article 5: Developer Self-Service to learn how to design effective self-service experiences that developers will actually use.