SynkronyXr© Platform — System Architecture Document (SAD)

Document Owner: Platform Architecture Team
Last Updated: 2026-07-25

1. Vision & Strategic Context

SynkronyXr© is a digital ecosystem of interconnected, intelligent applications designed to seamlessly blend real-world experiences with data-driven insights. Our mission is to empower users by transforming complex data into intuitive, actionable, and beautifully designed interfaces.

This document outlines the foundational architecture for the SynkronyXr© platform, beginning with its flagship product, the Event Route Optimiser (ERO).

1.1. Product Line: Event Route Optimiser (ERO)

The Event Route Optimiser (ERO) is an offline-first Progressive Web Application (PWA) designed for festival-goers. It calculates optimal walking paths, resolves schedule conflicts, and provides real-time biometric exertion tracking to enhance the live event experience.

---

2. Global Architecture Baseline: A Multi-Product Ecosystem

The SynkronyXr© platform is built on a globally distributed, edge-first architecture designed for high availability, low latency, and consistent user experiences across all products.

graph TD
    subgraph SynkronyXr© User Experience
        A[Astro PWA Mobile Client - ERO]
        B[Astro PWA Mobile Client - LBM]
        C[Future SynkronyXr© Products...]
    end

    subgraph Cloudflare Edge Platform
        direction LR
        D{Edge Layer}
        D -- JWT Auth --> E[Auth Middleware]
        D -- API Gateway --> F[API Workers]
        F -- CRUD --> G[D1 SQLite Database]
    end

    subgraph Azure Enterprise Platform (System of Record)
        direction LR
        H{Azure Landing Zones}
        H -- Identity --> I[Microsoft Entra External ID (CIAM)]
        H -- Governance --> J[CAF Management Groups]
        H -- Billing --> K[Azure Subscriptions]
    end

    A -- OAuth2/OIDC --> D
    B -- OAuth2/OIDC --> D
    C -- OAuth2/OIDC --> D
    D -- System Sync --> H

    style A fill:#2d3748,stroke:#fff,stroke-width:2px,color:#fff
    style B fill:#2d3748,stroke:#fff,stroke-width:2px,color:#fff
    style C fill:#2d3748,stroke:#fff,stroke-width:2px,color:#fff

---

3. DevSecOps & Governance: The CAF Landing Zone Vending Machine

The SynkronyXr© platform adheres to the Microsoft Cloud Adoption Framework (CAF), utilizing a "vending machine" model to provision new product landing zones with built-in governance, security, and cost management.

3.1. Management Group & Subscription Hierarchy

All resources are nested within a standardised CAF hierarchy, ensuring consistent policy inheritance and clear separation of concerns.

graph TD
    subgraph "Tenant Root Group (synkronyx.onmicrosoft.com)"
        A(synkronyx)
    end

    subgraph "Platform Services"
        B(synkronyx-platform)
        C(synkronyx-shared-services)
    end

    subgraph "Product Landing Zones (Vended here)"
        D(synkronyx-landingzones)
    end

    subgraph "ERO Product Line"
        E(synkronyx-ero)
        F(sub-sknx-ero-nonproduction)
        G(sub-sknx-ero-production)
    end

    subgraph "LBM Product Line (Future)"
        H(synkronyx-lbm)
        I(sub-sknx-lbm-nonproduction)
        J(sub-sknx-lbm-production)
    end

    A --> B
    A --> C
    A --> D

    D --> E
    E --> F
    E --> G

    D --> H
    H --> I
    H --> J

    style A fill:#0078D4,color:#fff
    style B fill:#2d3748,color:#fff
    style C fill:#2d3748,color:#fff
    style D fill:#4A5568,color:#fff
    style E fill:#718096,color:#fff
    style H fill:#718096,color:#fff

3.2. Infrastructure as Code (IaC) Deployment Model

Provisioning is a fully automated, two-stage process orchestrated by Bicep, requiring zero manual portal intervention.

1. Tenant-Scope Deployment (main.bicep):

   • Target: targetScope = 'tenant'
   • Action: Creates the core CAF management group hierarchy (synkronyx-landingzones, synkronyx-ero, etc.).
   • Outcome: A governed foundation ready to receive product subscriptions.

2. Subscription-Scope Deployment (identity.bicep):

   • Target: targetScope = 'subscription'
   • Action: Programmatically creates the sub-sknx-ero-* subscriptions via aliases and provisions the environment-specific CIAM tenants (dev, test, prod).
   • Outcome: A fully provisioned, isolated product environment.

---

4. Identity & Access Management (IAM): "Sign in with SynkronyXr©"

The identity strategy is central to the ecosystem, enabling a unified user profile across all SynkronyXr© products.

4.1. Architecture: Federated Microsoft Entra External ID (CIAM)

A federated model provides both product-specific and global identity capabilities.

• Central SynkronyXr© Cloud Identity: A dedicated Entra External ID tenant acts as the primary IdP, enabling "Sign in with SynkronyXr©" across all applications.
• Social & Enterprise IdPs: Federates with major providers (Google, Apple, etc.) to offer users choice.
• Protocols: Secure by design using OAuth 2.0 / OpenID Connect (OIDC) with PKCE.

4.2. Financial Invoice Projection (Per-Product, 100,000 MAUs)

Each product's CIAM usage is billed to its respective production subscription. The model remains consistent.

Example: ERO Production (sub-sknx-ero-production)

Invoice Line Item: Microsoft Entra External ID - Basic MAU
------------------------------------------------------------------------
Tier 1 (First 50,000 MAUs):                              $0.00 / MAU  = $0.00
Tier 2 (Next 50,000 MAUs @ $0.03 / MAU):         50,000 x $0.03 / MAU  = $1,500.00
------------------------------------------------------------------------
TOTAL ESTIMATED MONTHLY BILL (ERO):                                     $1,500.00 / m

5. Developer Experience (DX): The Zero-Friction Mandate

A developer on a fresh machine requires only VS Code, a repository clone, and a single command to be fully productive.

5.1. The Bootstrapper Engine (scripts/bootstrap.ps1)

This PowerShell script automates the entire workstation setup:

• Toolchain Installation: Uses winget to install pinned versions of Git, Node.js, Terraform, and the .NET SDK from config/dependencies.json.
• IDE Configuration: Installs all recommended VS Code extensions from .vscode/extensions.json.
• Credential Hydration: Securely prompts for and stores necessary tokens (.env.local).
• Database Seeding: Initializes the local Cloudflare D1 SQLite database with schema.sql and seed.sql.
• Service Ignition: Concurrently launches the Astro PWA and Cloudflare Worker dev servers.

---

6. Brand Identity & Design System

• Brand Mark: SynkronyXr©
• Primary Typeface: Plus Jakarta Sans (Sourced from Google Fonts)
• Design Philosophy: Minimalist, data-forward, and intuitive. The UI prioritizes clarity and performance, with a dark-mode-first approach that is accessible and visually striking.

---