Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
60 lines (54 loc) · 3.63 KB

ARCHITECTURE.md

File metadata and controls

60 lines (54 loc) · 3.63 KB
Raw

Conversation utilities

Shared conversation-domain helpers used by API routes, Pusher, sync workers, and background processing.

Boundaries

  • factory.py, location.py, search.py, and transcript_chunks.py provide serialization, lookup, and read-model helpers; callers retain ownership of request authentication and response shaping.

  • process_conversation.py is the synchronous enrichment coordinator. It persists the completed conversation and delegates expensive child work to the named executor lanes.

  • wake_word.py owns the pure, end-of-conversation matcher and trusted inline prompt marker. It has no realtime state, I/O, or speaker-identity gate. The independent invocation classifier lives in utils/llm/; task-intelligence capture owns the conjunction gate that consumes its validated verdicts.

  • finalizer.py is the durable handoff boundary for a persisted conversation. A caller must have already acquired a finalization-job lease before invoking it; it loads the conversation, performs enrichment through the postprocess bulkhead, and runs external integrations.

  • meeting_treatment.py owns the post-capture meeting policy. It uses durable conversation timestamps plus the union of transcribed-speech intervals, so dual microphone/system-audio transcripts cannot double-count speech.

  • duration.py owns the single conversation-duration rule shared with the Flutter and macOS clients: the transcript span (largest validated segment end), falling back to the wall window when no segment survives validation — whether the record is transcript-free or its segments are all malformed (the malformed-doc branch records a fallback so ops can see the degradation). started_at is the streaming-session origin, so no caller may recompute finished_at - started_at as a user-visible or policy duration.

  • overview_markdown.py renders notes-v2 structured.overview markdown to a closed HTML subset for the share-email body (headings, lists, emphasis, http(s) links; every text node escaped).

  • meeting_receipt.py is the sole writer of the final meeting verdict. It records reason and measured inputs on the finalization job, projects the verdict to the conversation, and attaches the deterministic Chat intent.

  • typesense_index.py owns the first-party Typesense projection of the durable conversation store. It is called fail-open from the conversation write/delete choke points (database/conversations.py durable mutations, lifecycle.delete_empty_recording_conversation, and the account-deletion purge), never from routers. Dual-writes on top of the still-installed Firebase extension firestore-typesense-conversations; the extension is removed only after this writer has baked (see the module runbook note).

  • The old orphaned WAV retranscription util (postprocess_conversation.py) was removed: the historical Flutter upload (memoryPostProcessing) and POST /v1/memories/{id}/post-processing router were removed and nothing imported the util. (Historical note: short-audio cancels were caused by the old client stripping quietSecondsForMemoryCreation (120s) from the WAV before upload, not by backend truncation.)

  • Route- or worker-specific ownership, retries, queues, and leases belong outside this package: database/conversation_finalization_jobs.py, services/conversation_finalization.py, and their callers own those states.

Data and credential safety

This package receives persisted conversation data only. Request-scoped BYOK context may be propagated by a live Pusher caller into finalizer.py, but it must never be written here, passed to durable task payloads, or logged.