Skip to content

overview.md

Latest commit

 

History

History
247 lines (198 loc) · 7.55 KB

overview.md

File metadata and controls

247 lines (198 loc) · 7.55 KB
Raw

Architecture Overview

Last Updated: 2026-05-24

System Overview

Promptimize is a VSCode/Cursor extension that:

  1. Captures audio via native @kstonekuan/audio-capture
  2. Transcribes with OpenAI Whisper (always required)
  3. Transforms transcribed speech into structured prompts via a configurable provider (ADR-0014)
  4. Inserts the result into the editor, chat, or clipboard

For setup and provider selection, see the Configuration Guide.

High-Level Architecture

flowchart TB
    User[User]

    subgraph Presentation["Presentation Layer"]
        StatusBar[Status Bar UI]
        Commands[VSCode Commands]
        ConfigPanel[Configuration Webview]
    end

    subgraph Application["Application Layer"]
        UseCases[Use Cases]
        Ports[Ports/Interfaces]
    end

    subgraph Domain["Domain Layer"]
        Entities[Entities]
        ValueObjects[Value Objects]
        BusinessRules[Business Rules]
    end

    subgraph Infrastructure["Infrastructure Layer"]
        AudioAdapter[Native Audio Recorder]
        WhisperAdapter[Whisper Service]
        ProviderFactory[Prompt Transformer Factory]
        InsertionAdapters[Text Inserters]
        ConfigAdapter[Config Repository]
        StorageAdapter[Secret Storage]
    end

    subgraph External["External Services"]
        OpenAI[OpenAI API]
        OtherLLMs[Anthropic / Google / Azure / Ollama / OpenCode / OpenRouter / Cursor]
        VSCodeAPI[VSCode API]
    end

    User -->|Interact| Presentation
    Presentation -->|Execute| Application
    Application -->|Use| Domain
    Application -->|Through Ports| Infrastructure
    Infrastructure -->|Call| External
Loading

Architectural Style

Promptimize follows Clean/Hexagonal Architecture (ports and adapters). Rationale and alternatives are documented in ADR-0002.

Why this matters for this project:

  • Multiple external integrations (Whisper, several LLM providers, VSCode APIs, native audio)
  • Swappable transformation providers without changing use cases
  • Business logic testable with mocked ports

Layer Architecture

Presentation ──→ Application ──→ Domain
                      ▲
Infrastructure ───────┘
Layer Location Responsibility
Domain src/domain/ Entities, value objects, domain errors — no framework imports
Application src/application/ Use cases, port interfaces, DTOs
Infrastructure src/infrastructure/ Port implementations (audio, Whisper, transformers, config, storage)
Presentation src/presentation/ Commands, status bar, configuration webview

Dependency rule: Inner layers never depend on outer layers. Presentation orchestrates use cases; it does not call infrastructure directly.

Component Diagram

graph TB
    subgraph Presentation["Presentation Layer"]
        CMD[Commands]
        SB[StatusBarItem]
        CFG[ConfigurationPanel]
    end

    subgraph Application["Application Layer"]
        UC1[StartRecordingUseCase]
        UC2[StopRecordingUseCase]
        UC3[TranscribeAudioUseCase]
        UC4[TransformPromptUseCase]
        UC5[InsertTextUseCase]

        PORT1[IAudioRecorder]
        PORT2[ITranscriptionService]
        PORT3[IPromptTransformer]
        PORT4[ITextInserter]
        PORT5[IConfigRepository]
    end

    subgraph Infrastructure["Infrastructure Layer"]
        AUDIO[NativeAudioRecorder]
        WHISPER[OpenAIWhisperService]
        FACTORY[PromptTransformerFactory]
        GPT[OpenAIPromptTransformer]
        CLAUDE[AnthropicPromptTransformer]
        GEMINI[GooglePromptTransformer]
        AZURE[AzureOpenAIPromptTransformer]
        OLLAMA[OllamaPromptTransformer]
        OPENCODE[OpenCodePromptTransformer]
        OPENROUTER[OpenRouterPromptTransformer]
        CURSOR[CursorPromptTransformer]
        INSERT1[ChatParticipantInserter]
        INSERT2[EditorTextInserter]
        INSERT3[FallbackTextInserter]
        CONFIG[VSCodeConfigRepository]
    end

    CMD --> UC1
    CMD --> UC2
    SB --> CMD
    CFG --> CONFIG

    UC1 --> PORT1
    UC3 --> PORT2
    UC4 --> PORT3
    UC5 --> PORT4

    AUDIO --> PORT1
    WHISPER --> PORT2
    FACTORY --> GPT
    FACTORY --> CLAUDE
    FACTORY --> GEMINI
    FACTORY --> AZURE
    FACTORY --> OLLAMA
    FACTORY --> OPENCODE
    FACTORY --> OPENROUTER
    FACTORY --> CURSOR
    GPT --> PORT3
    CLAUDE --> PORT3
    GEMINI --> PORT3
    AZURE --> PORT3
    OLLAMA --> PORT3
    OPENCODE --> PORT3
    OPENROUTER --> PORT3
    CURSOR --> PORT3
    INSERT1 --> PORT4
    INSERT2 --> PORT4
    INSERT3 --> PORT4
    CONFIG --> PORT5
Loading

Data Flow

End-to-end recording flow with error branches: see Complete Flow.

sequenceDiagram
    actor User
    participant UI as Status Bar
    participant UC as StopRecording Pipeline
    participant Audio as NativeAudioRecorder
    participant Whisper as OpenAI Whisper
    participant Transform as PromptTransformer
    participant Insert as TextInserter

    User->>UI: Toggle recording (stop)
    UI->>UC: execute()
    UC->>Audio: stopRecording()
    Audio-->>UC: AudioData
    UC->>Whisper: transcribe(audioData)
    Whisper-->>UC: TranscriptionResult
    opt Optimization enabled
        UC->>Transform: transform(transcription)
        Transform-->>UC: TransformedPrompt
    end
    UC->>Insert: insert(text)
    Insert-->>UC: Success
    UC-->>UI: Update state
Loading

Technology Stack

Component Technology Purpose
Language TypeScript 5.4+ Type-safe development
Runtime Node.js 22 LTS Extension host
Framework VSCode Extension API 1.120+ Extension foundation
Bundler Webpack 5 Module bundling
Audio @kstonekuan/audio-capture Native microphone capture
Transcription OpenAI Whisper Speech-to-text
Transformation OpenAI, Anthropic, Google, Azure, Ollama, OpenCode, OpenRouter, Cursor Prompt optimization
Testing Jest Unit and integration tests

Technology decisions: ADR-0001, ADR-0013.

Design Patterns

Pattern Where ADR
Clean Architecture Layer structure 0002
Dependency Injection Constructor injection in use cases 0004
Chain of Responsibility Text insertion (chat → editor → clipboard) 0006
Strategy / Factory Swappable prompt transformers 0014
Adapter Infrastructure wraps external APIs —
Repository Configuration access abstraction —

Source Code Map

Concern Start here
Entry point & DI wiring src/extension.ts
Use cases src/application/use-cases/
Port interfaces src/application/ports/
Domain model src/domain/
External integrations src/infrastructure/
UI & commands src/presentation/

Related: Complete Flow · ADRs · Testing Strategy