flowchart TD
  Start["VS Code entry point"] --> Entry{"Entry kind"}
  Entry -->|"New Contract then From Datasource"| ShellFrom["Sidebar shell forwards command with target root"]
  Entry -->|"Datasource row Create DataContract"| ShellRow["Sidebar shell forwards command with target root and datasource URI"]
  Entry -->|"Datasource file CodeLens"| Lens["CodeLens forwards command with datasource URI"]

  ShellFrom --> Command["CommandHandler routes to SidebarResourceCreation"]
  ShellRow --> Command
  Lens --> Command

  Command --> Resolve["resolve target project layout"]
  Resolve -->|"no layout"| Init["show Project Initialization needed"]
  Resolve -->|"layout found"| Preselected{"Datasource preselected"}

  Preselected -->|"yes"| OpenDs["load selected Datasource"]
  Preselected -->|"no"| PickDs["pick Datasource from target project"]
  PickDs -->|"cancel or none"| Cancel["return cancelled outcome"]
  PickDs --> OpenDs

  OpenDs -->|"backend failure"| Failure["show failure and stop"]
  OpenDs -->|"backend ready"| ListTables["list Datasource tables"]
  ListTables -->|"none or failure"| Failure
  ListTables --> PickTables["pick one or more tables"]
  PickTables -->|"cancel or empty"| Cancel
  PickTables --> Name["prompt Contract id"]
  Name -->|"cancel"| Cancel
  Name --> Introspect["introspect selected tables"]
  Introspect -->|"failure"| Failure
  Introspect --> Render["generate_data_contract_content"]
  Render --> Conflict{"target file exists"}
  Conflict -->|"no"| Write["apply edit without overwrite"]
  Conflict -->|"Open Existing"| OpenExisting["open existing file"]
  Conflict -->|"Choose Different Name"| Name
  Conflict -->|"Overwrite"| WriteOverwrite["apply edit with overwrite"]
  Write --> OpenNew["open generated Contract"]
  WriteOverwrite --> OpenNew
  OpenNew --> Done["show Contract created"]
sequenceDiagram
  participant User
  participant Shell as VSCode_shell
  participant Command as CommandHandler
  participant Creation as SidebarResourceCreation
  participant Editor as LspClient
  participant Backend as DatabaseBackend
  participant Writer as WorkspaceEdit

  User->>Shell: choose From Datasource or row action
  Shell->>Command: workspace execute command
  Command->>Creation: create Contract from Datasource
  Creation->>Editor: pick Datasource when not preselected
  Editor-->>Creation: Datasource URI
  Creation->>Backend: list tables
  Backend-->>Creation: table refs
  Creation->>Editor: pick tables
  Editor-->>Creation: selected tables
  Creation->>Editor: prompt Contract id
  Editor-->>Creation: Contract id
  Creation->>Backend: introspect selected tables
  Backend-->>Creation: column definitions
  Creation->>Editor: resolve conflict when needed
  Editor-->>Creation: conflict action
  Creation->>Writer: apply edit
  Writer-->>Creation: applied
  Creation->>Editor: open generated Contract
  Shell->>Shell: refresh and reveal All Contracts
classDiagram
  class CommandHandler {
    +handle(query) CommandResult
    +create_contract_from_datasource(arguments) CommandResult
  }

  class SidebarResourceCreation {
    +create_datasource(target_root) SidebarCreationOutcome
    +create_blank_contract(target_root) SidebarCreationOutcome
    +create_contract_from_datasource(request) SidebarCreationOutcome
  }

  class ContractFromDatasourceRequest {
    +target_root : Path
    +datasource_uri : str
  }

  class SidebarCreationOutcome {
    +uri : str
    +message : str
    +created : bool
    +opened_existing : bool
  }

  class LspClient {
    <<Protocol>>
    +pick_datasource(datasources) DatasourcePick
    +pick_tables(tables) tuple
    +prompt_text(message, placeholder) str
    +show_message_request(message, actions) str
    +show_document(uri) bool
    +apply_edit(uri, content, overwrite) bool
  }

  class DatabaseBackend {
    <<Protocol>>
    +list_tables(pattern) tuple
    +introspect_schema(table_id) tuple
  }

  class SidebarResourceCreationShell {
    +newContract() Promise~void~
    +newDatasource() Promise~void~
  }

  CommandHandler --> SidebarResourceCreation
  SidebarResourceCreation --> ContractFromDatasourceRequest
  SidebarResourceCreation --> SidebarCreationOutcome
  SidebarResourceCreation --> LspClient
  SidebarResourceCreation --> DatabaseBackend
  SidebarResourceCreationShell --> CommandHandler