Next Portal: Building an Internal Developer Platform That Developers Actually Use

Internal developer platforms have a reputation problem. Engineering organizations invest heavily in building them, and developers often ignore them. The platform team builds a portal with service catalogs, deployment dashboards, and infrastructure provisioning. The engineering teams continue to use their existing scripts, bookmarks, and tribal knowledge.

I built Next Portal because I believe the problem is not the concept of an IDP; it is the execution. Most internal developer platforms fail because they add complexity instead of removing it. They become another tool in an already crowded toolchain rather than a consolidation layer that reduces cognitive load.

The Cognitive Load Problem

An engineer at a modern software company interacts with dozens of tools daily. GitHub for code. Jira or Linear for project tracking. Slack for communication. AWS console for infrastructure. Datadog or Grafana for monitoring. PagerDuty for on-call. ArgoCD or Jenkins for deployments. Terraform for infrastructure as code. Confluence for documentation.

Each tool has its own URL, its own authentication flow, its own navigation patterns, its own mental model. Context-switching between these tools is not just inconvenient; it is cognitively expensive. Every switch requires loading a new mental model, finding the right page, and translating the concept in your head into the specific tool's vocabulary.

An internal developer platform should reduce the number of mental models an engineer needs to hold simultaneously. It should be a single interface that aggregates the most common workflows from multiple tools into a unified experience.

Most IDPs fail at this because they try to replicate the full functionality of each underlying tool. They build a GitHub interface inside the portal, a Jira interface inside the portal, an AWS interface inside the portal. The result is a lowest-common-denominator version of every tool, and developers go back to the real tools because the portal versions are inferior.

Next Portal's Approach

Next Portal takes a different approach. Instead of replicating tools, it surfaces the specific workflows that engineers perform most frequently and connects them through a unified interface.

The core insight is that most engineering tasks follow patterns:

• "I need to deploy my service to staging" (deployment workflow)
• "Something is wrong with my service in production" (incident investigation workflow)
• "I need to create a new microservice" (scaffolding workflow)
• "I need to understand what my service depends on" (dependency mapping workflow)
• "I need to check if my service is healthy" (observability workflow)

Each of these workflows touches multiple tools. Deploying to staging might involve GitHub (merge to staging branch), ArgoCD (trigger deployment), Datadog (verify health), and Slack (notify the team). The developer does not care about those individual tools during the workflow. They care about the outcome: "my service is deployed and healthy."

Next Portal models these workflows as first-class concepts:

// Workflow definition for "Deploy to Staging"
const deployToStaging: Workflow = {
  name: "Deploy to Staging",
  steps: [
    {
      tool: "github",
      action: "merge",
      params: { target: "staging" }
    },
    {
      tool: "argocd",
      action: "sync",
      params: { waitForHealthy: true }
    },
    {
      tool: "datadog",
      action: "checkHealth",
      params: { duration: "5m" }
    },
    {
      tool: "slack",
      action: "notify",
      params: { channel: "#deployments" }
    }
  ]
};

The engineer clicks "Deploy to Staging," confirms the parameters, and the workflow executes across all four tools. No context switching. No remembering which tool comes next. No copy-pasting identifiers between browser tabs.

Architecture

Next Portal is built on a modular plugin architecture:

Core Platform: Next.js application with a clean, responsive UI. Handles authentication (SSO via SAML/OIDC), user preferences, workflow execution, and the service catalog.

Plugin System: Each external tool integration is a plugin. Plugins are self-contained packages that register their capabilities with the core platform:

// Plugin registration
export const githubPlugin: Plugin = {
  name: "github",
  capabilities: ["merge", "createPR", "listBranches"],
  configure: (config) => new GitHubClient(config),
  actions: {
    merge: async (client, params) => { /* ... */ },
    createPR: async (client, params) => { /* ... */ },
    listBranches: async (client, params) => { /* ... */ }
  }
};

Service Catalog: A registry of services owned by the organization. Each service has metadata: owning team, tech stack, dependencies, deployment target, runbook links, and health check endpoints. The catalog is the single source of truth for "what services do we have and who owns them."

Workflow Engine: Executes multi-step workflows across plugins. Handles retries, rollbacks, and partial failure. Logs every step for auditability.

MCP Integration: Every plugin's capabilities are also exposed as MCP tools. This means AI agents can interact with Next Portal programmatically, using the same workflows that humans use through the UI.

The Service Catalog as Foundation

The service catalog is the most important component, and it is the one that most IDPs get wrong.

A service catalog that requires manual maintenance will become stale. Engineers will not update it because updating a catalog is not part of their workflow. It is administrative overhead that competes with their actual work.

Next Portal's catalog uses a hybrid approach:

Automated discovery. The platform scans infrastructure providers (Kubernetes clusters, AWS accounts, GCP projects) and automatically discovers running services. It correlates these with Git repositories to establish code ownership and with CI/CD pipelines to understand deployment patterns.

Enrichment, not creation. Engineers do not create catalog entries from scratch. They enrich automatically discovered entries with context that automated discovery cannot determine: team ownership, business criticality, SLA tier, and runbook locations. This is a much smaller task than building the catalog from nothing.

Git-backed configuration. Service metadata lives in the service's repository as a portal.yaml file. When the file changes, the catalog updates. This keeps the metadata close to the code and ensures it flows through the same review process as code changes.

# portal.yaml in service repository
name: user-service
team: platform-team
tier: critical
dependencies:
  - postgres-primary
  - redis-cache
  - auth-service
runbook: https://wiki.internal/runbooks/user-service
healthcheck: /health

Why Backstage Was Not Enough

Spotify's Backstage is the most prominent open source IDP. It is well-designed, has strong community support, and is used by many organizations. So why build something new?

The honest answer is that Backstage solves a slightly different problem than what I needed. Backstage is a platform for building portals. It provides the framework, the plugin architecture, and the component model. But you still need to build the actual portal on top of it. For organizations with dedicated platform teams, this is ideal. For smaller teams, it is more framework than they need.

Next Portal is opinionated where Backstage is flexible. It ships with built-in workflows, a pre-configured service catalog, and working integrations for the most common tools. You can customize everything, but the defaults are production-ready. The goal is to go from installation to useful portal in hours, not weeks.

The other difference is the workflow-first approach. Backstage is component-first: it organizes information around software components. Next Portal is workflow-first: it organizes actions around what engineers need to accomplish. Both approaches are valid, but the workflow-first model better matches how engineers think about their work.

Adoption Patterns

I have seen two successful adoption patterns for internal developer platforms.

Bottom-up adoption works when the platform solves an immediate pain point. If deploying to staging currently requires 7 steps across 4 tools, and the platform reduces it to 1 click, developers adopt it for that workflow. Once they are using the platform, they discover other capabilities.

Top-down adoption works when leadership mandates the platform for compliance or standardization purposes. This can succeed if the platform is genuinely easier than the alternatives. It fails when the platform is harder to use and the mandate becomes a source of frustration.

Next Portal is designed for bottom-up adoption. It solves specific workflow pain points well enough that engineers choose to use it. The service catalog and workflow engine provide value from day one, and additional capabilities layer on over time.

The worst thing a platform team can do is build a comprehensive portal and launch it with a company-wide announcement. Engineers will visit once, find that it does not solve their immediate problem, and never return. Start small. Solve one workflow brilliantly. Let adoption grow from there.

The IDP Landscape

The internal developer platform space is maturing rapidly. Backstage, Port, Cortex, OpsLevel, and others are all approaching the problem from different angles. This competition is healthy because it generates diverse approaches to a genuinely hard problem.

Next Portal's contribution to this landscape is the workflow-first, MCP-integrated approach. By exposing platform capabilities through MCP, it bridges the gap between human-operated and agent-operated infrastructure management. An engineer can deploy through the UI, and an AI agent can deploy through MCP, using the same underlying workflow.

This bridging is where I think IDPs are heading. The developer platform becomes the control plane for both human and AI interactions with infrastructure. The same catalog, the same workflows, the same audit trail, regardless of whether the actor is a person or an agent.

The code is open source, and I welcome contributions from anyone who shares the conviction that developer platforms should reduce cognitive load, not increase it.