Platform EngineeringWeb portal, command-line tool, phone view28 weeks SprintConceptual Case Study - Proposed Solution

Shipyard

An Internal Developer Platform: Service Catalog, Environments, Policy Checks and Cloud Cost

A concept study: we worked up this product, its architecture and its screens as an example of how we would approach it. The screens use fictional demo data and are design concepts, not screenshots of a live product, and this is not a client project.

Shipyard - Engineering Case Study Cover
Concept
A design study, not a live product
Fictional
Demo data on every screen
28 weeks
Estimated build time

About the Project

Shipyard is a design concept for the portal a platform team builds for its own developers, such as a company with a few hundred services on Kubernetes and a public cloud. It sits on top of Git, the build system and the cluster. A developer can find a service, create an environment, ship a change and see its cost and health without filing a ticket.

Git stays the source of truth. A service is described in a file in its repository, and every portal action becomes a commit or a pull request that someone can review and revert. The catalog database can be thrown away and rebuilt from those files. Policy rules also live in Git and run at merge, at deploy and inside the cluster, with a plain-language reason and a suggested fix for each failure.

Cost, ownership and readiness sit on the same service page as deploys. A platform engineer can try a new rule as a dry run against every service first. AI is offered only as read-only help: it explains a failed pipeline or policy result and proposes a fix as a pull request for a person to review.

Why This Matters Now

Market, rule and technology context for this kind of product, checked on 16 November 2026. Each item names its source.

Requirements & Objectives

  • Build a catalog from descriptor files in Git, with owner, repository, language, on-call rota, runbook link, dependencies and lifecycle stage for every service.
  • Create a new service from a vetted template that opens a repository with its pipeline, deploy config, dashboards and alerts already wired.
  • Create preview environments for each pull request, plus shared staging and production, with a time to live, quotas and automatic teardown.
  • Show build, test, scan, policy, deploy and approval for each service, with rollbacks and a change history for every environment.
  • Run policy checks at merge, at deploy and inside the cluster, and explain each failure with the reason and a suggested fix.
  • Show cloud cost by team, service and environment, with budgets, idle resources and an unallocated bucket that stays visible.
  • Score each service on readiness and list services on retiring runtimes or old Kubernetes APIs, each with an owner and a due date.
  • Support single sign-on, team roles, a second approver for tier 1 production deploys and an audit log of every portal action.

The Engineered Solution

1Git as the source of truth

Descriptors, environment config and policy live in repositories. The portal reads them and writes changes back as pull requests, so nothing important hides in a database nobody can review.

2Golden paths with built-in checks

A few templates cover a web service, a worker and a scheduled job. Each one arrives with build, deploy, monitoring and policy checks, so the safe route is also the quick one.

3Policy that explains itself

Rules run at merge, deploy and in the cluster. A failed check names the cause and shows the fix as a diff, and a new rule starts in warn mode with a dry run across every service.

4Cost next to the service

Required owner and cost labels join the billing export to in-cluster use. Spend appears on the service page and the team page, and unlabelled spend is shown, not hidden.

Design Concept Screens

Design concepts with fictional demo data. They show how the product could look and work, not a live release.

Shipyard service catalog with a filter panel, counts for services, missing owners, failing policy and deprecation items, a services table with owner team, lifecycle, readiness, monthly cost and on-call, team readiness bars, ownership gaps and a deprecation radar

01 / 05 Service catalog - find any service, see who owns it and spot missing owners or retiring parts

Engineering Process

  • Map how a new service reaches production today by following three real services and their owners from first commit to first release.
  • Define the descriptor format, the policy rules and the golden path with platform engineers, and agree which rules warn and which block.
  • Prototype the catalog, service page, pipeline view and cost view and test them with developers who do not know the platform.
  • Build the foundation first: single sign-on, GitHub App, catalog ingestion and the portal shell, then the web service template and preview environments.
  • Add policy checks in the pipeline and the cluster, the dry run, cost ingestion and budgets, and the command-line tool for the same actions.
  • Write migration scripts that add descriptors and labels to existing services, with a review step before any change lands.
  • Pilot with two or three teams, run load and failure tests, write runbooks and train the platform team before wider adoption.

Production Tech Stack

Layer / ComponentProduction Technologies
Portal
Next.js (App Router)TypeScriptTailwind CSSshadcn/uiTanStack TableApache EChartsMonaco editor
Backend
Node.js with FastifyGo controllers for KubernetesZod and JSON Schema validationTemporal for long jobs
Data
PostgreSQL rebuilt from GitClickHouse for cost line itemsRedis for caching
Delivery
GitHub AppGitHub ActionsArgo CD and Argo RolloutsOpenTofu or CrossplaneExternal Secrets
Policy and supply chain
Open Policy Agent with Conftest and KyvernoSigstore Cosign image signingTrivy scansCycloneDX bills of materials
Cloud and cost
AWS EKS and RDSOpenCost with the AWS Cost and Usage ReportFOCUS cost formatPrometheusGrafana and OpenTelemetry

What the design aims for

Shipyard aims to pave one safe road from a new service to production, with ownership, policy results and cloud cost on the same page as the deploy.

ARCHITECTURE & SCOPE CONSULTATION

Need a System Engineered Like Shipyard?

Deploy a dedicated engineering pod or initiate a fixed-scope milestone sprint with full IP ownership and guaranteed delivery.