Platform Notation

The limits of my language mean the limits of my world.

Architecture is often lost in translation. When we describe a platform, we usually rely on a mix of high-level diagrams, vendor-specific jargon, and ambiguous prose. A “cluster” might mean a physical set of servers to one person and a logical isolation boundary to another. In Azure, we talk about “Subscriptions”; in AWS, “Accounts”; in GCP, “Projects.” These terms are not just different labels; they carry subtle, vendor-specific behaviors that cloud our architectural intent.

To build a professional platform, we need a shared language that is precise, vendor-neutral, and readable by both humans and machines. This book introduces the Platform Notation—a structural definition language designed to express infrastructure placements, relationships, and types with mathematical clarity.

Why a New Notation?

You might wonder why we don’t just use standard Infrastructure as Code (IaC) like Terraform or YAML manifests. While those tools are excellent for implementation, they are too verbose and implementation-heavy for design.

We use Platform Notation for three reasons:

1. Vendor Neutrality: It allows us to discuss the “what” and the “where” without getting bogged down in the “how” of a specific cloud provider.
2. Shared Vocabulary: It creates a bridge between the platform engineer designing the system and the AI agents helping to build it. When an AI understands the notation, it can generate consistent, policy-compliant code across any provider.
3. Architectural Precision: It forces us to be explicit about boundaries. If you cannot express a boundary in the notation, it probably isn’t a well-defined boundary in your architecture.

The Grammar

The notation is built on three simple primitives: Types, Coordinates, and Collections.

Types

A Type defines what a resource is. It uses a functional syntax: Name(Parameters).

The name of the type represents a specific architectural concept or a cloud primitive. The parameters define its scope or characteristics.

Type(Parameter1, Parameter2, ...)

For example, a generic network boundary might be expressed as Network(Scope). A specific cloud resource might be expressed as AzureSubscription(Context).

Positional Inference

To keep the notation concise, we use positional inference. This means that if we have defined a standard set of parameters for a type, we can omit the parameter names as long as the values are in the correct order.

• Explicit: Group(Tenant = "payments", Tier = "live", Role = "admin")
• Inferred: Group("payments", "live", "admin")

Throughout this book, we will consistently use clean strings for parameters within functional calls, relying on the type’s definition to provide the context.

Coordinates

A Coordinate defines where a resource lives. It is expressed as a tuple—a comma-separated list of values inside parentheses.

(Dimension1, Dimension2, ...)

Coordinates act as the “address” for every resource in the platform. In the upcoming chapters, we will define a standard four-dimensional coordinate system that organizes our entire world (i.e. sector, tier, region and tenant). If a specific dimension is not relevant for a resource, we use an underscore (_) to indicate it is ignored.

• ("ecommerce", "live", "eu01", "payments"): A fully resolved address.
• ("platform", "live", _, _): An address that ignores the regional and tenant dimensions.

Collections

When we need to reference a set of resources rather than a single instance, we use Collections. We denote a collection by adding square brackets [] to a type and using the wildcard symbol * within the parameters.

• Type[](Dimension = "*"): A collection of all instances of that type across every value of that dimension.

For example, if we want to refer to every production network across all our business sectors, we might write: Network[](Sector = "*", Tier = "live").

Associations

Architecture is not just about isolated components; it is about how they relate to one another. To express these relationships, Platform Notation uses Associations.

While you can use functional verbs like Assign(Group, Role), the notation provides three simple, pleasant-to-read operators for the most common relationships:

1. Hierarchy (in): Expresses membership or containment.
   • Identity in Group("payments", "live", "reader")
2. Structural Mapping (=>): Expresses implementation or realization. Use this to link an abstract concept to a concrete cloud primitive.
   • Space("payments", "live", ...) => AzureResourceGroup(...)
3. Logical Connectivity (<->): Expresses a bidirectional link or communication path.
   • Spoke("ecommerce", "live", "eu01") <-> Hub("platform", "live", "eu01")

By combining types, coordinates, and associations, we can describe the entire “graph” of the platform with minimal ambiguity.

Disclosing the Platform

We will not introduce all the specific types, dimensions and associations in this chapter. Instead, we will disclose the language as we build the platform:

• In Chapter 4 (Segmentation), we will define the dimensions that form our coordinate system.
• In Chapter 5 (Identity and Access Management), we will introduce the types for roles and authorization groups.
• In Chapter 6 (Infrastructure), we will map these abstract types to concrete cloud primitives like VPCs, Accounts, and Subscriptions.

By the end of this book, this shorthand notation will allow you to describe an entire global, multi-tenant platform in just a few lines of precise, mathematical definitions.