Architecture

flowchart TD
  Start["VS Code TourEngine.start"] --> List["client.listTours"]
  List --> Server["OnboardingListTours.run_with_snapshot"]
  Server --> Service["TourService.list_tours"]
  Service --> Resolve["OnboardingTargetResolver.resolve"]
  Resolve --> Branch{"target kind"}
  Branch --> Contract["Contract or Dataset or Column field"]
  Branch --> Quality["Quality Spec or Check"]
  Branch --> SQL["SQL text target"]
  Branch --> UI["UI target id"]
  Branch --> YAML["Structural YAML fallback"]
  Contract --> Editor["ResolvedHighlight kind = editor_range"]
  Quality --> Editor
  SQL --> Editor
  YAML --> Editor
  UI --> UiResult["ResolvedHighlight kind = ui_target"]
  Editor --> DTO["StepDto.resolvedTarget"]
  UiResult --> DTO
  DTO --> Client["TourEngine.revealAndWatch"]
  Client --> Open{"resolved target kind"}
  Open --> File["open editor and decorate range"]
  Open --> Surface["route UI target id to All Contracts or Swagger or Dashboard"]
  File --> Watch["watchStep for predicates if present"]
  Surface --> Watch
  Watch --> Done["Next unlocks by predicate or timer policy"]

sequenceDiagram
  participant E as TourEngine
  participant C as TurbineClient
  participant L as OnboardingListTours
  participant S as TourService
  participant R as OnboardingTargetResolver
  participant O as TourFileOpener

  E->>C: listTours()
  C->>L: turbine/onboarding/listTours
  L->>S: list_tours(sandbox_root)
  loop each Step
    S->>R: resolve(sandbox_root, target)
    R-->>S: ResolvedHighlight
  end
  S-->>L: ListToursResult
  L-->>C: response
  C-->>E: tours
  E->>O: revealTarget(sandboxPath, resolvedTarget)
  E->>C: watchStep(tourId, stepId)
  C-->>E: stepCompleted notification
  E->>E: nextUnlocked = true

classDiagram
  class Step {
    +str id
    +str title
    +str body_markdown
    +HighlightTarget target
    +Predicate predicate
    +SkipAction skip
  }

  class HighlightTarget {
    <<Protocol>>
  }

  class ContractFieldTarget {
    +str file
    +str contract_id
    +str field
  }

  class DatasetTarget {
    +str file
    +str contract_id
    +str dataset
  }

  class ColumnFieldTarget {
    +str file
    +str dataset
    +str column
    +str field
  }

  class QualitySpecFieldTarget {
    +str file
    +str spec_id
    +str field
  }

  class CheckTarget {
    +str file
    +str source_id
    +str dataset
    +str check_type
    +str name
  }

  class SqlTextTarget {
    +str file
    +str text
  }

  class UiTarget {
    +str target_id
  }

  class OnboardingTargetResolver {
    +resolve(sandbox_root, target) ResolvedHighlight
  }

  class ResolvedHighlight {
    +ResolvedHighlightKind kind
    +str file
    +tuple~int~ range
    +str target_id
  }

  HighlightTarget <|.. ContractFieldTarget
  HighlightTarget <|.. DatasetTarget
  HighlightTarget <|.. ColumnFieldTarget
  HighlightTarget <|.. QualitySpecFieldTarget
  HighlightTarget <|.. CheckTarget
  HighlightTarget <|.. SqlTextTarget
  HighlightTarget <|.. UiTarget
  Step --> HighlightTarget
  OnboardingTargetResolver --> ResolvedHighlight