noteflow/.rag/03-domain-ports.md

NoteFlow Domain Ports (Protocols)

Location

src/noteflow/domain/ports/

Repository Protocols (repositories/)

Core Repositories (transcript.py)

Protocol	Key Methods
MeetingRepository	add(), get(), list(), update(), delete(), count_by_state(), find_older_than()
SegmentRepository	add(), add_batch(), get(), list_by_meeting(), update(), delete()
SummaryRepository	add(), get(), list_by_meeting(), mark_verified()
AnnotationRepository	add(), get(), list_by_meeting(), update(), delete()

External Repositories

Protocol	Location	Purpose
AssetRepository	asset.py	Store/retrieve meeting audio files
DiarizationJobRepository	background.py	Track background diarization jobs
EntityRepository	external/_entity.py	Persist NER entities
IntegrationRepository	external/_integration.py	Store OAuth integrations
WebhookRepository	external/_webhook.py	Webhook configs and delivery logs
UsageEventRepository	external/_usage.py	Track usage metrics

Identity Repositories (identity/)

Protocol	Purpose
UserRepository	User identity and authentication
WorkspaceRepository	Workspace tenancy
ProjectRepository	Project CRUD and member access
ProjectMembershipRepository	Project role-based access
SummarizationTemplateRepository	Template CRUD and versioning

Engine/Provider Protocols

DiarizationEngine (diarization.py)

Speaker identification (streaming: diart, offline: pyannote)

• assign_speakers(audio: ndarray, segments: list[Segment]) -> list[SpeakerAssignment]
• is_ready() -> bool

NerPort (ner.py)

Named entity recognition with spaCy

• extract(text: str) -> list[NamedEntity]
• extract_from_segments(segments: list[Segment]) -> list[NamedEntity]
• is_ready() -> bool

OAuthPort (calendar.py)

OAuth PKCE flow

• initiate_auth(provider: str) -> AuthUrl
• complete_auth(code: str, state: str) -> TokenResponse

CalendarProvider (calendar.py)

Calendar event fetching

• list_events(start: datetime, end: datetime) -> list[CalendarEventInfo]

SummarizerProvider (summarization/ports.py)

LLM summarization

• request(context: SummarizationRequest) -> SummarizationResult

Unit of Work Pattern (unit_of_work.py)

Hierarchical Protocol Structure

UnitOfWorkCapabilities
├── supports_annotations: bool
├── supports_diarization_jobs: bool
├── supports_preferences: bool
├── supports_entities: bool
├── supports_integrations: bool
├── supports_webhooks: bool
├── supports_usage_events: bool
├── supports_users: bool
├── supports_workspaces: bool
├── supports_projects: bool

UnitOfWorkCoreRepositories
├── meetings: MeetingRepository
├── segments: SegmentRepository
├── summaries: SummaryRepository
├── assets: AssetRepository

UnitOfWorkOptionalRepositories
├── annotations: AnnotationRepository | None
├── diarization_jobs: DiarizationJobRepository | None
├── preferences: PreferencesRepository | None
├── entities: EntityRepository | None
├── integrations: IntegrationRepository | None
├── webhooks: WebhookRepository | None
├── usage_events: UsageEventRepository | None

UnitOfWorkLifecycle
├── __aenter__() / __aexit__()
├── commit() async
├── rollback() async

Key Data Classes

SummarizationRequest

@dataclass
class SummarizationRequest:
    meeting_id: MeetingId
    segments: list[Segment]
    template: SummarizationTemplate | None
    context: dict[str, str]

SummarizationResult

@dataclass
class SummarizationResult:
    summary: str
    key_points: list[KeyPoint]
    action_items: list[ActionItem]
    model_name: str
    provider_name: str
    tokens_used: int

CalendarEventInfo

@dataclass
class CalendarEventInfo:
    id: str
    title: str
    start_time: datetime
    end_time: datetime
    attendees: list[str]
    location: str | None
    description: str | None