markupr 2.1.8 → 2.5.0

package/docs/ARCHITECTURE.md

@@ -1,460 +0,0 @@
-# Architecture
-
-This document provides a high-level overview of markupr's architecture.
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Process Model](#process-model)
-- [State Management](#state-management)
-- [Data Flow](#data-flow)
-- [Service Architecture](#service-architecture)
-- [Security Model](#security-model)
-
-## Overview
-
-markupr is an Electron application with a React frontend. It follows Electron's multi-process architecture with clear separation between the main process (Node.js) and renderer process (Chromium).
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        markupr                              │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                  │
-│  ┌──────────────────┐                ┌──────────────────────┐   │
-│  │   Main Process   │◄──── IPC ─────►│  Renderer Process    │   │
-│  │    (Node.js)     │                │    (Chromium)        │   │
-│  │                  │                │                      │   │
-│  │  - Capture       │                │  - React UI          │   │
-│  │  - Transcription │                │  - Audio Capture     │   │
-│  │  - File I/O      │                │  - Visualization     │   │
-│  │  - Settings      │                │                      │   │
-│  │  - Hotkeys       │                │                      │   │
-│  └──────────────────┘                └──────────────────────┘   │
-│                                                                  │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Process Model
-
-### Main Process
-
-The main process handles:
-
-- **System Integration**: Tray icons, hotkeys, native menus
-- **Screen Capture**: Using Electron's desktopCapturer
-- **File Operations**: Saving sessions, screenshots
-- **Settings**: Persistent storage via electron-store
-- **Secure Storage**: API keys via keytar
-- **Updates**: Auto-updater
-- **Session Orchestration**: State machine, service coordination
-
-### Renderer Process
-
-The renderer process handles:
-
-- **User Interface**: React components
-- **Audio Capture**: Web Audio API (requires renderer for MediaDevices)
-- **Visualization**: Waveforms, transcription preview
-- **User Input**: Buttons, forms, drag operations
-
-### Preload Script
-
-The preload script bridges the two processes:
-
-- **Context Isolation**: Enabled for security
-- **Node Integration**: Disabled in renderer
-- **API Exposure**: via `contextBridge.exposeInMainWorld`
-
-```typescript
-// Preload exposes a safe API
-contextBridge.exposeInMainWorld('markupr', {
-  session: {
-    start: (sourceId) => ipcRenderer.invoke('markupr:session:start', sourceId),
-    // ...
-  },
-  // ...
-});
-```
-
-## State Management
-
-### Session State Machine
-
-The session follows a finite state machine pattern:
-
-```
-                    ┌───────────────────────────────────────┐
-                    │                                       │
-                    ▼                                       │
-┌──────┐  start  ┌───────────┐  stop   ┌────────────┐     │
-│ idle │────────►│ recording │───────►│ processing │─────┘
-└──────┘         └───────────┘         └────────────┘
-   ▲                  │                      │
-   │                  │ cancel               │ complete
-   │                  │                      │
-   │                  ▼                      ▼
-   │              ┌──────┐             ┌──────────┐
-   └──────────────│ idle │◄────────────│ complete │
-                  └──────┘             └──────────┘
-```
-
-**States**:
-- `idle`: No active session
-- `recording`: Capturing audio and screenshots
-- `processing`: Generating output
-- `complete`: Session saved
-
-### State in Main Process
-
-```typescript
-// SessionController manages state
-class SessionController {
-  private state: SessionState = 'idle';
-  private session: Session | null = null;
-
-  async start(sourceId: string): Promise<void> {
-    if (this.state !== 'idle') throw new Error('Invalid state');
-    this.state = 'recording';
-    // ...
-  }
-}
-```
-
-### State in Renderer
-
-React components subscribe to state changes:
-
-```tsx
-function App() {
-  const [state, setState] = useState<SessionState>('idle');
-
-  useEffect(() => {
-    const unsubscribe = window.markupr.session.onStateChange(({ state }) => {
-      setState(state);
-    });
-    return unsubscribe;
-  }, []);
-}
-```
-
-## Data Flow
-
-### Recording Flow
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        Recording Flow                            │
-└─────────────────────────────────────────────────────────────────┘
-
-User speaks
-    │
-    ▼
-┌──────────────────┐
-│  AudioCapture    │  (Renderer - Web Audio API)
-│  (Renderer)      │
-└────────┬─────────┘
-         │ Audio chunks (100ms)
-         ▼
-┌──────────────────┐
-│  Main Process    │  IPC: AUDIO_CHUNK
-│                  │
-└────────┬─────────┘
-         │
-         ├────────────────────────┐
-         │                        │
-         ▼                        ▼
-┌──────────────────┐    ┌──────────────────┐
-│ Transcription    │    │ Intelligent      │
-│ Service          │    │ Capture          │
-│ (OpenAI WS)    │    │                  │
-└────────┬─────────┘    └────────┬─────────┘
-         │                        │
-         │ Transcript             │ Voice pause detected
-         │                        │
-         ▼                        ▼
-┌──────────────────┐    ┌──────────────────┐
-│ Session          │    │ Screen           │
-│ Controller       │◄───│ Capture          │
-│                  │    │                  │
-└────────┬─────────┘    └──────────────────┘
-         │
-         │ Feedback item
-         │
-         ▼
-┌──────────────────┐
-│  Renderer        │  IPC: SESSION_FEEDBACK_ITEM
-│  (UI Update)     │
-└──────────────────┘
-```
-
-### Export Flow
-
-```
-User clicks Export
-    │
-    ▼
-┌──────────────────┐
-│  ExportDialog    │  User selects format
-│  (Renderer)      │
-└────────┬─────────┘
-         │
-         ▼
-┌──────────────────┐
-│  Main Process    │  IPC: OUTPUT_EXPORT
-│                  │
-└────────┬─────────┘
-         │
-         ▼
-┌──────────────────┐
-│  ExportService   │  Generates document
-│                  │
-└────────┬─────────┘
-         │
-         ├───────────────────────────────┐
-         │                               │
-         ▼                               ▼
-┌──────────────────┐           ┌──────────────────┐
-│ Markdown         │           │ PDF / HTML       │
-│ Generator        │           │ Generator        │
-└────────┬─────────┘           └────────┬─────────┘
-         │                               │
-         └───────────────┬───────────────┘
-                         │
-                         ▼
-                ┌──────────────────┐
-                │  FileManager     │  Saves to disk
-                └──────────────────┘
-```
-
-## Service Architecture
-
-### Main Process Services
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                     Main Process Services                        │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                  │
-│  ┌─────────────────────────────────────────────────────────┐   │
-│  │                  SessionController                       │   │
-│  │  - State machine                                         │   │
-│  │  - Service coordination                                  │   │
-│  │  - Event emission                                        │   │
-│  └─────────────────────────────────────────────────────────┘   │
-│         │                │                │                     │
-│         │                │                │                     │
-│         ▼                ▼                ▼                     │
-│  ┌───────────┐    ┌───────────┐    ┌───────────┐              │
-│  │ Capture   │    │Transcript │    │  Output   │              │
-│  │ Service   │    │ Service   │    │ Service   │              │
-│  └───────────┘    └───────────┘    └───────────┘              │
-│                                                                  │
-│  ┌───────────┐    ┌───────────┐    ┌───────────┐              │
-│  │  Hotkey   │    │   Tray    │    │ Settings  │              │
-│  │  Manager  │    │  Manager  │    │  Manager  │              │
-│  └───────────┘    └───────────┘    └───────────┘              │
-│                                                                  │
-│  ┌───────────┐    ┌───────────┐    ┌───────────┐              │
-│  │   Menu    │    │  Crash    │    │   Auto    │              │
-│  │  Manager  │    │ Recovery  │    │  Updater  │              │
-│  └───────────┘    └───────────┘    └───────────┘              │
-│                                                                  │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### Service Descriptions
-
-| Service | Responsibility |
-|---------|----------------|
-| **SessionController** | Orchestrates recording sessions, manages state |
-| **CaptureService** | Screen capture via desktopCapturer |
-| **IntelligentCapture** | Voice-triggered screenshot timing |
-| **TranscriptionService** | OpenAI WebSocket integration |
-| **OutputService** | Document generation coordination |
-| **HotkeyManager** | Global hotkey registration |
-| **TrayManager** | System tray icon and menu |
-| **MenuManager** | Native application menu |
-| **SettingsManager** | Persistent settings via electron-store |
-| **CrashRecovery** | Session recovery after crashes |
-| **AutoUpdater** | Application updates |
-
-### Service Communication
-
-Services communicate through:
-
-1. **Direct method calls** (same process)
-2. **Events** (pub/sub pattern)
-3. **IPC** (between processes)
-
-```typescript
-// SessionController coordinates services
-class SessionController {
-  constructor(
-    private capture: CaptureService,
-    private transcription: TranscriptionService,
-    private output: OutputService,
-  ) {}
-
-  async start(sourceId: string) {
-    // Direct method calls
-    await this.capture.start(sourceId);
-    await this.transcription.connect();
-
-    // Event subscription
-    this.transcription.on('transcript', (text) => {
-      this.handleTranscript(text);
-    });
-  }
-}
-```
-
-## Security Model
-
-### Context Isolation
-
-The renderer process is sandboxed:
-
-```typescript
-// main/index.ts
-new BrowserWindow({
-  webPreferences: {
-    contextIsolation: true,   // Enabled
-    nodeIntegration: false,   // Disabled
-    preload: 'preload.js',    // Bridge
-  },
-});
-```
-
-### Secure API Key Storage
-
-API keys are stored using system keychain:
-
-```typescript
-// macOS: Keychain
-// Windows: Credential Manager
-// Linux: Secret Service
-
-import keytar from 'keytar';
-
-await keytar.setPassword('markupr', 'openai', apiKey);
-const key = await keytar.getPassword('markupr', 'openai');
-```
-
-### Content Security Policy
-
-```html
-<meta http-equiv="Content-Security-Policy"
-      content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'">
-```
-
-### IPC Security
-
-All IPC channels are:
-- Explicitly defined in shared types
-- Validated in handlers
-- Never expose raw Node.js APIs
-
-```typescript
-// Safe: Defined channel with specific handler
-ipcMain.handle('markupr:session:start', async (_, sourceId: string) => {
-  // Validate input
-  if (typeof sourceId !== 'string') throw new Error('Invalid sourceId');
-  return sessionController.start(sourceId);
-});
-
-// Unsafe (never do this): Exposing arbitrary execution
-ipcMain.handle('execute', (_, code) => eval(code)); // NEVER!
-```
-
-## Diagrams
-
-### Component Interaction
-
-```mermaid
-graph TD
-    subgraph Renderer
-        UI[React UI]
-        AC[Audio Capture]
-    end
-
-    subgraph Preload
-        API[markupr API]
-    end
-
-    subgraph Main
-        SC[Session Controller]
-        TC[Transcription]
-        CC[Capture]
-        HK[Hotkeys]
-        TR[Tray]
-    end
-
-    UI --> API
-    AC --> API
-    API --> SC
-    SC --> TC
-    SC --> CC
-    HK --> SC
-    TR --> SC
-```
-
-### Recording Sequence
-
-```mermaid
-sequenceDiagram
-    participant U as User
-    participant R as Renderer
-    participant M as Main
-    participant D as OpenAI
-
-    U->>R: Press hotkey
-    R->>M: session.start(sourceId)
-    M->>M: Initialize capture
-    M->>D: Connect WebSocket
-    D-->>M: Connection ready
-
-    loop Recording
-        R->>M: Audio chunk
-        M->>D: Send audio
-        D-->>M: Transcript
-        M-->>R: Feedback item
-        Note over M: Voice pause detected
-        M->>M: Capture screenshot
-        M-->>R: Screenshot captured
-    end
-
-    U->>R: Press hotkey
-    R->>M: session.stop()
-    M->>D: Close connection
-    M->>M: Generate output
-    M-->>R: Session complete
-```
-
-### Data Model
-
-```mermaid
-erDiagram
-    Session ||--o{ FeedbackItem : contains
-    FeedbackItem ||--o| Screenshot : has
-    Session ||--o{ Screenshot : buffers
-    Session {
-        string id
-        number startTime
-        number endTime
-        string sourceId
-        SessionState state
-    }
-    FeedbackItem {
-        string id
-        number timestamp
-        string text
-        number confidence
-    }
-    Screenshot {
-        string id
-        number timestamp
-        Buffer data
-        number width
-        number height
-    }
-```