ERO Product Docs

Appearance

Synkronyx Landing Zone & ERO Infrastructure Realignment - Completion Notes ​

Date: 2026-07-23
Project: Event Route Optimiser (ERO) & Synkronyx Enterprise Landing Zone
Repository: Synkronyx/event-route-optimiser
Branch: main (Fully Synchronized)

1. Executive Summary ​

During this engineering session, the Synkronyx Multi-Product Enterprise Landing Zone Architecture and Event Route Optimiser (ERO) infrastructure were refactored into a standardized, two-stage Bicep Vending Machine pattern.

All loose legacy root infrastructure files were removed, subscription boundaries were aligned with Microsoft Customer Agreement (MCA) Invoice Sections, environment variables were sanitized around single-source PUBLIC_ keys, VS Code task automation was configured, and system documentation was bundled into docs/MASTER_SYSTEM_SPECIFICATION.md.

2. Key Architecture & Engineering Deliverables ​

A. Landing Zone Vending Machine & Decoupled Bicep Modules ​

  • Tenant-Scoped Orchestrator: Refactored infra/landing-zone/main.bicep (targetScope = 'tenant') to deploy top-level Cloud Adoption Framework (CAF) Management Group hierarchy:
    • mg-synkronyx (Tenant Root Group)
    • mg-platform (Shared services, Key Vault, central identity)
    • mg-landingzones (Product landing zones parent)
    • mg-ero-nonproduction (ERO Non-Prod Management Group)
    • mg-ero-production (ERO Prod Management Group)
  • Decoupled Module Structure:
    • infra/landing-zone/modules/mgmt-root.bicep (Root MG creation)
    • infra/landing-zone/modules/mgmt-children.bicep (Platform & Product MG creation)
    • infra/landing-zone/modules/mgmt-subscriptions.bicep (Subscription movement into MGs)
  • Subscription Aliasing & MCA Billing Scope: Handled subscription alias vending via Microsoft.Subscription/aliases under MCA invoice section scopes (/providers/Microsoft.Billing/billingAccounts/${billingAccountId}/billingProfiles/${billingProfileId}/invoiceSections/${invoiceSectionId}).
  • Linter Cleanliness: Applied @sys.ignore('no-unused-params') on location and environment parameters to preserve downstream module interface compatibility without warnings.

B. Workload Infrastructure & Full Taxonomy Alignment ​

  • Workload Modules: Isolated regional workload resources to infra/modules/environment.bicep and infra/modules/ciam.bicep.
  • Parameter Files Taxonomy: Standardized parameter files in infra/parameters/:
    • development.bicepparam (Targets sub-sknx-ero-nonproduction & rg-sknx-ero-development, redirect: http://localhost:4321)
    • test.bicepparam (Targets sub-sknx-ero-nonproduction & rg-sknx-ero-test, redirect: https://ero-test.synkronyx.cloud)
    • production.bicepparam (Targets sub-sknx-ero-production & rg-sknx-ero-production, redirect: https://ero.synkronyx.cloud)

C. Two-Stage Vending Machine Bootstrapper Script ​

  • Script: scripts/deploy-landingzone.ps1
  • Workspace Root Resolution: Dynamically resolves $WorkspaceRoot = (Resolve-Path "$PSScriptRoot/..").Path to reliably locate .env.local and parameter files regardless of invocation working directory.
  • Process Environment Injection: Reads .env.local / settings/.env.local and injects billing secrets (SKNX_AZURE_BILLING_ACCOUNT_ID and SKNX_AZURE_BILLING_PROFILE_ID) into process memory.
  • Two-Stage Execution Flow:
    • Step 1: Pre-provisions / verifies Root MG mg-synkronyx with a 30-second delay if newly created for Azure directory replication.
    • Step 2: Executes tenant landing zone vending machine (infra/landing-zone/main.bicep).
    • Step 3: Captures non-prod subscription ID from tenant output, switches Azure CLI context (az account set --subscription $nonProdSubId), and provisions subscription-level workload infrastructure (infra/modules/environment.bicep).

D. Single-Source Credential Governance ​

  • Removed Duplicate Auth Keys: Eliminated non-PUBLIC_ duplicates (SKNX_ERO_CLIENT_ID and SKNX_ERO_TENANT_ID).
  • Standardized Key Set:
    • SKNX_AZURE_BILLING_ACCOUNT_ID
    • SKNX_AZURE_BILLING_PROFILE_ID
    • PUBLIC_SKNX_ERO_CLIENT_ID
    • PUBLIC_SKNX_ERO_TENANT_ID
    • PUBLIC_SKNX_ERO_AUTH_MOCK
  • Updated Templates: Cleaned settings/.env.local, settings/.env.dev.local, bootstrap.ps1, scripts/bootstrap.ps1, and created settings/.env.example.

E. Developer Experience (DX) & VS Code Task Integration ​

  • Updated .vscode/tasks.json with 6 explicit tasks:
    1. Deploy Landing Zone (Development) (Default Build Task, Ctrl + Shift + B)
    2. Deploy Landing Zone (Test)
    3. Deploy Landing Zone (Production)
    4. Get Started on ERO (Initial Setup) (scripts/bootstrap.ps1)
    5. Update Device (Refresh Dependencies) (scripts/bootstrap.ps1 -Update)
    6. Build Documentation (Master Spec) (node scripts/concat-docs.js)

F. Architectural Decision Records & Master Specification ​

  • Appended formal ADRs to docs/02-architectural-decisions.md:
    • ADR 006: Platform vs. Product-Isolated Subscription Boundaries
    • ADR 007: Enterprise Billing Hierarchy & Invoice Section Mapping
    • ADR 008: Enterprise CAF Management Group Governance & Vending Machine Pattern
  • Authored docs/03-landing-zone-governance.md detailing the complete multi-product hierarchy and vending machine flow.
  • Re-compiled docs/MASTER_SYSTEM_SPECIFICATION.md via node scripts/concat-docs.js.

3. Verified Verification Results ​

Test / Audit MetricResultTarget / Outcome
Bicep Linter Pass✅ 0 Errors / 0 WarningsClean compilation on tenant and subscription modules
Loose Bicep Audit✅ Clean0 .bicep files in infra/ root
Path Structure Audit✅ VerifiedLanding zone modules in infra/landing-zone/modules/
Doc Bundler Pass✅ 39 Files Bundleddocs/MASTER_SYSTEM_SPECIFICATION.md compiled cleanly
Git Working Tree✅ Clean (origin/main)Up to date with remote

4. Git Commit Log for Session ​

  1. arch(infra): standardize landing zone to sub-sknx-platform, sub-sknx-ero-nonproduction, and sub-sknx-ero-production
  2. feat(infra): realign landing zone vending machine, taxonomy, and single-source auth keys
  3. fix(infra): ensure main.bicep landing zone is fully self-contained and clean
  4. refactor(infra): remove legacy flat bicep files and structure landing-zone vs modules
  5. arch(landingzone): sync two-stage vending machine deployment, workspace root resolution, and clean taxonomy

5. Next Recommended Action Steps ​

  1. Execute Ctrl + Shift + B in VS Code (or run .\scripts\deploy-landingzone.ps1) to trigger the two-stage landing zone vending machine on Azure.
  2. Verify created Management Groups (mg-synkronyx, mg-platform, mg-landingzones, mg-ero-nonproduction, mg-ero-production) in the Azure Portal under Management Groups.
  3. Validate created subscription resource groups (rg-sknx-ero-development, rg-sknx-identity-production).