Diagrams

Parameter	Value
World FQDN	world.example.com
Organization FQDN	example.com
UUID for main component	ex4mpl31-8d4f-4c9b-a2e3-7f5c1b9d3e6a
Organization IP	203.0.113.20

System overview

Simplified system communication

sequenceDiagram
    autonumber
    participant C as Client
    participant O as Organization
    participant W as World

    O->>W: Organization registration

    C<<->>W: Organization discovery

    loop
        C<<->>O: Application traffic
    end

    loop
        W->>O: Monitoring
    end

Detailed system communication

sequenceDiagram
    autonumber
    participant D as DNS Resolver
    participant C as Client
    participant O as Organization
    participant W as World

    Note over O,W: Organization registration
    O<<->>W: Bootstrap certificate
    O->>W: Publish organization settings

    Note over D,W: Organization discovery
    C->>D: Resolve szworld.example.com (CNAME)
    D-->>C: world.example.com
    C->>W: Discovery request
    W-->>C: Discovery response
    C->>D: Resolve szex4mpl318d4f4c9ba2e37f5c1b9d3e6a.world.example.com
    D-->>C: 203.0.113.20

    Note over C,O: Application traffic
    loop
        C<<->>O: Application traffic
    end

    Note over O,W: Organization monitoring
    loop
        W->>O: Monitor status
    end

Full system overview

graph TB
  Client(["Desktop Client"])
  WebClient(["Web Client"])
  entraId[("Entra ID")]
  world["world.example.com:443"]
  worldMonitor["world.example.com"]

  subgraph OrgBox["Organization"]
    reverseProxy{{"reverse proxy<br/>:443"}}
    main["main:38443"]
    web["web:8082"]
    bff["bff:8081"]
    api["api:8080"]
    scim["scim:8083"]
  end

  smtp[("Mail server")]
  s3[("S3-compatible bucket")]
  idp[("OIDC / BankID IdP")]

  Client <-->|"Organisation Discovery"| world
  Client -->|"szex4mpl318d4f4c9ba2e37f5c1b9d3e6a.world.example.com"| reverseProxy
  WebClient -->|"https://synkzone.example.com"| reverseProxy
  entraId -->|"https://example.com/scim"| reverseProxy

  reverseProxy -->|"SNI"| main
  reverseProxy -->|"/"| web
  reverseProxy -->|"/api"| api
  reverseProxy -->|"/bff/api"| bff
  reverseProxy -->|"/scim"| scim
  bff --> main
  api --> main
  scim --> api

  main -->|"Registration"| world
  worldMonitor -->|"Monitoring"| reverseProxy

  world -.->|"smtp"| smtp
  main -.->|"smtp"| smtp
  main <-.->|"Remote Storage"| s3
  main <-.->|"IDP"| idp

  style OrgBox fill:none,stroke:#999

Organization

Components

Organization components as deployed by the standard-delivery reference installation.

graph LR
  nginx(("nginx:443"))

  subgraph containers
    main["main:38443"]
    web["web:8082"]
    bff["bff:8081"]
    api["api:8080"]
    scim["scim:8083"]

    bff --> main
    api --> main
    scim --> api
  end

  style containers fill:none,stroke:#999

  nginx -->|"szex4mpl318d4f4c9ba2e37f5c1b9d3e6a.world.example.com"| main
  nginx -->|"/"| web
  nginx -->|"/api"| api
  nginx -->|"/scim"| scim
  nginx -->|"/bff/api"| bff

Organization registration

When an Organization is first deployed, the Organization Server must acquire a signed certificate from the configured World Server.

sequenceDiagram
    autonumber
    participant O as Organization Server
    participant W as World Server

    O->>O: Generates certificate signing request (CSR)
    O->>W: Submit CSR

    W->>W: Sign certificate using World root
    W-->>O: Return signed certificate

    O->>O: Import signed certificate
    O->>O: Sign organization settings with certificate

    O->>W: Publish signed organization settings
    W->>W: Store organization settings

Organization discovery & trust verification

How a Client comes to trust an Organization it has never contacted before, using the bundled World root certificate.

sequenceDiagram
    autonumber
    participant D as DNS Resolver
    participant C as Client
    participant W as World

    C->>D: Resolve szworld.example.com
    D-->>C: world.example.com
    C->>W: Discovery request (Organization FQDN)
    W-->>C: Signed organization settings

    C->>C: Verify signature against bundled World root certificate

    C->>D: Resolve szex4mpl318d4f4c9ba2e37f5c1b9d3e6a.world.example.com
    D-->>C: 203.0.113.20

World

World certificate bootstrap

Establishing the World's own trust root on first installation. This is only applicable for self hosted world servers.

sequenceDiagram
    autonumber
    participant S as Synkzone
    participant Op as Operator
    participant W as World Server

    Op->>W: Start
    W->>W: Generates certificate signing request (CSR), then stops

    W->>Op: Copy CSR
    Op->>S: Submit CSR
    S->>S: Issue certificate
    S-->>Op: Return certificate

    Op->>W: Copy signed certificate
    Op->>W: Start
    W->>W: Imports, then stops