Platform Architecture

The Equation platform is designed to support scalable, secure, and reusable engineering calculations via APIs. It brings together domain logic, infrastructure automation, and client tooling into a consistent, governed environment.

This page explains how the different layers of the platform work together.

🧠 High-Level Architecture

At a high level, the Equation platform consists of:

1. Calculation packages written in Python (or other languages)
2. API layer that exposes these packages via RESTful APIs
3. Azure API Management (APIM) as the secure gateway
4. Clients like WaterFuser, Excel, Grasshopper, and Python SDK

Each API follows the OpenAPI specification and is secured through Haskoning's Azure Entra ID (SSO).

🔁 Flow Overview

1. Engineers write validated business logic in a Python package
2. A developer builds an API layer exposing this logic with a RESTful interface
3. The OpenAPI spec is published and routed through Azure API Management
4. APIM applies token validation, rate limits, logging, and policy enforcement
5. Clients call the API through APIM — never directly

🧱 Layer Breakdown

1. Calculation Layer

• Python packages (sometimes other languages)
• Typically one package = one domain model

2. API Layer

• FastAPI or Django backend wrapping the logic
• Publishes OpenAPI specification
• Handles request/response validation

3. Management Layer

• Azure API Management (APIM)
• Central access point for all clients
• Applies SSO, policies, and usage tracking

4. Client Layer

• Tools for users: WaterFuser, Excel, Python, Grasshopper
• Read inputs, trigger calculation, show results

🧑‍🤝‍🧑 Team Boundaries and Responsibilities

Equation enforces a clear separation between platform and product responsibilities:

• Platform Administrator Manages the core API Management infrastructure, role definitions, policy templates, and identity provisioning. They do not create or maintain individual APIs.

• Product Teams Own their specific calculation APIs. This includes:

  • Writing and maintaining the calculation logic
  • Defining the API layer and OpenAPI spec
  • Deploying their API via CI/CD pipelines using scoped role based access control with Managed Identities

Each product team is technically restricted to managing only their assigned API and backend resources. This ensures:

• Strong isolation between APIs
• Reduced risk of accidental cross-team changes
• Simplified troubleshooting and ownership

These boundaries are enforced through api scoped role-based access control (RBAC) at the Azure level and reinforced through version-controlled Terraform configuration.

INFO

📌 Federated API Model: Each team owns and deploys their own APIs. Equation enforces isolation and governance via scoped permissions, standardized pipelines, and shared infrastructure policies.

📦 Infrastructure & Deployment

• APIs are deployed using Terraform (or manually if required)
• Teams have isolated roles (product vs platform), and product teams are only permitted to maintain and deploy their own APIs. Access to other teams' APIs is technically restricted through scoped permissions.
• Environments: Acceptance and Production
• IP-based restrictions protect backend services and are part of the broader platform security controls. The APIM gateway uses a static IP address, which must be explicitly whitelisted by backend services to allow traffic from the platform.
• Azure AD Configuration – Developer Portal Login Integration

🔐 Security by Design

• All APIs are accessed via Entra ID authentication
• Backend services are not publicly exposed
• Logging, monitoring, and alerting are centralized

This architecture enables individual teams to own and evolve their APIs, while platform-wide tooling ensures security, stability, and governance.