noteflow/.rag/04-application-services.md

NoteFlow Application Services

Location

src/noteflow/application/services/

Core Services

MeetingService (meeting/)

Meeting lifecycle, segments, annotations, summaries, state.

Files:

• meeting_service.py - Composite class combining all mixins
• _base.py - Core initialization and dependencies
• _crud_mixin.py - Create, read, update, delete operations
• _segments_mixin.py - Segment management
• _summaries_mixin.py - Summary operations
• _state_mixin.py - State machine transitions
• _annotations_mixin.py - Annotation CRUD
• _types.py, _meeting_types.py - Service-specific TypedDicts

Key Methods:

• create_meeting(title, project_id) -> Meeting
• get_meeting(meeting_id) -> Meeting
• list_meetings(filters) -> list[Meeting]
• stop_meeting(meeting_id) -> Meeting
• add_segment(meeting_id, segment_data) -> Segment
• add_annotation(meeting_id, annotation_data) -> Annotation
• generate_summary(meeting_id, template_id) -> Summary

IdentityService (identity/)

User/workspace context, defaults, tenancy scoping.

Files:

• identity_service.py - Main service
• _context_mixin.py - Request context handling
• _workspace_mixin.py - Workspace operations
• _defaults_mixin.py - Default user/workspace creation

Key Methods:

• get_current_user() -> User
• get_current_workspace() -> Workspace
• switch_workspace(workspace_id) -> Workspace
• ensure_defaults() -> tuple[User, Workspace]

CalendarService (calendar/)

OAuth integration, event fetching, sync management.

Files:

• calendar_service.py - Main service
• _connection_mixin.py - OAuth connection handling
• _events_mixin.py - Event fetching
• _oauth_mixin.py - OAuth flow management
• _oauth_config_mixin.py - OAuth client configuration
• _service_mixin.py - Provider configuration
• _errors.py - Calendar-specific errors

Key Methods:

• initiate_oauth(provider) -> AuthUrl
• complete_oauth(code, state) -> Integration
• list_events(start, end) -> list[CalendarEvent]
• get_connection_status() -> ConnectionStatus

SummarizationService (summarization/)

Summary generation, template management, cloud consent.

Files:

• summarization_service.py - Main service
• template_service.py - Template CRUD
• _consent_manager.py - Cloud consent flow
• _template_ops.py - Template operations
• _provider_registry.py - Provider registration
• _citation_helper.py - Citation handling

Key Methods:

• generate_summary(meeting_id, template_id) -> Summary
• create_template(data) -> SummarizationTemplate
• list_templates() -> list[SummarizationTemplate]
• grant_consent() -> bool
• revoke_consent() -> bool
• has_consent() -> bool

ProjectService (project_service/)

Project CRUD, member management, roles, rules.

Files:

• __init__.py - Main service export
• crud.py - Project CRUD operations
• members.py - Member management
• roles.py - Role-based access
• rules.py - Project rules configuration
• active.py - Active project tracking
• _types.py - Service types

Key Methods:

• create_project(name, workspace_id) -> Project
• add_member(project_id, user_id, role) -> ProjectMembership
• update_member_role(project_id, user_id, role) -> ProjectMembership
• remove_member(project_id, user_id) -> bool
• set_active_project(project_id) -> Project

New Services (Strategy B)

AssistantService (assistant/)

AI chat interactions for meeting Q&A.

Files:

• assistant_service.py - Main service

Key Methods:

• ask(request: AssistantRequest) -> AssistantResponse
• stream(request: AssistantRequest) -> AsyncIterator[AssistantChunk]

AnalyticsService (analytics/)

Dashboard data aggregation and statistics.

Files:

• service.py - Main service
• refresh.py - Analytics refresh logic

Key Methods:

• get_overview(workspace_id, date_range) -> AnalyticsOverview
• get_speaker_stats(meeting_ids) -> list[SpeakerStat]
• get_entity_analytics(workspace_id, date_range) -> EntityAnalytics

TaskService (tasks/)

Action item management from meetings.

Files:

• service.py - Main service

Key Methods:

• list_tasks(filters) -> list[Task]
• create_task(request) -> Task
• update_task(task_id, updates) -> Task
• complete_task(task_id) -> Task

VoiceProfileService (voice_profile/)

Speaker voice enrollment for improved diarization.

Files:

• service.py - Main service

Key Methods:

• enroll_speaker(audio_data, speaker_name) -> VoiceProfile
• get_profile(profile_id) -> VoiceProfile
• list_profiles(workspace_id) -> list[VoiceProfile]

EmbeddingService (embedding/)

Vector embedding operations for semantic search.

Files:

• _embedding.py - Embedding logic

Key Methods:

• embed_text(text) -> list[float]
• embed_segments(segments) -> list[Embedding]

Configuration Services

AsrConfigService (asr_config/)

ASR model configuration and state management.

Files:

• service.py - Main service
• persistence.py - Config persistence
• types.py - Config types
• _engine_manager.py - ASR engine lifecycle
• _job_manager.py - Background job management

Key Methods:

• get_config() -> AsrConfig
• update_config(config) -> AsrConfig
• get_job_status(job_id) -> AsrJobStatus

StreamingConfigService (streaming_config/)

Audio streaming configuration.

Files:

• persistence.py - Config persistence

Key Methods:

• get_config() -> StreamingConfig
• update_config(config) -> StreamingConfig

Supporting Services

NerService (ner/)

Named entity extraction wrapper, model loading.

• extract_entities(meeting_id) -> list[NamedEntity]
• is_ready() -> bool
• _dedupe.py - Deduplication logic

ExportService (export/)

Transcript export (Markdown, HTML, PDF).

• export(meeting_id, format) -> ExportResult

WebhookService (webhooks/)

Webhook registration, delivery, retry logic.

• register_webhook(config) -> WebhookConfig
• deliver_event(event) -> WebhookDelivery

AuthService (auth/)

User authentication, OIDC integration.

Files:

• service.py - Main service
• workflows.py - Auth flow logic
• token_exchanger.py - Token exchange
• integration_manager.py - Integration management
• types.py - Auth types
• constants.py - Auth constants

Key Methods:

• initiate_login(provider) -> AuthUrl
• complete_login(code, state) -> User
• logout() -> bool

TriggerService (triggers/)

Calendar/audio/foreground-app trigger detection.

• check_triggers() -> list[TriggerSignal]
• snooze_triggers(duration) -> bool

RetentionService (retention/)

Automatic meeting deletion based on policy.

• apply_retention_policy() -> int

RecoveryService (recovery/)

Data recovery (meeting, job, audio).

Files:

• recovery_service.py - Main service
• _meeting_recoverer.py - Meeting recovery
• _job_recoverer.py - Job recovery
• _audio_validator.py - Audio validation

Key Methods:

• recover_meeting(meeting_id) -> Meeting
• recover_job(job_id) -> DiarizationJob

HfTokenService (huggingface/)

Hugging Face token management.

• set_token(token) -> bool
• get_status() -> HfTokenStatus
• validate_token() -> bool

Service Exports (__init__.py)

from noteflow.application.services import (
    MeetingService, IdentityService, ProjectService,
    SummarizationService, SummarizationTemplateService,
    AuthService, ExportService, RetentionService,
    TriggerService, RecoveryService,
    # ... and related types
)