Platform Developer Portal
Your engineers shouldn't need to ask Slack where to find the API docs. This developer portal gives your organization an internal service catalog, auto-generated API documentation, onboarding guides for new hires, and self-service infrastructure templates — all in Markdown and YAML you can host anywhere. It reduces "where do I find X?" questions to near-zero and cuts new engineer onboarding time from weeks to days.
Key Features
- Service catalog schema — YAML-based service registry with ownership, dependencies, SLOs, runbook links, and repository URLs
- API documentation templates — OpenAPI-compatible templates with request/response examples and authentication guides
- New hire onboarding guide — Day 1 through Day 90 structured checklist covering tools, access, codebase orientation, and first deploy
- Self-service infra templates — Cookiecutter-style project scaffolds for new microservices, Lambda functions, and cron jobs
- Architecture decision records (ADRs) — Template and index for recording technical decisions
- Team topology map — YAML schema for team ownership and escalation paths
- Search-friendly structure — Consistent frontmatter for static site generators (MkDocs, Hugo)
Quick Start
unzip platform-developer-portal.zip && cd platform-developer-portal/
# Generate a new service catalog entry
python3 src/platform_developer_portal/core.py add-service \
--name "payment-service" --team "payments" --tier 1 \
--repo "https://github.example.com/org/payment-service"
# Scaffold a new microservice
python3 src/platform_developer_portal/core.py scaffold \
--template microservice --name "notification-service" --output ./generated/
Architecture / How It Works
CATALOG → DOCS → ONBOARD → SCAFFOLD
- Catalog — Every service registered in YAML with standardized fields. Teams update via pull requests.
- Docs — API specs, ADRs, and guides live as Markdown alongside the catalog.
- Onboard — Structured checklists guide new engineers from "I have a laptop" to "I shipped my first PR."
- Scaffold — Project templates let any engineer spin up a new service with organizational standards baked in.
Usage Examples
Service Catalog Entry
# catalog/services/payment-service.yaml
apiVersion: portal/v1
kind: Service
metadata:
name: payment-service
team: payments
tier: 1 # 1=critical, 2=important, 3=internal
lifecycle: production
spec:
description: "Processes customer payments via Stripe"
repository: https://github.example.com/org/payment-service
language: Python
contacts:
owner: payments-team@example.com
slack: "#payments-eng"
dependencies:
- name: user-service
type: sync
- name: notification-service
type: async
slos:
availability: 99.95%
latency_p99: 200ms
links:
runbook: /runbooks/payment-service.md
dashboard: https://grafana.example.com/d/payments
api_docs: /docs/api/payment-service.md
Architecture Decision Record Template
# ADR-{number}: {Title}
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-{n}
**Date:** YYYY-MM-DD
## Context
What is the issue motivating this decision?
## Decision
What change are we making?
## Consequences
What becomes easier or harder? What are the risks?
Onboarding Checklist Generator
from platform_developer_portal.core import OnboardingTracker
tracker = OnboardingTracker(new_hire="jane.doe@example.com")
tracker.add_tasks("day_1", [
"Laptop setup and OS configuration",
"GitHub org access request",
"Slack channels: #engineering, #incidents",
"VPN and SSH key setup",
"Read: Architecture Overview doc",
])
tracker.add_tasks("week_1", [
"Complete local dev environment setup",
"Clone and build the team's primary service",
"Ship: First PR (starter issue from backlog)",
])
tracker.export("onboarding/jane_doe.yaml")
Configuration
# config.example.yaml
portal:
title: "Acme Corp Developer Portal"
base_url: https://portal.example.com
catalog:
schema_version: v1
required_fields: [name, team, tier, repository, contacts.owner]
validation: strict
scaffolding:
templates_dir: ./templates/scaffolds
available_templates: [microservice, lambda-function, cron-job, library]
defaults:
language: python
ci: github-actions
onboarding:
buddy_assignment: automatic
checklist_source: ./templates/onboarding/
Best Practices
- Make the catalog the single source of truth — if it's not in the catalog, it doesn't exist. Enforce this culturally.
- Automate catalog validation in CI — reject PRs missing required fields
- Keep onboarding docs current — assign quarterly review to the most recent hire
- Use ADRs for non-trivial decisions — future engineers will thank you
-
Add portal links to your Slack bot —
@portal payment-servicereturns the catalog entry
Troubleshooting
MkDocs build fails with "page not found" errors
Check that all internal links use relative paths, not absolute URLs. Run mkdocs build --strict to catch broken links before deploying.
Service catalog validation rejects valid entries
Review the required_fields list in config. If you added new required fields, existing entries need updating. Use --validation permissive temporarily during migration.
Scaffold generates wrong project name
Ensure the --name contains only lowercase letters, numbers, and hyphens.
New hire checklist not sending notifications
Verify notify_manager: true and that the manager's email is set in the team YAML.
This is 1 of 7 resources in the SRE Platform Pro toolkit. Get the complete [Platform Developer Portal] with all files, templates, and documentation for $49.
Or grab the entire SRE Platform Pro bundle (7 products) for $89 — save 30%.
Top comments (0)