settled-reach/docs/diagrams/architecture/system-tiers.d2

# Simulation Tiers + Multiplayer-Ready Principles — D-026, D-010, D-009
# Four simulation tiers with LRU eviction.
# D-010: four non-negotiable architectural principles embedded as annotations.

vars: {
  color-bg: "#2a3040"
  color-stroke: "#333340"
  color-text: "#c8d0e0"
  color-accent: "#c8d8f0"
  color-dim: "#1a1e24"
}

direction: down

principles: Architectural Principles (D-010) {
  style.fill: ${color-dim}
  style.stroke: ${color-accent}
  style.font-color: ${color-text}
  style.border-radius: 4

  p1: Client-Server Separation\neven in single-player {
    style.fill: ${color-bg}
    style.stroke: ${color-stroke}
    style.font-color: ${color-text}
  }
  p2: Information Boundaries\nas first-class system {
    style.fill: ${color-bg}
    style.stroke: ${color-stroke}
    style.font-color: ${color-text}
  }
  p3: No Baked Player Identity\n"characters, some player-controlled" {
    style.fill: ${color-bg}
    style.stroke: ${color-stroke}
    style.font-color: ${color-text}
  }
  p4: Deterministic Simulation\ntimestamped input events {
    style.fill: ${color-bg}
    style.stroke: ${color-stroke}
    style.font-color: ${color-text}
  }
}

tiers: Simulation Tiers (D-026) {
  style.fill: ${color-dim}
  style.stroke: ${color-accent}
  style.font-color: ${color-text}
  style.border-radius: 4

  active: Tier 1 — Active {
    style.fill: ${color-bg}
    style.stroke: ${color-accent}
    style.font-color: ${color-text}
    style.bold: true
  }
  background: Tier 2 — Background {
    style.fill: ${color-bg}
    style.stroke: ${color-stroke}
    style.font-color: ${color-text}
  }
  saved: Tier 3 — State-Saved {
    style.fill: ${color-bg}
    style.stroke: ${color-stroke}
    style.font-color: ${color-text}
  }
  ungenerated: Tier 4 — Ungenerated {
    style.fill: ${color-dim}
    style.stroke: ${color-stroke}
    style.font-color: ${color-text}
    style.stroke-dash: 5
  }
}

active_detail: 30-80 NPCs\nFull sim · 10-20 ticks/sec\nScope tags keep NPCs here {
  shape: page
  style.fill: ${color-dim}
  style.stroke: ${color-accent}
  style.font-color: ${color-text}
}

background_detail: 500-2,000 NPCs\nState machine · 1 tick/game-minute\n(schedule · mood · relationships · job) {
  shape: page
  style.fill: ${color-dim}
  style.stroke: ${color-stroke}
  style.font-color: ${color-text}
}

saved_detail: 10,000+ NPCs\nFrozen serialized structs ~1-2KB\nReactivate on player return ~2-5ms {
  shape: page
  style.fill: ${color-dim}
  style.stroke: ${color-stroke}
  style.font-color: ${color-text}
}

eviction: LRU Eviction\n(interaction-timestamp priority queue) {
  shape: diamond
  style.fill: ${color-bg}
  style.stroke: ${color-accent}
  style.font-color: ${color-text}
}

tiers.active -> active_detail {
  style.stroke: ${color-accent}
}
tiers.background -> background_detail {
  style.stroke: ${color-stroke}
}
tiers.saved -> saved_detail {
  style.stroke: ${color-stroke}
}

tiers.active -> tiers.background: "evict (LRU)" {
  style.stroke: ${color-accent}
  style.stroke-dash: 4
}
tiers.background -> tiers.active: "player proximity\nor scope tag" {
  style.stroke: ${color-accent}
}
tiers.background -> tiers.saved: "evict (LRU)" {
  style.stroke: ${color-stroke}
  style.stroke-dash: 4
}
tiers.saved -> tiers.background: "player return" {
  style.stroke: ${color-stroke}
}
tiers.ungenerated -> tiers.saved: "player approach\n(generated ahead of arrival)" {
  style.stroke: ${color-stroke}
  style.stroke-dash: 4
}

eviction -> tiers {
  style.stroke: ${color-accent}
  style.stroke-dash: 4
}