noteflow/.rag/06-grpc-layer.md

NoteFlow gRPC Layer

Location

src/noteflow/grpc/

Core Files

Service (service.py)

Main NoteFlowServicer - gRPC service implementation composing all mixins.

Client (client.py)

Python gRPC client wrapper for testing and internal use.

Proto (proto/noteflow.proto)

Service definition with bidirectional streaming and RPC methods.

Key RPC Groups:

• Streaming: StreamTranscription(AudioChunk) -> TranscriptUpdate (bidirectional)
• Meeting Lifecycle: CreateMeeting, StopMeeting, ListMeetings, GetMeeting, DeleteMeeting
• Summaries: GenerateSummary, ListSummarizationTemplates, CreateSummarizationTemplate
• Diarization: RefineSpeakerDiarization, RenameSpeaker, GetDiarizationJobStatus
• Annotations: AddAnnotation, GetAnnotation, ListAnnotations, UpdateAnnotation, DeleteAnnotation
• Export: ExportTranscript (Markdown, HTML, PDF)
• Calendar: Calendar event sync and OAuth
• Webhooks: Webhook config and delivery management
• OIDC: Authentication via OpenID Connect
• Tasks: Task CRUD (Strategy B)
• Analytics: Dashboard data aggregation (Strategy B)
• Assistant: AI chat interactions (Strategy B)

Server Mixins (mixins/)

Streaming Mixin (streaming/)

Bidirectional ASR streaming.

Files:

• _mixin.py - Main StreamingMixin
• _session.py - Stream session lifecycle
• _session_helpers.py - Session helper utilities
• _session_init_helpers.py - Session initialization
• _asr.py - ASR engine integration
• _metadata.py - Stream metadata handling
• _partials.py - Partial transcript handling
• _cleanup.py - Resource cleanup
• _types.py - Type definitions
• _processing/ - Audio processing pipeline
  • _audio_ops.py - Audio operations
  • _chunk_tracking.py - Chunk tracking
  • _congestion.py - Backpressure handling
  • _vad_processing.py - VAD processing
  • _constants.py, _types.py

Diarization Mixin (diarization/)

Speaker diarization (streaming + offline refinement).

Files:

• _mixin.py - Main DiarizationMixin
• _jobs.py - Background job management
• _job_validation.py - Job validation
• _streaming.py - Real-time diarization
• _refinement.py - Offline refinement with pyannote
• _execution.py - Job execution
• _speaker.py - Speaker assignment
• _status.py - Job status tracking
• _types.py - Type definitions

Summarization Mixin (summarization/)

Summary generation and templates.

Files:

• _generation_mixin.py - Summary generation flow
• _templates_mixin.py - Template CRUD mixin
• _template_crud.py - Template CRUD operations
• _consent_mixin.py - Cloud consent mixin
• _consent.py - Consent handling
• _summary_generation.py - Core generation logic
• _template_resolution.py - Template lookup
• _context_builders.py - Context preparation
• _constants.py - Summarization constants

Meeting Mixin (meeting/)

Meeting lifecycle management.

Files:

• meeting_mixin.py - Meeting state management
• _project_scope.py - Project scoping
• _stop_ops.py - Stop operations
• _post_processing.py - Post-meeting processing
• _title_generation.py - Auto title generation

Project Mixin (project/)

Project management operations.

Files:

• _mixin.py - Main ProjectMixin
• _membership.py - Member management
• _converters.py - Project converters

OIDC Mixin (oidc/)

OpenID Connect authentication.

Files:

• oidc_mixin.py - Main OidcMixin
• _support.py - OIDC support utilities

Converters (converters/)

Proto <-> Domain conversion.

Files:

• _domain.py - Domain entity conversion
• _external.py - External entity conversion
• _streaming.py - Streaming type conversion
• _timestamps.py - Timestamp conversion
• _id_parsing.py - ID parsing and validation
• _oidc.py - OIDC entity conversion
• _export.py - Export type conversion
• _task_analytics.py - Task/analytics conversion

Error Helpers (errors/)

gRPC error handling.

Files:

• _abort.py - abort_not_found(), abort_invalid_argument()
• _require.py - Precondition checks
• _fetch.py - Fetch with error handling
• _parse.py - Parsing helpers
• _webhooks.py - Webhook error handling
• _constants.py - Error constants

Other Mixins (Top-level files)

• annotation.py - Segment annotations CRUD
• asr_config.py - ASR configuration management
• assistant.py - AI assistant interactions (Strategy B)
• analytics_mixin.py - Analytics data (Strategy B)
• tasks.py - Task management (Strategy B)
• calendar.py - Calendar sync
• calendar_oauth_config.py - OAuth client config
• entities.py - Named entity extraction
• export.py - Export operations
• hf_token.py - HuggingFace token management
• identity.py - User/workspace identity
• observability.py - Usage tracking, metrics
• preferences.py - User preferences
• streaming_config.py - Streaming configuration
• sync.py - State synchronization
• webhooks.py - Webhook management
• diarization_job.py - Job status/management

Servicer Protocols

• servicer_core/protocols.py - Core servicer protocol
• servicer_other/protocols.py - Additional protocols
• protocols.py - ServicerHost protocol
• _repository_protocols.py - Repository protocols
• _servicer_state.py - Servicer state management

Supporting Modules

• _audio_processing.py - Audio utilities
• _metrics.py - gRPC metrics
• _model_status.py - Model status tracking
• _processing_status.py - Processing status
• _sync_execution.py - Sync execution helpers
• _task_callbacks.py - Task callback handling
• _types.py - Shared types

Server Bootstrap (server/)

Files:

• __main__.py - Server entry point
• __init__.py - Server exports
• health.py - Health check service

Startup (startup/)

Server startup sequence and service initialization.

Client Mixins (client_mixins/)

Client-side gRPC operations.

• streaming.py - Client streaming operations
• meeting.py - Meeting CRUD operations
• diarization.py - Diarization requests
• export.py - Export requests
• annotation.py - Annotation operations
• converters.py - Response converters
• protocols.py - ClientHost protocol

Interceptors (interceptors/)

gRPC interceptors for identity context propagation.

Types (types/)

gRPC-related type definitions.

Config (config/)

gRPC configuration.

Identity (identity/)

Identity management for gRPC context.

Critical Paths

Recording Flow

1. Client: StreamTranscription(AudioChunk) -> gRPC streaming
2. Server: StreamingMixin consumes chunks
3. ASR Engine: Transcribe via faster-whisper
4. VAD: Segment by silence
5. Diarization: Assign speakers (streaming)
6. Repository: Persist Segments
7. Client: Receive TranscriptUpdate with segments

Summary Generation Flow

1. Client: GenerateSummary(meeting_id) -> gRPC call
2. SummarizationService: Fetch segments
3. SummarizerProvider: Call LLM
4. Citation Verifier: Validate claims
5. Template Renderer: Apply template
6. Repository: Persist Summary
7. Client: Receive Summary