SessionScribe

SessionScribe is a Windows desktop application for recording therapy sessions with live transcription, PHI redaction, and automated DAP note generation.

Features

• WebRTC Audio Capture: Real-time microphone access with device selection and level monitoring
• Live Transcription: Real-time speech-to-text with <2s P95 latency using faster-whisper
• Dual View Modes: Unified timeline or separate therapist/client lanes for transcription display
• Latency Monitoring: Real-time P95/P99 latency tracking with performance alerts
• PHI Redaction: Automatic detection and redaction of personal health information using regex patterns and spaCy NER
• DAP Note Generation: Automated clinical note generation using OpenAI API with schema validation
• Insights Dashboard: Optional session insights extraction with offline/redaction gates
• Privacy First: Offline-capable, redaction-required before any network transmission
• Native Performance: Built with Tauri for native Windows performance and smaller bundle size

Architecture

SessionScribe/
├── apps/desktop/
│   ├── src-tauri/        # Tauri Rust backend & configuration
│   └── renderer/          # React UI with Tailwind CSS
├── services/
│   ├── asr/              # Audio recording + Whisper transcription
│   ├── redaction/        # PHI detection & redaction
│   ├── note_builder/     # DAP note generation via OpenAI
│   └── insights_bridge/  # Session insights (optional)
├── packages/shared/
│   ├── schemas/          # JSON schemas for validation
│   └── prompts/          # LLM prompt templates
├── tests/                # Unit, integration & E2E tests
├── tools/openapi/        # API schema management tools
└── scripts/ci/           # CI/CD automation scripts

API Versioning

SessionScribe uses versioned APIs to maintain backward compatibility:

• Current Version: /v1 - All new features and endpoints
• Legacy Routes: Automatically redirect to /v1 with deprecation headers
• Breaking Changes: Only introduced in new major versions
• Schema Contracts: Automatically validated and version-pinned

Service Endpoints:

• ASR Service: http://localhost:7031/v1/ (docs)
• Redaction Service: http://localhost:7032/v1/ (docs)
• Insights Bridge: http://localhost:7033/v1/ (docs)
• Note Builder: http://localhost:7034/v1/ (docs)

Quick Start

Prerequisites

• Windows 10/11
• Python 3.11+
• Node.js 18+
• pnpm
• Rust 1.70+ (for Tauri backend)
• Visual Studio Build Tools (Windows SDK)

Installation

1. Clone and setup:

   git clone <repository>
   cd SessionScribe

2. Install Tauri dependencies:

   .\scripts\install-tauri-deps.ps1

3. Run SessionScribe (PRIMARY METHOD):

   .\launch-tauri.ps1

   Or manually:

   .\scripts\dev.ps1

4. Start the application:

   # Simple one-command start (Windows)
   .\launch-tauri.ps1
   
   # Or manually start services:
   # Terminal 1: Backend services
   .\.venv\Scripts\python.exe -m uvicorn services.asr.app:app --host 127.0.0.1 --port 7031
   .\.venv\Scripts\python.exe -m uvicorn services.redaction.app:app --host 127.0.0.1 --port 7032
   .\.venv\Scripts\python.exe -m uvicorn services.insights_bridge.app:app --host 127.0.0.1 --port 7033
   .\.venv\Scripts\python.exe -m uvicorn services.note_builder.app:app --host 127.0.0.1 --port 7034
   
   # Terminal 2: Start Tauri app
   pnpm -C apps/desktop tauri dev

Environment Configuration

Copy .env.example to .env and configure:

# Required for AI features  
OPENAI_API_KEY=your_api_key_here

# Application settings
SS_OFFLINE=false
SS_OUTPUT_DIR=%USERPROFILE%\Documents\SessionScribe

# Port configuration (optional, defaults shown)
VITE_RENDERER_PORT=3001
VITE_ASR_PORT=7031
VITE_REDACTION_PORT=7032
VITE_INSIGHTS_PORT=7033
VITE_NOTE_BUILDER_PORT=7034

Port Configuration: All service ports are configurable via environment variables with sensible defaults. The Tauri app connects to backend services on their respective ports.

Tauri Setup

For first-time setup or troubleshooting:

# Verify Tauri installation
pnpm -C apps/desktop tauri info

# Install Rust if needed
winget install Rustlang.Rust.MSVC

# Verify Windows SDK
pnpm -C apps/desktop tauri doctor

Usage

Recording Sessions

1. Setup: Select microphone device and session type
2. Record: Use Ctrl+R to start/stop recording
3. Monitor: Watch live audio levels and real-time transcription
4. Mark: Use Ctrl+Alt+M to bookmark important moments
5. View: Switch between unified timeline and separate lanes display

PHI Review

1. Review: Examine detected PHI entities with evidence
2. Accept/Reject: Approve or reject each redaction
3. Save: Generate redacted transcript file

Note Generation

1. Configure: Choose session type and note template
2. Generate: Create DAP note from redacted transcript
3. Validate: Ensure note meets schema requirements
4. Save: Export note as plain text file

Dashboard Insights (Optional)

1. Quick Redact: Process transcript for PHI
2. Select: Choose insight types (themes, questions, etc.)
3. Confirm: Review redaction before sending
4. Send: Get AI insights (requires online mode)

File Outputs

SessionScribe saves files to %USERPROFILE%\Documents\SessionScribe\:

• session_YYYYMMDD_HHMMSS_audio.wav - Stereo recording
• session_YYYYMMDD_HHMMSS_original.txt - Raw transcript
• session_YYYYMMDD_HHMMSS_redacted.txt - PHI-redacted transcript
• session_YYYYMMDD_HHMMSS_note.txt - Final DAP note

Security & Privacy

• Offline First: Default mode with no network access
• Redact Before Send: PHI removal required before API calls
• Local Storage: All transcripts and notes saved locally only
• No Telemetry: Zero analytics or crash reporting
• Content Isolation: No logging of session content

CI/CD Pipeline

SessionScribe uses automated CI/CD to ensure code quality and API contract stability.

Pipeline Overview

Our CI/CD pipeline validates all changes with comprehensive testing:

• Lint & Code Quality: Python (black, flake8, isort) and TypeScript (eslint)
• Contract Tests: Validates /v1 API contracts against baseline schemas
• E2E Tests: Full integration testing across all 4 services
• Schema Validation: Automatic detection of breaking API changes
• Drift Detection: Nightly monitoring for unexpected schema changes

Running CI Locally

# Run the full CI pipeline locally
docker-compose -f docker-compose.ci.yml up -d

# Wait for services to be healthy
scripts/ci/wait-for-services.sh

# Run contract tests for all services
scripts/ci/run-contracts.sh

# Or test a specific service
scripts/ci/run-contracts.sh asr

# Export current schemas for comparison
python tools/openapi/export_schemas.py

# Compare schemas for breaking changes
python tools/openapi/compare_schemas.py --fail-on-breaking

Manual Workflow Triggers

# Trigger CI manually (requires gh CLI)
gh workflow run ci.yml

# Run nightly drift detection
gh workflow run ci.yml --ref main

Contract Testing

API contracts are automatically validated on every PR:

1. Schema Export: Current schemas are exported from running services
2. Baseline Comparison: Changes are compared against approved baselines
3. Breaking Change Detection: Automatically flags backward-incompatible changes
4. PR Comments: Schema diffs are posted as PR comments for review

Schema Locations:

• Current schemas: artifacts/openapi/
• Baseline schemas: tests/contracts/schemas/
• Comparison reports: artifacts/schema-diff.md

Branch Protection

The main branch requires:

• ✅ All CI checks passing
• ✅ Contract tests passing
• ✅ No breaking schema changes (unless approved)
• ✅ At least 1 approving review

Nightly Monitoring

Automated nightly checks detect:

• Unexpected schema drift
• Service health issues
• Baseline schema updates needed

Alerts are automatically created as GitHub issues when drift is detected.

Development

Tauri Development

SessionScribe uses Tauri for the desktop application, providing native performance with a web-based UI.

Key Tauri Features:

• Rust backend for native Windows integration
• Web-based frontend (React + Tailwind CSS)
• Smaller bundle size compared to Electron
• Native system APIs access
• Enhanced security with capability-based permissions

Testing

# Python unit tests
pytest

# React component tests  
pnpm -C apps/desktop/renderer test

# Phase 3 audio pipeline tests
pnpm -C apps/desktop/renderer test Recorder.test.tsx
pnpm -C apps/desktop/renderer test LiveTranscriber.test.tsx
pytest tests/test_audio_pipeline_integration.py -v
pytest tests/test_latency_performance.py -v

# End-to-end tests
pnpm -C apps/desktop/renderer e2e

# Performance benchmarks
pytest tests/test_latency_performance.py::test_benchmark_against_target -v

Building

# Build for production
make build

# Create Windows installer
pnpm -C apps/desktop tauri build

# Development build
pnpm -C apps/desktop tauri dev

Quality Gates

• Latency: Live transcription P95 ≤ 2.0 seconds ✅
• Audio Quality: 48kHz 16-bit PCM capture ✅
• Real-time Display: <1s UI update latency ✅
• Redaction: Precision ≥ 90%, Recall ≥ 95%
• Validation: 100% JSON schema compliance
• Security: Zero PHI in logs or network requests

License

[License information to be added]

Support

For issues and feature requests, please use the GitHub issue tracker.