Conversation

Manages the structured formats, timing, and active recording of conversations.

featureStructured Formats

Data Model

Diagram

er Conversation data model

Gallery Source ⛶

Diagram Syntax Error

erDiagram
  participant {
    string id PK
    string name 
    string deviceId 
  }
  format {
    string id PK
    string name 
    string description 
  }
  section {
    string id PK
    string formatId 
    integer order 
    string title 
    integer durationSeconds 
    string guidelines 
  }
  session {
    string id PK
    string formatId 
    datetime startedAt 
    datetime endedAt 
    integer duration 
  }
  session_participant {
    string sessionId 
    string participantId 
  }
  marker {
    string id PK
    string sessionId 
    string participantId 
    integer offsetMs 
    string visibility 
  }
  section }o--|| format : "formatId"
  session }o--|| format : "formatId"
  session_participant }o--|| session : "sessionId"
  session_participant }o--|| participant : "participantId"
  marker }o--|| session : "sessionId"
  marker }o--|| participant : "participantId"

Source

Table participant {
  id string [pk]
  name string [note: 'Display name or alias']
  deviceId string [null, note: 'Links to synchronization/device']
}

Table format {
  id string [pk]
  name string
  description string [null]
}

Table section {
  id string [pk]
  formatId string [ref: > format.id]
  order integer [note: 'Sequence within the format']
  title string
  durationSeconds integer [note: 'Timebox duration for this section']
  guidelines string [note: 'Instructions on how to speak, listen, or engage']
}

Table session {
  id string [pk]
  formatId string [ref: > format.id]
  startedAt datetime
  endedAt datetime [null]
  duration integer [null, note: 'seconds']
}

Table session_participant {
  sessionId string [ref: > session.id]
  participantId string [ref: > participant.id]
}

Table marker {
  id string [pk]
  sessionId string [ref: > session.id]
  participantId string [null, ref: > participant.id]
  offsetMs integer [note: 'Millisecond offset from session start']
  visibility string [note: 'private | shared; default: private']
}

API

Actions

start-session

Starts a new conversation session using a specific format.

Properties

format-idstringparticipantsarray

Parameter	Type	Required	Description
format-id	string	—
participants	array	—

mark-moment

Creates a timestamped flag during an active session.

Properties

session-idstringtimestampnumber

Parameter	Type	Required	Description
session-id	string	—
timestamp	number	—

end-session

Ends an active conversation session.

Properties

session-idstring

Parameter	Type	Required	Description
session-id	string	—

Events

session-started

Emitted when a new session begins.

Properties

session-idstringformat-idstringtimestampDate

Parameter	Type	Required	Description
session-id	string	—
format-id	string	—
timestamp	Date	—

moment-marked

Emitted when a user taps to mark an important moment.

Properties

marker-idstringsession-idstringtimestampDate

Parameter	Type	Required	Description
marker-id	string	—
session-id	string	—
timestamp	Date	—

session-ended

Emitted when a session concludes.

Properties

session-idstringdurationnumbertimestampDate

Parameter	Type	Required	Description
session-id	string	—
duration	number	—
timestamp	Date	—

Operations

write

enforce-timing

Manages the turn-taking and timers defined by a format.

Input Parameters

session-idstringformat-idstring

Parameter	Type	Required	Description
session-id	string	—
format-id	string	—

Errors

Error ID	Code	Category	Description
session-not-found	TODO	domain	Thrown when a requested session does not exist.

Policies

Source	Condition	Reaction	Rule
start-session	—	start-recording	Recording begins automatically when a session starts successfully.
end-session	—	stop-recording	Recording is stopped when a session ends successfully.
session-ended	—	request-transcription	Transcription is requested automatically after every session ends.

Reactive Topology

autoflow Conversation reactive topology

Gallery Source ⛶

Diagram Syntax Error

flowchart LR;
    classDef actionNode fill:#e3f2fd,stroke:#1e88e5,color:#0d47a1;
    classDef eventNode fill:#e8f5e9,stroke:#4caf50,color:#1b5e20;
    classDef errorNode fill:#ffebee,stroke:#ef5350,color:#b71c1c;
    classDef externalNode fill:#f5f5f5,stroke:#9e9e9e,color:#616161,stroke-dasharray:4 4;
    subgraph audio ["Audio"]
        n7(["start-recording"])
        n8(["stop-recording"])
    end
    subgraph conversation ["Conversation"]
        n0(["start-session"])
        n1(["mark-moment"])
        n2(["end-session"])
        n3{{"session-started"}}
        n4{{"moment-marked"}}
        n5{{"session-ended"}}
        n6{{"session-not-found"}}
    end
    subgraph speech-to-text ["Speech-To-Text (STT)"]
        n9(["request-transcription"])
    end
    n0 -. "policy (success)" .-> n7
    n2 -. "policy (success)" .-> n8
    n5 -. "auto-transcription" .-> n9
    n0 -- success --> n3
    n2 -- success --> n5
    n1 -- success --> n4
    class n0,n1,n2 actionNode;
    class n3,n4,n5 eventNode;
    class n6 errorNode;
    class n7,n8,n9 externalNode;
    click n0 href "/domains/conversation#start-session" _self;
    click n1 href "/domains/conversation#mark-moment" _self;
    click n2 href "/domains/conversation#end-session" _self;
    click n3 href "/domains/conversation#session-started" _self;
    click n4 href "/domains/conversation#moment-marked" _self;
    click n5 href "/domains/conversation#session-ended" _self;
    click n6 href "/domains/conversation#session-not-found" _self;
    click n7 href "/domains/audio#start-recording" _self;
    click n8 href "/domains/audio#stop-recording" _self;
    click n9 href "/domains/speech-to-text#request-transcription" _self;