Concepts

A shared vocabulary is not a cosmetic concern. When every engineer on the team means the same thing by "segment," "synthesis," or "task," design conversations become faster and bugs become easier to describe. This page is the canonical glossary of the domain; use it when writing code, specs, or tests.

Core entities

Meeting — the primary unit of work in Wordloop. A Meeting is a bounded session captured in the system, tied to a user, optionally attended by multiple People, and producing a Transcription, a MeetingSynthesis, and Tasks. The meetings table and the /meetings routes are the center of gravity for the entire platform.

Person — a contact record representing an attendee of one or more Meetings. A Person carries identity fields (display name, email, title, company) and an optional voice model used to attribute TranscriptSegments to a speaker. People are distinct from Users — a User is someone with a Wordloop account; a Person is someone who appeared in a meeting, with or without an account.

Transcription — the speech-to-text record attached to a Meeting. A Transcription aggregates TranscriptSegments as they are produced in near-real-time by the ML service and reaches a completed status when the meeting closes.

TranscriptSegment — the atomic unit of the Transcription. Each segment carries a speaker label, the attributed Person (if matched), text, start and end timestamps, a confidence score, and a is_final flag. Most ML processing — embeddings, topic extraction, synthesis — operates over segments.

MeetingSynthesis — the AI-generated summary attached to a Meeting. Contains a headline, a prose summary, key points, a list of Topics, and nested TalkingPoints. Produced by the ML service after the Transcription finalises; can be regenerated on demand.

Topic — a thematic cluster extracted from a Meeting's segments. Topics carry a name, a summary, and the set of TranscriptSegments that contributed to them. A Meeting has many Topics; a Topic belongs to one Meeting.

TalkingPoint — a specific point or claim within a Topic. TalkingPoints are the most granular unit of the MeetingSynthesis, surfaced in the recap UI as bullets under each Topic.

Task — an action item extracted from a Meeting. Tasks are assignable, trackable, and hierarchical (via parent_task_id). They live beyond the Meeting itself and are the primary output a user acts on after review. Status values: pending, in_progress, completed, canceled.

Supporting entities

User — a Wordloop account holder, identified via Clerk. A User has an associated Person record (the voice model and contact info for their own participation in meetings). JIT-provisioned on first sign-in.

Note — a free-form annotation attached to any entity (meeting, person, task, etc.) via a polymorphic subject_type / subject_id pair.

Tag — a label a user can apply to Meetings, People, or Tasks for organisation.

Cross-cutting concepts

Voice model — the speaker-identification vector attached to a Person. The ML service matches incoming audio against stored voice vectors to attribute TranscriptSegments to a specific Person rather than an anonymous SpeakerLabel. Voice models are built incrementally from verified segments.

JIT provisioning — "just-in-time" user creation. When a user signs in via Clerk for the first time, the Core API reads their Clerk profile and creates both the local User record and the corresponding Person record on demand. No webhooks, no seeding.

Echo suppression — the mechanism by which a person's own outgoing audio is not re-ingested as incoming segments. A subtle but load-bearing piece of the real-time pipeline; see Real-Time principles for the design model.

Further reading

• Architecture Overview — how these entities are distributed across services.
• Data Flow — the lifecycle of a segment, from microphone to synthesis.
• Reference / Glossary — the complete, link-resolvable vocabulary.