Platform Engineering Internal Developer Portal Guide

## ROLE

You are a platform engineering leader who has built internal developer platforms (IDPs) that serve hundreds of engineers. You have deployed Backstage-based developer portals, designed golden path templates that reduce new service onboarding from weeks to minutes, and built self-service infrastructure provisioning that eliminates ticket-based workflows. You understand that platform engineering is a product discipline — your users are developers, and adoption depends on delivering genuine developer experience improvements rather than enforcing compliance through gates.

## OBJECTIVE

Design and implement an internal developer platform and portal for [ORGANIZATION: startup with 20-50 engineers / mid-size with 50-200 engineers / enterprise with 200+ engineers / custom] that currently experiences [PAIN POINTS: slow onboarding of new services / inconsistent infrastructure configurations / lack of service ownership visibility / manual environment provisioning / scattered documentation / no standardized CI/CD / difficulty discovering internal APIs / custom]. The platform targets [INFRASTRUCTURE: Kubernetes / cloud-managed services / hybrid / custom] running on [CLOUD: AWS / Azure / GCP / multi-cloud].

## TASK: INTERNAL DEVELOPER PLATFORM DESIGN

### Platform Vision & Principles

Define the platform engineering charter for [ORGANIZATION]:

**Platform as a Product:** The IDP is an internal product. Its success is measured by developer adoption (not mandated usage), time-to-production for new services, developer satisfaction (NPS or CSAT), and reduction in platform team toil (tickets eliminated). Define [NUMBER: 3-5] platform principles: self-service by default (no tickets for standard operations), golden paths not golden cages (recommended patterns, not enforced constraints), composable building blocks (developers can mix and match platform capabilities), and [CUSTOM PRINCIPLES based on ORGANIZATION culture].

**Team Topology:** Define the platform team structure using Team Topologies model. The platform team operates as an [INTERACTION MODE: X-as-a-Service (provide capabilities via API/portal) / facilitating (help stream-aligned teams adopt patterns) / hybrid]. Size the team at [RATIO: 1 platform engineer per 10-15 application developers] for [ORGANIZATION]. Define the interface boundary: platform team owns everything below the application layer (infrastructure, CI/CD, observability, security scanning) while application teams own their service code, business logic, and feature delivery.

### Developer Portal (Backstage) Implementation

Deploy and configure [PORTAL: Backstage / Port / Cortex / OpsLevel / custom] as the central developer experience layer:

**Software Catalog Setup:**
Configure the software catalog to discover and register all services, libraries, APIs, and infrastructure components. Define the entity model:
- **Component:** Individual deployable service with: name, description, owner (team), lifecycle stage (experimental/production/deprecated), system membership, tech stack tags, and links to repo, CI/CD, monitoring, and documentation
- **System:** Logical grouping of components that deliver a business capability (e.g., "Checkout System" containing cart-service, payment-service, order-service)
- **API:** Machine-readable API definitions (OpenAPI/AsyncAPI/gRPC/GraphQL) registered in the catalog with version, owner, and consumer list
- **Resource:** Infrastructure dependencies (databases, caches, queues) linked to consuming components

Provide the catalog-info.yaml template that every team must include in their repository root. Configure [DISCOVERY: GitHub/GitLab autodiscovery / LDAP team sync / custom entity provider] to automatically populate and keep the catalog current. Set up entity validation that flags: services without owners, APIs without documentation, components with outdated lifecycle stages, and orphaned resources.

**TechDocs Integration:**
Configure TechDocs to render markdown documentation from each service's repository directly in the portal. Define the documentation standard every service must meet: README with service purpose and architecture, API documentation (auto-generated from OpenAPI spec), runbook for on-call engineers, ADRs (Architecture Decision Records) for significant technical choices, and onboarding guide for new team members. Set up a docs-like-code pipeline that builds and publishes documentation on every merge to main.

### Golden Path Templates (Software Templates)

Design [NUMBER: 4-6] software templates that codify organizational best practices:

**Template 1: Standard Microservice**
Scaffolds a production-ready [LANGUAGE: Go / Java / Python / Node.js / .NET] microservice with: project structure following [ORGANIZATION] conventions, Dockerfile (multi-stage, non-root, health check), Helm chart or Kubernetes manifests, CI/CD pipeline ([TOOL: GitHub Actions / GitLab CI]) with build, test, scan, and deploy stages, observability instrumentation (metrics endpoint, structured logging, trace context propagation), catalog-info.yaml pre-filled with creator's team and system, and README template with required sections.

Input parameters the developer provides: service name, owning team, target namespace, database needed (yes/no + type), cache needed (yes/no), message queue integration (yes/no), and initial resource sizing (small/medium/large).

The template execution should: create the repository from template, configure branch protection rules, register the service in the software catalog, provision the CI/CD pipeline, create initial Kubernetes namespace and RBAC, set up monitoring dashboards from template, and output a fully working service endpoint within [TIME: 5-15 minutes].

**Template 2: Frontend Application**
Scaffolds a [FRAMEWORK: React / Next.js / Vue / Angular] application with: component library integration ([DESIGN SYSTEM: custom / Material UI / Chakra / custom]), CDN configuration, feature flag SDK, analytics instrumentation, E2E test framework, and deployment pipeline targeting [HOSTING: Vercel / CloudFront + S3 / Azure Static Web Apps / custom].

**Template 3: Data Pipeline**
Scaffolds a data processing pipeline with: [TOOL: Airflow DAG / Spark job / dbt project / Prefect flow / custom] boilerplate, data quality checks, schema registry integration, monitoring and alerting, and deployment to [DATA PLATFORM: Databricks / EMR / Dataflow / custom].

**Template 4: Infrastructure Module**
Scaffolds a reusable Terraform/Pulumi module for [RESOURCE: database / cache / queue / storage bucket / networking] with: input variables following [ORGANIZATION] naming and tagging standards, security best practices baked in (encryption, access control, logging), cost estimation via [TOOL: Infracost / custom], and automated testing with [TOOL: Terratest / checkov / custom].

Provide [NUMBER: 1-2] additional templates specific to [ORGANIZATION]'s technology stack and common patterns.

### Self-Service Infrastructure Provisioning

Build the self-service layer that eliminates infrastructure provisioning tickets:

**Resource Catalog:** Define the menu of self-service resources developers can provision through the portal. For each resource, specify: what it provisions (e.g., PostgreSQL database with read replica, Redis cluster, S3 bucket with lifecycle policy), sizing options (small/medium/large with specific specs and cost estimate), environment targeting (dev/staging/prod with appropriate guardrails), approval workflow (dev: auto-approved, staging: auto-approved, prod: requires [APPROVER: team lead / platform team / security review]), and provisioning time SLA ([TIME: 2-5 minutes for dev, 15-30 minutes for prod]).

**Implementation:** Use [PROVISIONER: Crossplane / Terraform Cloud / Pulumi Automation API / AWS Service Catalog / custom Kubernetes operator] to execute provisioning. The flow: developer fills form in portal -> validation -> approval (if needed) -> provisioner creates infrastructure -> connection details stored in [SECRETS: Vault / Kubernetes secrets / cloud secrets manager] -> developer's application automatically configured via [METHOD: external secrets operator / environment injection / service binding].

**Guardrails & Governance:** Implement policy-as-code using [TOOL: OPA/Gatekeeper / Kyverno / Sentinel / Azure Policy] that enforces: resource naming conventions, mandatory tags (owner, cost-center, environment), size limits per environment (no production-sized databases in dev), security baselines (encryption at rest, no public access by default), and budget limits per team per environment. Policies should enable, not block — provide clear error messages with remediation guidance.

### Developer Experience Metrics (DORA+)

Measure platform effectiveness using these metrics:

**DORA Metrics:** deployment frequency (target: [FREQUENCY: daily / weekly] per team), lead time for changes (target: [TIME: hours / days] from commit to production), change failure rate (target: below [PERCENTAGE: 5% / 10% / 15%]), and mean time to recovery (target: below [TIME: 1 hour / 4 hours]).

**Platform-Specific Metrics:** time to first deployment for new service (target: under [TIME: 1 day / 1 week]), self-service adoption rate (percentage of provisioning done without tickets, target: [PERCENTAGE: 80%+]), template usage rate (percentage of new services using golden paths), developer NPS (quarterly survey, target: [SCORE: 30+ / 50+]), and ticket volume trend for platform team (should decrease over time).

**Implementation:** Collect metrics from [SOURCES: GitHub/GitLab API for deployment frequency and lead time, incident management tool for MTTR, CI/CD system for change failure rate, portal analytics for self-service adoption]. Build a Grafana or [TOOL: custom] dashboard that the platform team reviews weekly and shares with engineering leadership monthly. Use metrics to prioritize platform roadmap: if time-to-first-deployment is high, invest in templates; if change failure rate is high, invest in testing and canary infrastructure; if self-service adoption is low, investigate UX friction and missing capabilities.