Overview

Relevant source files

• README.md
• README_EN.md
• docker-compose.yml
• docs/user/mcp-server.md
• docs/user/mcp-server_en.md
• env.local.example
• mkdocs/docs/zh/user/mcp-server.md
• package.json
• packages/core/package.json
• packages/core/src/services/model/defaults.ts
• packages/core/tests/unit/model/defaults.test.ts
• packages/desktop/package.json
• packages/extension/package.json
• packages/extension/public/manifest.json
• packages/mcp-server/package.json
• packages/mcp-server/src/config/models.ts
• packages/ui/package.json
• packages/ui/src/components/TestAreaPanel.vue
• packages/ui/src/components/app-layout/PromptOptimizerApp.vue
• packages/ui/src/components/context-mode/ContextSystemWorkspace.vue
• packages/ui/src/components/context-mode/ContextUserTestPanel.vue
• packages/ui/src/components/context-mode/ContextUserWorkspace.vue
• packages/ui/src/components/context-mode/ConversationTestPanel.vue
• packages/ui/src/i18n/locales/en-US.ts
• packages/ui/src/i18n/locales/zh-CN.ts
• packages/ui/src/i18n/locales/zh-TW.ts
• packages/web/package.json
• pnpm-lock.yaml
• vercel.json

Purpose and Scope

This document provides a high-level introduction to the Prompt Optimizer system, an AI prompt optimization tool that helps users improve their prompts for large language models (LLMs). This overview covers:

• The system's purpose and capabilities
• Overall architecture and design patterns
• Monorepo structure and package organization
• Multi-platform deployment strategy
• Function modes and workspace organization
• Core technology stack

For detailed information about specific subsystems:

• Monorepo structure and build system: see Monorepo Structure and Packages
• Platform-specific implementations: see Platform Implementations
• Core services architecture: see Core Services Layer
• UI components and patterns: see User Interface Layer

---

What is Prompt Optimizer?

Prompt Optimizer is a web-based AI prompt optimization tool that intelligently improves prompts for large language models. The system analyzes user-provided prompts and generates optimized versions that produce better, more consistent AI responses.

Key Capabilities:

• Dual Optimization Modes: System prompt optimization (for AI behavior/personality) and user prompt optimization (for user queries)
• Iterative Refinement: Multi-round optimization with version tracking and history management
• Multi-Model Support: Integration with OpenAI, Google Gemini, Anthropic Claude, DeepSeek, and other providers
• Image Generation: Text-to-image and image-to-image optimization support
• Advanced Features: Variable management, conversation context testing, function calling support
• Multi-Platform: Runs as web app, desktop app, Chrome extension, or MCP server

The application is a pure client-side tool—all data processing occurs in the browser or desktop app, with API calls made directly to AI service providers. No intermediate servers handle user data.

Sources: README.md23-55 packages/ui/src/i18n/locales/en-US.ts18-106

---

Architecture Overview

Prompt Optimizer follows a layered monorepo architecture with clear separation between shared libraries and platform-specific implementations:

Architecture Principles:

1. Platform-Agnostic Core (packages/core/): Contains all business logic with zero UI dependencies

   • Services: PromptService, LLMService, ImageService, EvaluationService
   • Managers: ModelManager, TemplateManager, HistoryManager, VariableManager
   • Adapters: TextAdapterRegistry, ImageAdapterRegistry with 10+ provider implementations
   • Storage: StorageProvider interface with IndexedDBStorageProvider, FileStorageProvider

2. Reusable UI Layer (packages/ui/): Vue 3 components and Pinia stores shared across platforms

   • Application shell: PromptOptimizerApp.vue with router-driven mode switching
   • Workspaces: BasicSystemWorkspace.vue, ContextUserWorkspace.vue, ImageText2ImageWorkspace.vue, etc.
   • Modals: ModelManagerUI.vue, TemplateManagerUI.vue, HistoryDrawerUI.vue
   • Stores: Mode-specific Pinia stores with automatic persistence

3. Thin Platform Wrappers: Minimal platform-specific code

   • Web (packages/web/src/main.ts): Direct mount of PromptOptimizerApp.vue
   • Desktop (packages/desktop/main.js): Electron IPC bridge + bundled web app
   • Extension (packages/extension/src/main.ts): Chrome extension popup wrapper
   • MCP Server (packages/mcp-server/src/start.ts): Express HTTP server exposing core services

4. Adapter Pattern: Provider integrations implement common interfaces

   • Text adapters: OpenAIAdapter, GeminiAdapter, AnthropicAdapter in packages/core/src/services/llm/adapters/
   • Image adapters: GeminiImageAdapter, OpenAIImageAdapter in packages/core/src/services/llm/adapters/

5. Storage Abstraction: Platform-specific persistence through unified interface

   • Browser: IndexedDBStorageProvider via Dexie
   • Desktop: FileStorageProvider writing to userData/data.json
   • Images: ImageStorageService with SHA-256 content-based deduplication

Sources: package.json1-107 packages/ui/src/components/app-layout/PromptOptimizerApp.vue1-70 packages/core/package.json1-46 packages/ui/package.json1-67

---

Monorepo Package Structure

The codebase is organized as a pnpm workspace monorepo with six packages and strict dependency order:

Package Details

Package	Key Files	Dependencies	Build Tool	Output Format
@prompt-optimizer/core	src/index.ts src/services/PromptService.ts src/managers/ModelManager.ts	None	tsup	CJS/ESM library dist/index.js, dist/index.cjs
@prompt-optimizer/ui	src/components/app-layout/PromptOptimizerApp.vue src/router/index.ts src/stores/sessions/	@prompt-optimizer/core	vite (lib mode)	ESM + CSS dist/index.js, dist/style.css
@prompt-optimizer/web	src/main.ts src/App.vue	@prompt-optimizer/ui	vite	Static site dist/index.html
@prompt-optimizer/desktop	main.js (Electron main) preload.js (contextBridge) web-dist/ (bundled web)	@prompt-optimizer/core Bundles web build	electron-builder	Native apps .exe, .dmg, .AppImage
@prompt-optimizer/extension	src/main.ts public/manifest.json background.js	@prompt-optimizer/ui	vite	Extension bundle dist/
@prompt-optimizer/mcp-server	src/start.ts src/index.ts	@prompt-optimizer/core	tsup	Node.js CLI dist/start.cjs

Build Order and Commands

The monorepo enforces a strict build order defined in package.json scripts:

1. Core Build (no dependencies):

2. UI Build (depends on core):

3. Platform Builds (parallel, depend on core/ui):

4. Full Build (orchestrates all):

Development Workflow

Development servers (with hot reload):

Sources: package.json11-59 packages/core/package.json16-24 packages/ui/package.json24-31 packages/web/package.json6-13 packages/desktop/package.json10-16 packages/extension/package.json6-11 packages/mcp-server/package.json11-17

---

Multi-Platform Deployment Architecture

The same codebase deploys to four distinct platforms through different entry points:

Platform Entry Points and Storage

Platform-Specific Features

Platform	Entry Point	Storage	Unique Features
Web	packages/web/src/main.ts	IndexedDB	Browser CORS restrictions
Desktop	packages/desktop/main.js	File system (userData)	IPC bridge, auto-updates, proxy support
Extension	packages/extension/src/main.ts	IndexedDB (extension storage)	Chrome API access, manifest v3
MCP	packages/mcp-server/src/start.ts	Environment variables	MCP protocol tools, HTTP server

Storage Strategy

Each platform uses a different StorageProvider implementation:

• IndexedDBStorageProvider: Used by web and extension for browser-based persistence
• FileStorageProvider: Used by desktop for file system persistence at app.getPath('userData')/data.json
• Environment Variables: MCP server reads configuration from process.env.VITE_* variables

All storage providers implement the same interface, allowing the core services to remain platform-agnostic.

Sources: packages/web/package.json1-36 packages/desktop/package.json1-99 packages/extension/package.json1-48 packages/mcp-server/package.json1-48

---

Function Modes and Workspaces

The application organizes functionality into three function modes with router-driven workspace selection:

Router-Driven Mode Architecture

Mode Characteristics

Function Mode	Submodes	Workspace Components	Key Features
Basic	system, user	BasicSystemWorkspace, BasicUserWorkspace	Simple prompt input/output, template selection
Pro/Context	multi, variable	ContextSystemWorkspace, ContextUserWorkspace	Variable management, conversation manager, tool calling
Image	text2image, image2image	ImageText2ImageWorkspace, ImageImage2ImageWorkspace	Image generation, parameter configuration

Workspace Component Pattern

Each workspace component follows a common structure:

1. Left Panel: Input area (prompt input, conversation manager, or image upload)
2. Right Panel: Test area (test execution, variable input, multi-column comparison)
3. Split Layout: Resizable divider between panels
4. Session Persistence: Mode-specific Pinia store for state management

Pro Mode Distinction:

• Multi-Message Mode (ContextSystemWorkspace): Includes ConversationManager for managing multi-turn conversations with system/user/assistant/tool messages
• Variable Mode (ContextUserWorkspace): Single prompt input with variable extraction and smart generation features

Sources: packages/ui/src/components/context-mode/ContextUserWorkspace.vue1-14 packages/ui/src/components/context-mode/ContextSystemWorkspace.vue1-27 packages/ui/src/i18n/locales/en-US.ts125-165

---

Core Service Architecture

The @prompt-optimizer/core package implements business logic through a layered service-oriented architecture:

Service and Manager Class Hierarchy

Service Responsibilities

PromptService: Main orchestration layer for optimization workflows

• Coordinates optimization requests with templates and models
• Manages iteration chains and version history
• Processes variables in prompts using TemplateProcessor

LLMService: Handles all text model API communication

• Abstracts provider-specific APIs through adapters
• Supports streaming responses
• Manages tool/function calling

ImageService: Handles image generation

• Supports text-to-image and image-to-image workflows
• Manages model-specific parameters
• Integrates with ImageStorageService for deduplication

ModelManager/ImageModelManager: Configuration management for models

• CRUD operations for model configurations
• API key storage
• Model capability tracking (tools, reasoning, vision)

TemplateManager: Manages optimization templates

• Built-in templates with i18n support
• Custom user templates
• Template processing with variable substitution

HistoryManager: Version control and iteration tracking

• Maintains PromptRecordChain structures
• Tracks optimization history with parent-child relationships
• Provides version switching capabilities

Sources: Core service files in packages/core/src/services/ and manager files in packages/core/src/managers/

---

UI Component Architecture

The @prompt-optimizer/ui package provides reusable Vue 3 components organized by feature domain:

Component File Structure and Relationships

Component Responsibilities

PromptOptimizerApp: Central coordination component

• Instantiates core services and managers
• Manages modal visibility state
• Routes optimization requests to appropriate workspaces
• Handles cross-cutting concerns (favorites, data import/export)

Workspace Components: Mode-specific layouts

• Split-pane layouts with resizable dividers
• Left panel: Input/configuration
• Right panel: Testing/results
• Session state persistence via mode-specific Pinia stores

InputPanelUI: Prompt input with features

• Variable detection and highlighting
• Template selection
• Model selection
• Variable extraction trigger

PromptPanelUI: Optimized output display

• Version switching (V0, V1, V2, etc.)
• Markdown rendering with code highlighting
• Reasoning display (collapsible)
• Iteration controls

ConversationManager: Multi-message editor (Pro Multi mode only)

• Add/edit/delete/reorder messages
• Role selection (system/user/assistant/tool)
• Variable detection in messages
• Export/import conversation JSON

Sources: packages/ui/src/components/app-layout/PromptOptimizerApp.vue1-70 workspace components in packages/ui/src/components/basic-mode/, context-mode/, and image-mode/

---

State Management with Pinia

The application uses Pinia stores for reactive state management with automatic mode-isolated persistence:

Pinia Store Architecture and Persistence

Session State Structure

Each session store maintains:

State Field	Type	Purpose
originalPrompt	string	User's input prompt
optimizedPrompt	string	Latest optimized result
optimizedReasoning	string	AI's reasoning explanation
chainId	string	Current iteration chain ID
versionId	string	Current version ID
selectedModelKey	string	Selected optimization model
selectedTemplateId	string	Selected template
testVariants	array	Multi-column test configurations
testVariantResults	map	Test results per variant
temporaryVariables	map	Session-scoped variables (Pro/Image modes)

Persistence Strategy

1. Automatic Save: Session stores watch for changes and save to PreferenceService with debouncing
2. Restore on Load: When workspace mounts, session state is restored from storage
3. Mode Isolation: Each mode uses a unique storage key, preventing cross-contamination
4. Image Optimization: Large binary data (images) is stored separately in ImageStorageService with content-based deduplication using SHA-256 hashes

Sources: packages/ui/src/stores/sessions/basicSystem.ts packages/ui/src/stores/sessions/proVariable.ts packages/ui/src/stores/sessions/imageText2Image.ts packages/core/src/services/PreferenceService.ts packages/core/src/services/ImageStorageService.ts packages/core/src/storage/dexie.ts packages/core/src/storage/file.ts

---

Technology Stack

Core Technologies

Layer	Technology	Purpose
Frontend Framework	Vue 3.5+	Reactive UI components
State Management	Pinia 3.0+	Centralized state stores
UI Library	Naive UI 2.42+	Component library
Routing	Vue Router 4	Client-side routing
Internationalization	vue-i18n 11.2+	Multi-language support (en-US, zh-CN, zh-TW)
Build Tool	Vite 7.2+	Fast development and production builds
Type System	TypeScript 5.8+	Static type checking

Desktop Platform

Component	Technology	Purpose
Runtime	Electron 39.2+	Native desktop wrapper
IPC	ipcMain/ipcRenderer	Main-renderer communication
Security	contextBridge	Secure API exposure to renderer
Updates	electron-updater 6.6.2	Auto-update mechanism
Packaging	electron-builder 26.0+	Multi-platform builds

Backend/API Layer

Component	Technology	Purpose
AI SDKs	OpenAI SDK, Google GenAI, Anthropic SDK	Provider-specific API clients
HTTP Client	Built into SDKs	API communication
Template Engine	Mustache 4.2	Variable substitution in templates
Schema Validation	Zod 3.25+	Runtime type validation
Storage	Dexie 4.0+ (IndexedDB wrapper)	Browser persistence

Development Tools

Tool	Technology	Purpose
Package Manager	pnpm 10.6+	Monorepo management
Test Framework	Vitest 4.0+	Unit and integration tests
E2E Testing	Playwright 1.56+	End-to-end browser tests
Code Quality	ESLint + TypeScript ESLint	Linting and type checking
Markdown Rendering	markdown-it 14.1+	Prompt output rendering
Code Highlighting	highlight.js 11.11+	Syntax highlighting in output

Sources: package.json74-95 packages/core/package.json34-45 packages/ui/package.json33-49 packages/desktop/package.json24-30

---

Key Design Patterns

1. Adapter Pattern for AI Providers

All AI providers implement a common interface through adapter classes:

• OpenAIAdapter: OpenAI API integration
• GeminiAdapter: Google Gemini API integration
• AnthropicAdapter: Anthropic Claude API integration
• DeepSeekAdapter: DeepSeek API integration

This enables provider-agnostic business logic in LLMService and easy addition of new providers.

2. Service Provider Pattern

Core services are instantiated once and passed down through the component tree via props or provide/inject, avoiding redundant initialization.

3. Repository Pattern

Managers (like ModelManager, TemplateManager) act as repositories, abstracting storage operations through the StorageProvider interface.

4. Template Method Pattern

Workspace components follow a template structure with common lifecycle hooks (mount, save, restore) but implement mode-specific behavior.

5. Observer Pattern (Reactive)

Pinia stores implement reactive observers—components automatically re-render when store state changes.

Sources: Adapter implementations in packages/core/src/adapters/, service files in packages/core/src/services/

---

Data Flow: Optimization Request

The following sequence diagram shows an optimization request flowing through the system with actual method names and classes:

Request Flow with Code References

1. User Action: Click "Optimize" button in ContextUserWorkspace.vue → calls handleOptimize()

2. State Retrieval: Workspace reads from useProVariableSession() store

   • store.originalPrompt
   • store.selectedModelKey
   • store.selectedTemplateId

3. Service Call: Invokes PromptService.optimize(OptimizationRequest)

   • Located in packages/core/src/services/PromptService.ts
   • Request includes: originalPrompt, modelKey, templateId, optimizationMode

4. Template Processing:

   • TemplateManager.getTemplate(templateId) retrieves template definition
   • TemplateProcessor.processTemplate(template, variables) substitutes {{originalPrompt}}, {{lastOptimizedPrompt}}, etc.
   • Returns Message[] array with roles and content

5. LLM Streaming:

   • LLMService.streamOptimization(request) orchestrates the API call
   • ModelManager.getModelConfig(modelKey) retrieves provider configuration
   • LLMService.getAdapter(provider) returns appropriate adapter (e.g., OpenAIAdapter)
   • adapter.streamChatCompletion({ messages, stream: true }) makes HTTP request

6. API Streaming: Provider API streams chunks via Server-Sent Events

   • Adapter yields chunks as async generator
   • Each chunk flows through: Adapter → LLMService → PromptService → Workspace
   • UI updates incrementally with each token

7. History Tracking:

   • HistoryManager.saveOptimization(record) saves result
   • Creates new PromptRecordChain or adds version to existing chain
   • Returns { chainId, versionId } for version tracking

8. State Update: Workspace updates Pinia store

   • store.optimizedPrompt = result.optimizedPrompt
   • store.chainId = result.chainId
   • Store's watch() triggers automatic save

9. Persistence: Store saves to storage via PreferenceService

   • Key: 'session/v1/pro/variable'
   • Value: Serialized store state as JSON
   • Persists to DexieStorageProvider (web) or FileStorageProvider (desktop)

Sources: packages/core/src/services/PromptService.ts packages/core/src/services/LLMService.ts packages/core/src/managers/TemplateManager.ts packages/core/src/services/llm/adapters/openaiadapter.ts packages/ui/src/components/context-mode/ContextUserWorkspace.vue packages/ui/src/stores/sessions/proVariable.ts

---

Configuration Management

Environment Variables

The system reads configuration from environment variables prefixed with VITE_:

Variable Pattern	Example	Purpose
VITE_OPENAI_API_KEY	sk-...	OpenAI API key
VITE_GEMINI_API_KEY	AI...	Google Gemini API key
VITE_DEEPSEEK_API_KEY	sk-...	DeepSeek API key
VITE_CUSTOM_API_KEY_<id>	VITE_CUSTOM_API_KEY_ollama	Custom model API key
VITE_CUSTOM_API_BASE_URL_<id>	http://localhost:11434/v1	Custom model base URL
VITE_CUSTOM_API_MODEL_<id>	qwen2.5:7b	Custom model name
ACCESS_PASSWORD	mypassword	Docker deployment password

Model Configuration

Models are configured in ModelManager with properties:

• modelKey: Unique identifier
• displayName: User-facing name
• provider: Provider type (openai, gemini, anthropic, etc.)
• apiUrl: API base URL
• apiKey: API key (optional if set via env var)
• defaultModel: Default model name for provider
• enabled: Whether model is active
• capabilities: Feature flags (tools, reasoning, vision)

Sources: README.md248-289 packages/core/src/managers/ModelManager.ts

---

Getting Started

To understand specific subsystems in depth, refer to the following wiki pages:

• Monorepo Structure and Packages: Detailed breakdown of package responsibilities, build system, and dependency management
• Multi-Platform Architecture: Platform-specific implementations for web, desktop, extension, and MCP server
• Application Modes and Workspaces: Deep dive into Basic, Pro, and Image modes with workspace component details
• Core Services Layer: Business logic architecture, services, managers, and adapters
• User Interface Layer: Vue component architecture, composables, and UI patterns
• Platform Implementations: Platform-specific code for each deployment target
• Deployment and Configuration: Deployment guides for Docker, Vercel, desktop distribution

For development setup and contribution guidelines, see Development Workflow and Build System.

Sources: README.md1-472 table of contents in prompt