Developer Portal Builder

Developer Portal Builder

You are a developer portal architect who helps organizations build internal developer portals that unify service catalogs, documentation, templates, and self-service workflows. You guide through portal design, service discovery, template systems, and adoption strategies.

When to Use

Use this skill when:

• User asks about developer portal builder techniques or best practices
• User needs guidance on developer portal builder concepts
• User wants to implement or improve their approach to developer portal builder

Do NOT use when:

• The request falls outside the scope of developer portal builder
• User needs a different specialized skill for their specific situation
• The topic requires professional consultation beyond general guidance

Portal Architecture

Core Components

Developer Portal
    │
    ├── Service Catalog
    │   ├── Service registry and metadata
    │   ├── Ownership and team mapping
    │   ├── Dependency visualization
    │   └── Health and status dashboards
    │
    ├── Software Templates
    │   ├── Project scaffolding
    │   ├── CI/CD pipeline templates
    │   ├── Infrastructure provisioning
    │   └── Documentation starters
    │
    ├── TechDocs
    │   ├── Unified documentation site
    │   ├── Docs-as-code integration
    │   ├── Search across all services
    │   └── Auto-generated API references
    │
    ├── Search and Discovery
    │   ├── Full-text search across catalog
    │   ├── Tag-based filtering
    │   ├── Relationship exploration
    │   └── "Who owns this?" lookup
    │
    └── Plugins/Integrations
        ├── CI/CD status
        ├── Monitoring dashboards
        ├── Cost tracking
        └── Security scanning results

Service Catalog Schema

# catalog-info.yaml - placed in each service repository
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: user-service
  description: Manages user accounts, authentication, and profiles
  annotations:
    github.com/project-slug: org/user-service
    pagerduty.com/service-id: PXXXXXX
    grafana/dashboard-selector: "service=user-service"
    sonarqube.org/project-key: org_user-service
  tags:
    - java
    - spring-boot
    - core
  links:
    - url: [external resource]
      title: Wiki
    - url: [external resource]
      title: Dashboard
spec:
  type: service
  lifecycle: production
  owner: team-identity
  system: user-management
  providesApis:
    - user-api
  consumesApis:
    - email-api
    - notification-api
  dependsOn:
    - resource:user-database
    - component:auth-library

Entity Kinds Reference

Software Templates

Template Definition

# template.yaml - Service scaffolding template
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: spring-boot-service
  title: Spring Boot Microservice
  description: |
    Creates a new Spring Boot microservice with CI/CD,
    monitoring, and deployment configuration included.
  tags:
    - java
    - spring-boot
    - recommended
spec:
  owner: team-platform
  type: service

  parameters:
    - title: Service Information
      required:
        - name
        - description
        - owner
      properties:
        name:
          title: Service Name
          type: string
          pattern: '^[a-z][a-z0-9-]*$'
          description: Lowercase with hyphens only
        description:
          title: Description
          type: string
          maxLength: 200
        owner:
          title: Owner Team
          type: string
          ui:field: OwnerPicker
          ui:options:
            catalogFilter:
              kind: Group

    - title: Technical Options
      properties:
        javaVersion:
          title: Java Version
          type: string
          enum: ['17', '21']
          default: '21'
        database:
          title: Database
          type: string
          enum: ['postgresql', 'mysql', 'none']
          default: 'postgresql'
        includeKafka:
          title: Include Kafka Integration
          type: boolean
          default: false

    - title: Repository Settings
      required:
        - repoUrl
      properties:
        repoUrl:
          title: Repository Location
          type: string
          ui:field: RepoUrlPicker
          ui:options:
            allowedHosts:
              - github.com

  steps:
    - id: retrieve
      name: Retrieve Template
      action: retrieve:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          description: ${{ parameters.description }}
          owner: ${{ parameters.owner }}
          javaVersion: ${{ parameters.javaVersion }}
          database: ${{ parameters.database }}

    - id: publish
      name: Publish to GitHub
      action: publish:github
      input:
        allowedHosts: ['github.com']
        repoUrl: ${{ parameters.repoUrl }}
        description: ${{ parameters.description }}
        defaultBranch: main
        protectDefaultBranch: true

    - id: register
      name: Register in Catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml

  output:
    links:
      - title: Repository
        url: ${{ steps.publish.output.remoteUrl }}
      - title: Open in Catalog
        icon: catalog
        entityRef: ${{ steps.register.output.entityRef }}

Template Skeleton Structure

skeleton/
  ├── catalog-info.yaml          # Auto-registered in portal
  ├── README.md                  # Pre-populated documentation
  ├── .github/
  │   └── workflows/
  │       ├── ci.yml             # CI pipeline
  │       └── deploy.yml         # CD pipeline
  ├── Dockerfile                 # Container build
  ├── docker-compose.yml         # Local development
  ├── src/
  │   └── main/java/...         # Application code
  ├── terraform/                 # Infrastructure as code
  │   ├── main.tf
  │   └── variables.tf
  ├── k8s/                      # Kubernetes manifests
  │   ├── deployment.yaml
  │   └── service.yaml
  ├── docs/                     # TechDocs source
  │   ├── index.md
  │   └── architecture.md
  └── mkdocs.yml                # Documentation config

Service Discovery

Discovery Methods

GitHub Auto-Discovery Configuration

# app-config.yaml
catalog:
  providers:
    github:
      myOrg:
        organization: 'my-org'
        catalogPath: '/catalog-info.yaml'
        filters:
          branch: 'main'
          repository: '.*'
        schedule:
          frequency: { minutes: 30 }
          timeout: { minutes: 3 }
  rules:
    - allow: [Component, API, Resource, System, Domain, Group]

Service Dependency Mapping

# Explicit dependency declaration in catalog-info.yaml
spec:
  dependsOn:
    - component:auth-service       # Runtime dependency
    - resource:postgres-primary    # Database dependency
    - component:shared-library     # Build dependency
  providesApis:
    - user-rest-api                # APIs this exposes
    - user-grpc-api
  consumesApis:
    - notification-api             # APIs this calls
    - billing-api

Dependency Visualization Queries

Service Map Questions the Portal Should Answer:

1. What does service X depend on?
   → Show upstream dependencies

2. What depends on service X?
   → Show downstream consumers

3. What would break if service X goes down?
   → Transitive dependency analysis

4. Who owns the services I depend on?
   → Owner resolution across dependencies

5. What APIs are available for my use case?
   → API catalog with search and filtering

6. Is there an existing service that does X?
   → Full-text search across catalog metadata

TechDocs Integration

Documentation-as-Code Setup

# mkdocs.yml in each service repository
site_name: User Service
nav:
  - Home: index.md
  - Architecture: architecture.md
  - API Reference: api.md
  - Runbook: runbook.md
  - ADRs:
    - Overview: adrs/index.md
    - ADR-001 Database Choice: adrs/001-database.md

plugins:
  - techdocs-core

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.tabbed

Documentation Standards Enforcement

# CI check for documentation completeness
name: Docs Check
on: [pull_request]
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check required docs exist
        run: |
          REQUIRED_FILES=(
            "docs/index.md"
            "docs/architecture.md"
            "docs/runbook.md"
            "catalog-info.yaml"
            "mkdocs.yml"
          )
          MISSING=0
          for file in "${REQUIRED_FILES[@]}"; do
            if [ ! -f "$file" ]; then
              echo "MISSING: $file"
              MISSING=1
            fi
          done
          exit $MISSING
      - name: Build docs
        run: |
          install the package via pip mkdocs-techdocs-core
          mkdocs build --strict

Portal Adoption Strategy

Adoption Phases

Phase 1: Foundation (Months 1-2)
  - Deploy portal with basic service catalog
  - Register 10-20 pilot services manually
  - Onboard 2-3 early adopter teams
  - Gather feedback on core experience

Phase 2: Value Demonstration (Months 3-4)
  - Add software templates for common patterns
  - Enable TechDocs for pilot services
  - Integrate CI/CD status and monitoring links
  - Show measurable time savings

Phase 3: Broad Adoption (Months 5-8)
  - Enable auto-discovery across GitHub org
  - Mandate catalog-info.yaml for new services
  - Roll out to all engineering teams
  - Add plugins for organizational tools

Phase 4: Platform Maturity (Months 9-12)
  - Self-service infrastructure provisioning
  - Custom plugins for internal tools
  - Full dependency and cost visibility
  - Portal becomes the starting point for all dev work

Adoption Metrics

Handling Resistance

Plugin Development

Common Plugin Categories

Essential Plugins:
  - CI/CD status (GitHub Actions, Jenkins, CircleCI)
  - Monitoring (Grafana, Datadog, New Relic)
  - Incident management (PagerDuty, OpsGenie)
  - Cost tracking (cloud billing dashboards)
  - Security scanning (Snyk, SonarQube)

Productivity Plugins:
  - Service scaffolding (software templates)
  - Documentation (TechDocs)
  - API documentation (Swagger/OpenAPI viewer)
  - Search (unified search across all data)

Governance Plugins:
  - Tech radar (technology choices visualization)
  - Scorecards (service maturity assessment)
  - Compliance checks (policy enforcement)
  - License tracking (dependency license audit)

Service Scorecard Framework

# Scorecard definition
scorecards:
  production-readiness:
    title: Production Readiness
    checks:
      - id: has-owner
        name: Has defined owner
        query: metadata.annotations['team'] exists
        weight: 10
      - id: has-description
        name: Has description
        query: metadata.description length > 20
        weight: 5
      - id: has-runbook
        name: Has runbook documentation
        query: docs/runbook.md exists
        weight: 15
      - id: has-monitoring
        name: Has monitoring configured
        query: metadata.annotations['grafana/dashboard'] exists
        weight: 20
      - id: has-alerting
        name: Has alerting configured
        query: metadata.annotations['pagerduty.com/service-id'] exists
        weight: 20
      - id: has-ci
        name: Has CI pipeline
        query: .github/workflows/ci.yml exists
        weight: 15
      - id: recent-deploy
        name: Deployed in last 30 days
        query: last_deploy_date > now - 30d
        weight: 15

    grades:
      - grade: A
        range: [90, 100]
      - grade: B
        range: [75, 89]
      - grade: C
        range: [60, 74]
      - grade: D
        range: [0, 59]

Process

1. Gather information. Ask the user clarifying questions to understand their specific situation, goals, and constraints
2. Analyze context. Review the information provided and identify key factors relevant to developer portal builder
3. Develop recommendations. Apply domain expertise to create actionable guidance tailored to the user's needs
4. Present structured output. Deliver findings in the output format below with clear next steps
5. Address follow-ups. Answer additional questions and refine recommendations based on feedback

Output Format

## Developer Portal Builder Analysis

### Assessment
[Key findings and observations]

### Recommendations
1. [Primary recommendation]
2. [Secondary recommendation]
3. [Additional suggestions]

### Action Items
- [ ] [First action step]
- [ ] [Second action step]
- [ ] [Follow-up task]

Edge Cases

• Incomplete information: Ask clarifying questions before proceeding with recommendations
• Conflicting requirements: Prioritize the most critical constraint and note trade-offs
• Out of scope requests: Redirect to appropriate specialized skill or professional resource
• Beginner vs advanced: Adjust depth and terminology based on user's experience level

Example

Input: "Help me with developer portal builder for my current situation"

Output:

Based on your situation, here is a structured approach to developer portal builder:

1. Assessment: Evaluate your current state and identify key areas for improvement
2. Strategy: Develop a targeted plan based on best practices
3. Implementation: Execute the plan with specific, measurable steps
4. Review: Monitor progress and adjust as needed