A Grain of Salt

Platform Architecture: Understanding Layers, Capabilities, and Building Blocks

· Teddy Aryono

In previous posts, we established what platform engineering is and explored its relationship with Site Reliability Engineering. Now we turn to the architecture of platforms themselves - how they’re structured, what capabilities they provide, and how those capabilities are built.

Understanding platform architecture is crucial because it clarifies the relationship between what developers experience (the interface), what value the platform provides (capabilities), and how that value is technically delivered (implementation). This mental model helps both platform builders make better design decisions and platform consumers understand what they’re working with.

The Challenge of Platform Architecture

Platform engineering faces a unique architectural challenge: you’re building a product that sits between developers and infrastructure, abstracting complexity while maintaining flexibility. Too much abstraction and you limit what’s possible; too little and you haven’t solved the complexity problem.

The solution lies in understanding platforms as layered systems where each layer has distinct responsibilities and clear boundaries. This separation of concerns allows platforms to evolve, scale, and serve diverse needs without becoming unwieldy.

The Three-Layer Architecture

Successful platforms typically organize around three distinct layers, each serving a different purpose:

Interface Layer: How Developers Interact

The interface layer is what developers see and touch. It’s the “front door” to your platform, and its primary goal is to provide a coherent experience that abstracts away the complexity of everything underneath.

Internal Developer Portals serve as web-based central hubs. Tools like Backstage provide a unified place where developers can browse the service catalog, view documentation, trigger deployments, check service health, and manage environments. The portal aggregates information and actions from across the platform into one coherent interface.

CLI Tools offer command-line access for developers who prefer terminal workflows or need scriptability. Instead of clicking through multiple systems, developers can execute platform deploy my-service or platform create database postgres. CLIs are particularly powerful for integration with CI/CD systems and automation scripts.

APIs provide programmatic access to platform capabilities. Well-designed APIs allow other tools and automation to consume platform services, enabling extensibility. Teams can build custom tooling on top of your platform without waiting for the platform team to implement every feature.

GitOps Workflows express infrastructure and application changes as Git commits. Developers interact with the platform by modifying files in repositories; the platform watches these repos and automatically reconciles desired state with actual state. This brings the benefits of code review, version control, and audit trails to infrastructure changes.

IDE Integrations bring platform capabilities into developers’ daily tools. Deploying from VSCode, viewing logs inline, or accessing documentation without leaving the editor reduces context switching and friction.

The key principle: the interface layer should be consistent regardless of what’s happening underneath. Whether you’re deploying to AWS or GCP, using Kubernetes or another orchestrator, the developer experience should feel unified and coherent.

Capability Layer: What Developers Can Do

The capability layer defines the actual value the platform provides. This is the “product” layer - what developers can accomplish, independent of how it’s implemented. Capabilities are organized around developer needs rather than technical implementation details.

Deployment & Release Management encompasses deploying applications to various environments, progressive rollouts (canary deployments, blue-green deployments), rollback to previous versions, and visibility into deployment status and history. This capability answers: “How do I get my code running in production safely?”

Infrastructure Provisioning covers creating databases (PostgreSQL, MySQL, MongoDB), provisioning caches (Redis, Memcached), setting up message queues (RabbitMQ, Kafka, SQS), creating storage buckets, and configuring networking (VPCs, load balancers, DNS). This capability answers: “How do I get the infrastructure my application needs?”

Observability & Monitoring includes metrics collection and dashboards, log aggregation and search, distributed tracing, alerting and on-call management, and service health status. This capability answers: “How do I understand what my application is doing and debug issues?”

Secrets Management provides secure storage and retrieval of sensitive configuration, automatic secret rotation, access control for secrets, and integration with external secret stores. This capability answers: “How do I handle credentials and sensitive data securely?”

Environment Management enables spinning up ephemeral environments for testing, managing environment configurations, environment promotion (dev → staging → prod), and cost tracking per environment. This capability answers: “How do I test changes in isolation before production?”

Service Discovery & Communication handles services finding each other, load balancing, circuit breaking and retries, and API gateway capabilities. This capability answers: “How do my services communicate reliably?”

Data Platform Access covers data warehouse access, ETL pipeline management, data catalog and discovery, and analytics/BI tool integration. This capability answers: “How do I work with data?”

Security & Compliance includes authentication and authorization, network policies, security scanning (containers, dependencies, secrets), compliance reporting, and audit logging. This capability answers: “How do I ensure my application is secure and compliant?”

Developer Onboarding provides service scaffolding and templates, documentation and runbooks, training materials, and support channels. This capability answers: “How do new developers get productive quickly?”

Each capability solves a specific developer need. The capability layer is where you think about product design: What should this capability do? How should it behave? What’s the developer experience?

Importantly, capabilities are defined from the user’s perspective, not the implementation. “Deployment” is a capability regardless of whether it’s implemented with Kubernetes, ECS, or something else.

Implementation Layer: How Capabilities Are Built

The implementation layer is the technical foundation - the tools, systems, and patterns used to actually deliver capabilities. This layer should be largely invisible to platform consumers, but it’s where platform engineers spend most of their time.

Infrastructure as Code tools like Terraform and OpenTofu handle multi-cloud infrastructure, Pulumi enables infrastructure with general-purpose programming languages, CloudFormation manages AWS-specific resources, CDK provides higher-level abstractions, and Crossplane offers Kubernetes-native infrastructure management.

Container Orchestration typically centers on Kubernetes for container scheduling and management, supplemented by Helm for package management, Kustomize for configuration management, and Operators for extending Kubernetes with custom resources.

CI/CD Systems include GitHub Actions, GitLab CI, and Jenkins for build and test automation, ArgoCD and FluxCD for GitOps-based deployment, Tekton for Kubernetes-native pipelines, and Spinnaker for sophisticated deployment strategies.

Service Mesh solutions like Istio and Linkerd handle service-to-service communication, traffic management and routing, mutual TLS between services, and observability for service interactions.

Observability Stack commonly consists of Prometheus for metrics collection, Grafana for visualization, Loki or ELK stack for log aggregation, Jaeger or Tempo for distributed tracing, and OpenTelemetry for standardized instrumentation.

Policy & Governance tools include Open Policy Agent (OPA) for policy as code, Kyverno for Kubernetes policy management, Cloud Custodian for cloud resource policies, and security scanning tools like Trivy and Snyk.

Secret Management typically involves HashiCorp Vault for secret storage and management, External Secrets Operator for Kubernetes integration, cloud provider secret managers (AWS Secrets Manager, GCP Secret Manager), and Sealed Secrets for encrypted secrets in Git.

Authentication & Authorization includes OAuth2/OIDC providers, service mesh authorization policies, RBAC (Role-Based Access Control) systems, and integration with corporate identity providers.

The implementation layer is where technical decisions live: Which cloud provider? Which orchestrator? Which monitoring stack? These decisions should be driven by requirements from the capability layer, not the other way around.

How the Layers Work Together

A concrete example illustrates the interaction between layers:

Developer goal: Deploy a new microservice that needs a PostgreSQL database

Interface Layer: Developer runs platform create service payment-api --runtime python --database postgres via CLI, or fills out a form in the developer portal.

Capability Layer: The platform understands this requires:

Implementation Layer: The platform executes:

Result: Developer gets a fully operational service with database, monitoring, logging, and secure credential management - all from one simple command or form submission.

The beauty of this layered architecture: you can swap implementation details without changing the developer experience. Migrating from AWS RDS to Google CloudSQL? That’s an implementation layer change. The capability (provision a PostgreSQL database) remains the same. The interface (how developers request it) remains the same. Only the implementation changes.

Key Architectural Principles

Several principles guide effective platform architecture:

Separation of Concerns - Each layer has a distinct responsibility. The interface layer focuses on user experience, the capability layer on product definition, and the implementation layer on technical execution. This separation allows each layer to evolve independently.

Abstraction - Each layer hides the complexity of the layer below. Developers don’t need to know you’re using Terraform to provision infrastructure. Platform engineers don’t need to know whether developers prefer CLI tools or web portals. Each layer provides a clean interface to the layer above.

Flexibility - Multiple implementations can deliver the same capability without changing the interface. You might support multiple deployment strategies, multiple cloud providers, or multiple database engines - all behind the same capability interface. This flexibility is crucial for evolution and avoiding lock-in.

Composability - Capabilities should compose naturally. Deploying a service that needs a database and a cache should feel straightforward, not like stitching together unrelated systems. The platform orchestrates multiple capabilities into coherent workflows.

Evolvability - You should be able to improve implementation without breaking consumers. Upgrading Kubernetes versions, switching monitoring systems, or adopting new IaC tools are implementation changes that don’t affect the interface or capabilities. This allows the platform to improve continuously without disrupting users.

The Relationship Between Capabilities and Building Blocks

Here’s a crucial insight: capabilities and building blocks are inseparable. Building blocks are how you deliver capabilities.

Consider the Deployment capability:

The capability (user perspective): “I can deploy my application to production safely and reliably, with rollback if needed.”

The building blocks (implementation):

The capability defines what value you’re providing. The building blocks are how you construct that value. Different organizations might implement the same capability using different building blocks, based on their constraints and context.

This relationship extends across all capabilities:

Observability capability is built with metrics collectors, log aggregators, tracing systems, dashboards, and alerting engines.

Infrastructure provisioning capability is built with IaC tools, cloud provider APIs, policy engines, and cost management systems.

Secrets management capability is built with secret stores, encryption systems, rotation mechanisms, and access control systems.

The layered architecture makes this relationship explicit. The capability layer defines what you’re building (from the user’s perspective), and the implementation layer defines how you’re building it (from the technical perspective).

Designing for Your Organization

Not every platform needs every capability, and not every capability needs the same level of sophistication. Platform architecture should be driven by actual organizational needs.

Start with high-pain, high-frequency capabilities. What do developers spend the most time on? What causes the most friction? Build capabilities that address real pain points first.

Match sophistication to maturity. A startup might need basic deployment capabilities; an enterprise might need sophisticated progressive delivery with automated rollback. Design capabilities appropriate to your organization’s scale and maturity.

Evolve incrementally. Start with simple implementations and add sophistication as needs become clear. It’s easier to add complexity than to remove it.

Measure usage and value. Track which capabilities are adopted, which provide the most value (reduced time-to-deployment, fewer incidents, etc.), and which are underutilized. Let data guide investment.

Platform Architecture Anti-Patterns

Several common mistakes undermine platform architecture:

Leaky abstractions occur when implementation details bleed through to the interface layer. If developers need to understand Kubernetes to use your deployment capability, your abstraction has leaked. Each layer should shield the layer above from complexity below.

Capability sprawl happens when platforms try to do everything. Platforms accumulate capabilities without clear prioritization, leading to shallow implementations and high maintenance burden. Focus beats breadth.

Implementation-driven design inverts the proper relationship - choosing tools first, then forcing capabilities to fit the tools. This creates awkward interfaces that reflect technical constraints rather than user needs. Always start with capabilities (what users need), then choose appropriate implementations.

Monolithic coupling ties layers too tightly together. When changing implementation requires changing the interface, you’ve lost the benefits of layering. Maintain clear boundaries and contracts between layers.

Ignoring escape hatches creates platforms that can’t handle edge cases. When the abstraction doesn’t fit, users need ways to work around it. Platforms without escape hatches become bottlenecks.

Key Takeaways

For Engineering Leaders:

For Platform Engineers:

For Both:

Looking Ahead

Understanding platform architecture - the layers, capabilities, and building blocks - provides the foundation for building effective platforms. But architecture alone isn’t enough. In the next post, we’ll explore a critical question: how do you build platforms that accelerate organizations rather than becoming bottlenecks? How do you create abstractions that add value without limiting what’s possible?

We’ll examine the philosophy and patterns for building platforms that remain useful as both technology and organizational needs evolve - platforms that empower rather than constrain.

This is the third post in a series exploring platform engineering in depth. Previous posts covered platform engineering fundamentals and the relationship between SRE and platforms.

#platform-engineering

Reply to this post by email ↪