# `Lightning.Collaborate`
[🔗](https://github.com/OpenFn/lightning/blob/main/lib/lightning/collaboration.ex#L1)

Public API for starting collaborative workflow editing sessions.

This module serves as the main entry point for collaborative editing,
coordinating the creation and management of document and session processes
for workflow collaboration.

All collaborative sessions require a workflow struct.

## Example

    # Existing workflow
    workflow = Lightning.Workflows.get_workflow(workflow_id)

    Collaborate.start(user: user, workflow: workflow)

    # New workflow
    workflow = %Lightning.Workflows.Workflow{
      id: workflow_id,
      project_id: project_id,
      name: "",
      positions: %{}
    }

    Collaborate.start(user: user, workflow: workflow)

# `lookup`

# `start`

```elixir
@spec start(instance :: Lightning.Collaboration.Instance.t(), opts :: Keyword.t()) ::
  GenServer.on_start()
```

# `start_document`

```elixir
@spec start_document(
  workflow :: Lightning.Workflows.Workflow.t(),
  document_name :: String.t()
) ::
  {:ok, pid()} | {:error, term()}
```

Starts the collaborative document tree for `document_name`.

`document_name` is a positional payload (domain identity); the registered name
and the optional `owner` are process configuration and live in trailing `opts`,
per `.claude/guidelines/testable-supervision-trees.md` §1.

## Options

- `:owner` — a pid the document tree monitors. When that pid goes `:DOWN`, the
  tree stops `:normal` (running its flush via `terminate/2`; `:transient` means
  no restart). Lets any caller — a test, a request — get deterministic cleanup
  by passing `owner: self()`, with no wrapper. Defaults to `nil` (no monitor),
  so production documents outlive the LiveView that starts them.

# `start_document`

```elixir
@spec start_document(
  workflow :: Lightning.Workflows.Workflow.t(),
  document_name :: String.t(),
  opts :: Keyword.t()
) :: {:ok, pid()} | {:error, term()}
@spec start_document(
  instance :: Lightning.Collaboration.Instance.t(),
  workflow :: Lightning.Workflows.Workflow.t(),
  document_name :: String.t()
) :: {:ok, pid()} | {:error, term()}
```

# `start_document`

```elixir
@spec start_document(
  instance :: Lightning.Collaboration.Instance.t(),
  workflow :: Lightning.Workflows.Workflow.t(),
  document_name :: String.t(),
  opts :: Keyword.t()
) :: {:ok, pid()} | {:error, term()}
```

# `stop_document`

```elixir
@spec stop_document(
  instance :: Lightning.Collaboration.Instance.t(),
  document_name :: String.t()
) ::
  :ok
```

Deterministically stops the collaborative document for `document_name`.

Tears down its DocumentSupervisor, SharedDoc and PersistenceWriter (with a
final flush). Synchronous and idempotent: returns `:ok` whether or not a
document is running. The symmetric partner to `start_document/2`.

# `whereis`

---

*Consult [api-reference.md](api-reference.md) for complete listing*