Synkronyx Core Docs

Appearance

Event Route Optimiser (ERO) - Architectural Decision Records & Delivery Matrix ​

1. Executive Summary ​

This document formalises key Architectural Decision Records (ADRs), cloud provider region targets, and the Specification-to-Delivery Matrix governing the Event Route Optimiser (ERO) platform.

The system relies on an offline-first Progressive Web Application (PWA), a Cloudflare Edge Compute API layer, an enterprise Azure Governance & Identity Boundary (Entra External ID / CIAM), and multi-cloud analytics on Google Cloud Platform (GCP).

2. Architectural Decision Records (ADRs) ​

ADR 001: Offline-First Client Datastore (Dexie.js / IndexedDB) ​

  • Status: Accepted / Implemented
  • Context: Festival grounds frequently exhibit zero-connectivity or degraded cellular network coverage due to high crowd density.
  • Decision: ERO uses Dexie.js wrapping client-side IndexedDB to store master schedule timetables, stage geometries, and user preferences locally. All read queries are served from the local cache.
  • Consequences: Outbound sync operations queue locally during network loss and push automatically via online network listeners when connectivity is restored.

ADR 002: Edge Reverse Proxy & Micro-Database Architecture (Cloudflare Workers & D1) ​

  • Status: Accepted / Implemented
  • Context: Low latency API response times are required globally for line-up updates and user preference synchronization.
  • Decision: Deploy Cloudflare Worker edge functions bound to Cloudflare D1 SQLite databases.
  • Consequences: Low-latency serverless routing at the edge with fast read/write transactions and native CORS handling.

ADR 003: Subscription-Scoped Infrastructure as Code (Azure Bicep) ​

  • Status: Accepted / Implemented
  • Context: Environmental isolation requires separate landing zones for development, testing, staging, and production without manual resource group creation.
  • Decision: Utilize subscription-scoped Bicep deployments (targetScope = 'subscription') in Azure.
  • Consequences: Pipelines dynamically create resource groups (rg-sknx-ero-development, rg-sknx-ero-production) on-the-fly without manual portal interventions.

ADR 004: Dual-Loop Identity Authentication (Entra External ID & Inner Loop Mock) ​

  • Status: Accepted / Implemented
  • Context: Production security demands strict Entra CIAM social federation, whereas rapid local development requires zero-network offline execution.
  • Decision: Decouple auth into Inner Loop mock token bypass (local-dev-token) and Outer Loop Entra CIAM JWKS cryptographic validation using WebCrypto APIs (RSASSA-PKCS1-v1_5, SHA-256).
  • Consequences: Developers test locally without cloud dependencies, while production routes validate real JWT bearer tokens at the Cloudflare edge.

ADR 005: Spatial Optimization Engine (Weighted Dijkstra Routing) ​

  • Status: Accepted / In Progress
  • Context: Festival attendees require conflict resolution when chosen acts overlap across distant stages.
  • Decision: Implement Dijkstra shortest path and weighted interval algorithms to compute walking transit times, flag clashes, and suggest precise departure times.
  • Consequences: Delivers exact walking itineraries (Act -> Transit -> Act) directly to users.

ADR 006: Platform vs. Product-Isolated Subscription Boundaries ​

  • Status: Accepted / Implemented
  • Context: Enterprise security and IAM governance require decoupling core corporate platform identity services from product-specific workload resources.
  • Decision: Establish sub-sknx-platform housing central identity (rg-sknx-identity-production), while isolating ERO workload environments into product landing zones sub-sknx-ero-nonproduction (rg-sknx-ero-development, rg-sknx-ero-test) and sub-sknx-ero-production (rg-sknx-ero-production).
  • Consequences: Eliminates blast radius across product boundaries and ensures least-privilege RBAC role assignment for service connections.

ADR 007: Enterprise Billing Hierarchy & Invoice Section Mapping ​

  • Status: Accepted / Implemented
  • Context: Enterprise accounting requires transparent cost sectioning and billing attribution across platform cost centers and individual product lines under a single Microsoft Customer Agreement (MCA).
  • Decision: Structure billing under Billing Account ba-synkronyx and Billing Profile bp-synkronyx-primary using explicit Invoice Sections:
    • inv-sknx-platform (Platform Cost Center: sub-sknx-platform)
    • inv-sknx-ero (Event Route Optimiser Product: sub-sknx-ero-nonproduction, sub-sknx-ero-production)
    • inv-sknx-lbm (Logbook Manager Product: sub-sknx-lbm-nonproduction, sub-sknx-lbm-production)
  • Consequences: Provides granular financial tracking per invoice section and enables automated Bicep subscription alias vending linked directly to product invoice sections via billingScope.

3. Cloud Infrastructure & Region Placement Standards ​

Layer / ServiceProviderTarget RegionResource Group / Boundary
Platform IdentityAzureuksouth (London)rg-sknx-identity-production (sub-sknx-platform)
Development SandboxAzureuksouth (London)rg-sknx-ero-development (sub-sknx-ero-nonproduction)
Integration TestingAzureuksouth (London)rg-sknx-ero-test (sub-sknx-ero-nonproduction)
Pre-Production StagingAzureuksouth (London)rg-sknx-ero-preproduction (sub-sknx-ero-nonproduction)
Production WorkloadAzureuksouth (London)rg-sknx-ero-production (sub-sknx-ero-production)
Edge API & D1 SQLiteCloudflareGlobal Anycast EdgeCloudflare Edge Network
GCP Multi-Cloud LakehouseGCPeurope-west2 (London)synkronyx-ero-prod

4. Specification-to-Delivery Matrix ​

EpicFeatureDeliverable ArtefactStatusTarget Environment
Epic 1PWA Core & Offline Syncapp/src/lib/db.ts, app/src/lib/sync.ts✅ VerifiedClient Browser (Local / Cloud)
Epic 2Edge API & SQLite D1api/src/index.ts, api/schema.sql✅ VerifiedCloudflare Workers / D1
Epic 3Azure Bicep IaCinfra/modules/environment.bicep✅ VerifiedSubscriptions (sub-sknx-ero-nonproduction, sub-sknx-ero-production)
Epic 4Workstation DXscripts/bootstrap.ps1, .vscode/tasks.json✅ VerifiedArch2 Desktop / Arch1 Laptop
Epic 5Entra CIAM & Dual Loopapi/src/auth.ts, app/src/lib/auth.ts✅ VerifiedEntra External Tenant & Worker Edge
Epic 6GCP & Web Ecosystemdocs/05-ado-backlog.md, scripts/sync-ado-backlog.js⏳ Pending / In ProgressGCP & Chrome Web Store

5. Automated System Verification & Governance ​

  • Documentation Bundler: All architectural documents are compiled into docs/MASTER_SYSTEM_SPECIFICATION.md via npm run build:docs.
  • Agent Governance (.agentrules): Any modifications to markdown files in docs/ trigger an automated build pass of npm run build:docs.
  • Azure DevOps Sync: Backlog items are automatically synchronized to Azure DevOps via node scripts/sync-ado-backlog.js.

ADR-008: Enterprise CAF Management Group Governance & Vending Machine Pattern ​

  • Status: Accepted
  • Context: Manually creating subscriptions, resource groups, and tenant configurations for new products or new company deployments leads to delays, environment drift, and inconsistent security policies.
  • Decision:
    1. Nest product workloads into the existing Synkronyx Microsoft Azure Cloud Adoption Framework (CAF) Management Group hierarchy (the vending machine references the root; it does not recreate it):
      • synkronyx (existing CAF Root Management Group — referenced, never recreated)
      • synkronyx-platform / synkronyx-shared-services (existing platform & shared-services tiers)
      • synkronyx-landingzones (Application Landing Zones parent for product workloads)
      • Product MGs under Landing Zones: synkronyx-ero-nonprod (with synkronyx-ero-dev / synkronyx-ero-test child policy scopes) and synkronyx-ero-prod
    2. Adopt the Landing Zone Vending Machine pattern in Bicep (infra/landing-zone/main.bicep). Executing a single tenant-scoped command creates the synkronyx-landingzones parent plus the ERO product Management Groups, vends nonproduction/production subscriptions linked to the correct MCA Invoice Section, and places each subscription into its Management Group at vend time via the alias additionalProperties.managementGroupId.
    3. Enforce 100% parameterised repeatability. Provisioning a new client or platform (such as NeilCommerce or Neat-Grid) requires only updating the productCode parameter and running the vending machine pipeline.
  • Consequences: Reduces new app landing zone spin-up time from 7 days to under 5 minutes, guarantees strict RBAC and Policy isolation across products, and satisfies enterprise auditability.