Files

Travis Vasceannie 40f9adf27f feat: introduce GLiNER and spaCy backends for NER, refactor NER infrastructure, and update client-side entity extraction.

2026-01-20 03:47:12 +00:00

30 KiB

Raw Blame History

╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ Strategic CLAUDE.md Placement Analysis for NoteFlow

Executive Summary

This document analyzes optimal placement of CLAUDE.md files throughout the NoteFlow codebase to provide meaningful context for AI assistants. The analysis considers both constrained (strategic) and unlimited scenarios.

Current State: Existing Documentation Files

10 CLAUDE.md/AGENTS.md Files Already Present ┌─────────────────────┬───────────┬──────────────────────────────────────────────────────────┐ │ Location │ File │ Focus │ ├─────────────────────┼───────────┼──────────────────────────────────────────────────────────┤ │ / │ CLAUDE.md │ Root orchestration, parallel execution, project overview │ ├─────────────────────┼───────────┼──────────────────────────────────────────────────────────┤ │ / │ AGENTS.md │ Architecture for non-Claude AI assistants │ ├─────────────────────┼───────────┼──────────────────────────────────────────────────────────┤ │ /src/ │ CLAUDE.md │ Python backend entry point │ ├─────────────────────┼───────────┼──────────────────────────────────────────────────────────┤ │ /src/ │ AGENTS.md │ Python backend for other AIs │ ├─────────────────────┼───────────┼──────────────────────────────────────────────────────────┤ │ /src/noteflow/ │ CLAUDE.md │ Detailed Python standards (line limits, typing, modules) │ ├─────────────────────┼───────────┼──────────────────────────────────────────────────────────┤ │ /src/noteflow/grpc/ │ CLAUDE.md │ gRPC security patterns │ ├─────────────────────┼───────────┼──────────────────────────────────────────────────────────┤ │ /src/noteflow/grpc/ │ AGENTS.md │ gRPC security (duplicate) │ ├─────────────────────┼───────────┼──────────────────────────────────────────────────────────┤ │ /client/ │ CLAUDE.md │ Tauri + React development │ ├─────────────────────┼───────────┼──────────────────────────────────────────────────────────┤ │ /client/src/ │ CLAUDE.md │ TypeScript security rules │ ├─────────────────────┼───────────┼──────────────────────────────────────────────────────────┤ │ /docker/ │ CLAUDE.md │ Docker security and build patterns │ └─────────────────────┴───────────┴──────────────────────────────────────────────────────────┘

Part 1: Strategic Placement (Constrained Resources)

If limited to 5-7 additional files, prioritize these high-impact locations:

Tier 1: Critical Gaps (Add These First)

/src/noteflow/infrastructure/CLAUDE.md

Why: Infrastructure layer has 15+ adapters with distinct patterns (ASR, diarization, NER, summarization, calendar, webhooks, persistence). No unified guidance exists.

/src/noteflow/domain/CLAUDE.md

Why: Domain layer defines entities, ports, rules, and value objects. Understanding DDD boundaries prevents architectural violations.

/src/noteflow/application/services/CLAUDE.md

Why: 12+ services with distinct responsibilities. Service-level guidance prevents duplication and clarifies orchestration patterns.

/client/src/hooks/CLAUDE.md

Why: 7 hook directories (audio, auth, data, processing, recording, sync, ui) with complex interdependencies. Prevents reinventing existing hooks.

/client/src-tauri/src/CLAUDE.md

Why: Rust backend has commands, gRPC client, audio processing, state management. No Rust-specific guidance currently exists.

Tier 2: High Value (Add Next)

/tests/CLAUDE.md

Why: Testing conventions (fixtures, markers, quality gates) are scattered. Centralized guidance improves test quality.

/src/noteflow/infrastructure/persistence/CLAUDE.md

Why: UnitOfWork pattern, repository hierarchy, capability flags, migrations are complex. Prevents incorrect persistence patterns.

Part 2: Unlimited Placement (Comprehensive Coverage)

With no constraints, here's the complete list of 25+ locations where CLAUDE.md would add value:

Python Backend (src/noteflow/) ┌────────────────────────────────────────┬─────────────────────────────────────────────────────────┐ │ Path │ Content Focus │ ├────────────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ domain/CLAUDE.md │ DDD entities, ports, value objects, rules engine │ ├────────────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ domain/entities/CLAUDE.md │ Entity relationships, state machines, invariants │ ├────────────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ domain/ports/CLAUDE.md │ Repository protocols, capability contracts │ ├────────────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ domain/rules/CLAUDE.md │ Rule modes (SIMPLE→EXPRESSION), registry, evaluation │ ├────────────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ application/CLAUDE.md │ Use case organization, service boundaries │ ├────────────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ application/services/CLAUDE.md │ Service catalog, dependency patterns │ ├────────────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ infrastructure/CLAUDE.md │ Adapter patterns, external integrations │ ├────────────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ infrastructure/asr/CLAUDE.md │ Whisper, VAD, segmentation, streaming │ ├────────────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ infrastructure/diarization/CLAUDE.md │ Job lifecycle, streaming vs offline, speaker assignment │ ├────────────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ infrastructure/ner/CLAUDE.md │ Backend abstraction, mapper, post-processing │ ├────────────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ infrastructure/summarization/CLAUDE.md │ Provider protocols, consent workflow, citation linking │ ├────────────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ infrastructure/persistence/CLAUDE.md │ UnitOfWork, repositories, migrations │ ├────────────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ infrastructure/calendar/CLAUDE.md │ OAuth flow, sync patterns, trigger detection │ ├────────────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ infrastructure/webhooks/CLAUDE.md │ Delivery, signing, retry logic │ ├────────────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ grpc/mixins/CLAUDE.md │ Mixin composition, streaming handlers │ ├────────────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ grpc/startup/CLAUDE.md │ Service initialization, dependency injection │ ├────────────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ config/CLAUDE.md │ Settings cascade, feature flags, environment loading │ ├────────────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ cli/CLAUDE.md │ Command patterns, model management │ └────────────────────────────────────────┴─────────────────────────────────────────────────────────┘ Client (client/) ┌──────────────────────────────────┬─────────────────────────────────────────────────────────┐ │ Path │ Content Focus │ ├──────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ src/api/CLAUDE.md │ Adapter pattern, transport abstraction, type generation │ ├──────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ src/components/CLAUDE.md │ Component hierarchy, feature organization │ ├──────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ src/hooks/CLAUDE.md │ Hook catalog, composition patterns, state management │ ├──────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ src/lib/CLAUDE.md │ Utility catalog, AI providers, audio processing │ ├──────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ src-tauri/src/CLAUDE.md │ Rust patterns, command handlers, state │ ├──────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ src-tauri/src/commands/CLAUDE.md │ IPC contract, audio commands, recording session │ ├──────────────────────────────────┼─────────────────────────────────────────────────────────┤ │ src-tauri/src/grpc/CLAUDE.md │ gRPC client wrapper, type conversions │ └──────────────────────────────────┴─────────────────────────────────────────────────────────┘ Testing (tests/) ┌─────────────────────────────┬────────────────────────────────────────────────────┐ │ Path │ Content Focus │ ├─────────────────────────────┼────────────────────────────────────────────────────┤ │ tests/CLAUDE.md │ Test conventions, fixtures, markers, quality gates │ ├─────────────────────────────┼────────────────────────────────────────────────────┤ │ tests/fixtures/CLAUDE.md │ Shared fixtures catalog, usage patterns │ ├─────────────────────────────┼────────────────────────────────────────────────────┤ │ tests/integration/CLAUDE.md │ Integration test setup, testcontainers │ └─────────────────────────────┴────────────────────────────────────────────────────┘ Documentation (docs/) ┌────────────────────────┬───────────────────────────────────────────┐ │ Path │ Content Focus │ ├────────────────────────┼───────────────────────────────────────────┤ │ docs/sprints/CLAUDE.md │ Sprint structure, documentation standards │ └────────────────────────┴───────────────────────────────────────────┘

Part 3: Mockup - /src/noteflow/infrastructure/CLAUDE.md

Infrastructure Layer Development Guide

Overview

The infrastructure layer (src/noteflow/infrastructure/) contains adapters that implement domain ports. These connect the application to external systems: databases, ML models, cloud APIs, file systems.

Architecture Principle: Hexagonal/Ports-and-Adapters

Domain Ports (interfaces) Infrastructure Adapters (implementations) ───────────────────────── ─────────────────────────────────────────── NerPort → SpacyBackend, GlinerBackend SummarizationProvider → CloudProvider, OllamaProvider, MockProvider DiarizationEngine → DiartSession, PyannoteOffline AssetRepository → FileSystemAssetRepository UnitOfWork → SqlAlchemyUnitOfWork, MemoryUnitOfWork CalendarProvider → GoogleCalendar, OutlookCalendar

Rule: Infrastructure code imports domain; domain NEVER imports infrastructure.

Adapter Catalog

Directory	Responsibility	Key Protocols
`asr/`	Speech-to-text (Whisper)	`TranscriptionResult`
`diarization/`	Speaker identification	`DiarizationEngine`, `DiarizationJob`
`ner/`	Named entity extraction	`NerPort`
`summarization/`	LLM summarization	`SummarizationProvider`
`persistence/`	Database (SQLAlchemy)	`UnitOfWork`, `*Repository`
`calendar/`	OAuth + event sync	`CalendarProvider`
`webhooks/`	Event delivery	`WebhookDeliveryService`
`export/`	PDF/HTML/Markdown	`ExportAdapter`
`audio/`	Recording/playback	`AudioDevice`
`crypto/`	Encryption	`Keystore`
`logging/`	Structured logging	`LogEventType`
`metrics/`	Observability	`MetricsCollector`
`gpu/`	GPU detection	`GpuInfo`

Common Patterns

1. Async Wrappers for Sync Libraries

Many ML libraries (spaCy, faster-whisper) are synchronous. Wrap them:

async def extract(self, text: str) -> list[NamedEntity]:
    loop = asyncio.get_running_loop()
    return await loop.run_in_executor(
        None,  # Default ThreadPoolExecutor
        self._sync_extract,
        text
    )

2. Backend Selection via Factory

def create_ner_engine(config: NerConfig) -> NerPort:
    match config.backend:
        case "spacy":
            return SpacyBackend(model=config.model_name)
        case "gliner":
            return GlinerBackend(model=config.model_name)
        case _:
            raise ValueError(f"Unknown NER backend: {config.backend}")

3. Capability Flags for Optional Features

class SqlAlchemyUnitOfWork(UnitOfWork):
    @property
    def supports_entities(self) -> bool:
        return True  # Has EntityRepository

    @property
    def supports_webhooks(self) -> bool:
        return True  # Has WebhookRepository

Always check capability before accessing optional repository:
if uow.supports_entities:
    entities = await uow.entities.get_by_meeting(meeting_id)

4. Provider Protocol Pattern

class SummarizationProvider(Protocol):
    async def summarize(
        self,
        segments: list[Segment],
        template: SummarizationTemplate,
    ) -> SummaryResult: ...

    @property
    def requires_consent(self) -> bool: ...

---
Forbidden Patterns

❌ Direct database access outside persistence/
# WRONG: Raw SQL in service layer
async with engine.connect() as conn:
    result = await conn.execute(text("SELECT * FROM meetings"))

❌ Hardcoded API keys
# WRONG: Secrets in code
client = anthropic.Anthropic(api_key="sk-ant-...")

❌ Synchronous I/O in async context
# WRONG: Blocking the event loop
def load_model(self):
    self.model = whisper.load_model("base")  # Blocks!

❌ Domain imports in infrastructure
# WRONG: Infrastructure should implement domain ports, not modify domain
from noteflow.domain.entities import Meeting
meeting.state = "COMPLETED"  # Don't mutate domain objects here

---
Testing Infrastructure Adapters

Use Dependency Injection for Mocking

# tests/infrastructure/ner/test_engine.py
@pytest.fixture
def mock_backend() -> NerBackend:
    backend = Mock(spec=NerBackend)
    backend.extract.return_value = [
        RawEntity(text="John", label="PERSON", start=0, end=4)
    ]
    return backend

async def test_engine_uses_backend(mock_backend):
    engine = NerEngine(backend=mock_backend)
    result = await engine.extract("Hello John")
    mock_backend.extract.assert_called_once()

Integration Tests with Real Services

# tests/integration/test_ner_integration.py
@pytest.mark.integration
@pytest.mark.requires_gpu
async def test_gliner_real_extraction():
    backend = GlinerBackend(model="urchade/gliner_base")
    result = await backend.extract("Microsoft CEO Satya Nadella announced...")
    assert any(e.label == "ORG" and "Microsoft" in e.text for e in result)

---
Adding a New Adapter

1. Define port in domain (domain/ports/) if not exists
2. Create adapter directory (infrastructure/<adapter_name>/)
3. Implement the protocol with proper async handling
4. Add factory function for backend selection
5. Write unit tests with mocked dependencies
6. Write integration test with real external service
7. Update gRPC startup (grpc/startup/services.py) for dependency injection
8. Document in this file (update Adapter Catalog table)

---
Key Files
┌───────────────────────────────┬──────────────────────────────────┐
│             File              │             Purpose              │
├───────────────────────────────┼──────────────────────────────────┤
│ __init__.py                   │ Public exports for layer         │
├───────────────────────────────┼──────────────────────────────────┤
│ */engine.py                   │ Main adapter implementation      │
├───────────────────────────────┼──────────────────────────────────┤
│ */backends/                   │ Multiple backend implementations │
├───────────────────────────────┼──────────────────────────────────┤
│ */mapper.py                   │ External→Domain type conversion  │
├───────────────────────────────┼──────────────────────────────────┤
│ */post_processing.py          │ Output normalization             │
├───────────────────────────────┼──────────────────────────────────┤
│ persistence/unit_of_work/*.py │ Transaction management           │
├───────────────────────────────┼──────────────────────────────────┤
│ persistence/repositories/*.py │ Data access                      │
├───────────────────────────────┼──────────────────────────────────┤
│ persistence/models/*.py       │ ORM definitions                  │
└───────────────────────────────┴──────────────────────────────────┘
---
See Also

- /src/noteflow/domain/ports/ — Port definitions
- /src/noteflow/grpc/startup/services.py — Dependency injection
- /tests/infrastructure/ — Adapter tests

---

## Part 4: Answer to "Would Your Answer Change With No Limit?"

**Yes, significantly.**

### Constrained (5-7 files):
Focus on **layer boundaries** (domain, application, infrastructure) and **high-complexity areas** (hooks, Rust backend). Each file covers broad territory.

### Unlimited (25+ files):
Add **subsystem-specific documentation** for:
- Complex state machines (diarization jobs, recording lifecycle)
- Protocol patterns (summarization providers, NER backends)
- Cross-cutting concerns (rules engine, settings cascade)
- Test organization (fixtures, integration setup)

The key difference: with unlimited resources, document **WHY decisions were made** (design rationale), not just **WHAT exists** (API reference).

---

## Recommendation

### Immediate Action (Phase 1)
Add these 3 files for maximum impact:
1. `/src/noteflow/infrastructure/CLAUDE.md` — Adapter patterns (mockup above)
2. `/src/noteflow/domain/CLAUDE.md` — DDD boundaries, entity relationships
3. `/client/src-tauri/src/CLAUDE.md` — Rust patterns, IPC contracts

### Follow-up (Phase 2)
4. `/src/noteflow/application/services/CLAUDE.md` — Service catalog
5. `/client/src/hooks/CLAUDE.md` — Hook organization
6. `/tests/CLAUDE.md` — Testing conventions

### Future (Phase 3)
Remaining 19+ files as the codebase grows and patterns stabilize.

30 KiB Raw Blame History