Overview

Relevant source files

• README.md
• README_EN.md
• docker-compose.dev.yml
• docker-compose.yml
• docker/generate-auth.sh
• images/other/sponsor_wx.jpg
• package.json
• packages/core/package.json
• packages/desktop/package.json
• packages/extension/public/manifest.json
• packages/ui/package.json
• pnpm-lock.yaml
• vercel.json

This document provides a high-level introduction to Prompt Optimizer, covering its purpose, architecture, deployment options, and key design decisions. For detailed information about specific subsystems, refer to the following pages:

• Project structure and package organization: Project Structure and Packages
• Detailed architecture patterns and service design: Architecture Overview
• Development setup and workflows: Development Workflow
• Core business logic services: Core Services
• User interface components and patterns: User Interface
• Platform-specific implementations: Platform Applications
• Deployment and configuration: Deployment and Operations
• Environment variables and API configuration: Configuration and Environment

---

What is Prompt Optimizer

Prompt Optimizer is a multi-platform AI prompt engineering tool that helps users write better prompts for large language models (LLMs). The application takes a user's initial prompt and optimizes it using various templates and AI models, supporting iterative refinement through version-tracked prompt chains.

The system operates as a pure client-side application with no backend server—all data flows directly between the user's browser/desktop and AI service providers (OpenAI, Gemini, DeepSeek, etc.). This architecture ensures data privacy while eliminating the need for infrastructure maintenance.

Current Version: 2.1.0 (as of package.json3)

Primary Use Cases:

• Optimizing prompts for better AI responses
• Role-playing character development with structured prompts
• Knowledge extraction with format consistency
• Creative writing with precise requirement specification
• Function calling and tool integration testing

Sources: README.md1-50 README_EN.md1-50 package.json1-10

---

Core Capabilities

Capability	Description	Key Components
Prompt Optimization	Transform basic prompts into structured, effective prompts using AI	PromptService, TemplateManager, LLMService
Multi-Model Support	Connect to OpenAI, Gemini, DeepSeek, Zhipu, SiliconFlow, custom APIs	TextAdapterRegistry, provider adapters
Image Generation	Text-to-image (T2I) and image-to-image (I2I) capabilities	ImageService, ImageModelManager, ImageAdapterRegistry
History Tracking	Version-controlled prompt chains for iterative refinement	HistoryManager, PromptRecordChain
Advanced Testing	Context variables, multi-turn conversations, function calling	ContextRepo, advanced mode UI
Favorites Management	Save and categorize prompts with tags and hierarchical categories	FavoriteManager
Data Portability	Import/export all configurations and data	DataManager
Internationalization	Multi-language UI support (English, Simplified Chinese, Traditional Chinese)	Vue I18n system

Sources: README.md43-72 README_EN.md43-71

---

System Architecture at a Glance

Monorepo Structure: Five deployment targets share common @prompt-optimizer/core and @prompt-optimizer/ui packages

Three-Layer Architecture Pattern:

Key Architectural Principles:

1. Service Injection Pattern: Core services implement interfaces (e.g., ILLMService, IModelManager) and are injected into UI composables, enabling platform-specific implementations (direct import in web, IPC proxies in Electron)

2. Adapter Pattern: AI provider integration uses adapters (OpenAIAdapter, GeminiAdapter) registered in TextAdapterRegistry, allowing runtime provider selection without tight coupling

3. Storage Abstraction: Storage operations use IStorageProvider interface with implementations for browser (BrowserStorageProvider using IndexedDB) and file system (FileStorageProvider for Electron)

4. Pure Client-Side: No backend server—all AI API calls originate from the client, with API keys stored locally

Sources: package.json1-96 README.md23-55 high-level architecture diagrams

---

Deployment Targets

Prompt Optimizer deploys to five distinct environments, each optimized for different use cases:

Target	Entry Point	Build Command	Use Case
Web Application	packages/web/src/main.ts	pnpm build:web	Online access, easiest to try
Browser Extension	packages/extension/src/background.ts	pnpm build:ext	Persistent sidebar in browser
Desktop Application	packages/desktop/main.js	pnpm build:desktop	No CORS limitations, auto-updates
Docker Container	Dockerfile docker-compose.yml	Docker build	Self-hosted with authentication
MCP Server	packages/mcp-server/src/index.ts	pnpm mcp:build	Claude Desktop integration

Deployment Architecture:

Platform-Specific Features:

• Web/Extension: Use BrowserStorageProvider with IndexedDB, subject to CORS limitations
• Desktop: Use FileStorageProvider with file system access, no CORS restrictions, implements IPC bridge via packages/desktop/preload.js
• Docker: Runs Nginx reverse proxy routing /mcp to MCP server on port 3000, configurable via docker/nginx.conf
• MCP: Exposes three tools: optimize-user-prompt, optimize-system-prompt, iterate-prompt via Model Context Protocol

Sources: package.json11-43 README.md73-246 vercel.json1-32 docker-compose.yml1-44 packages/desktop/package.json1-98 packages/extension/public/manifest.json1-34

---

Technology Stack

Frontend Stack

Technology	Purpose	Key Files
Vue 3 (3.5.13+)	UI framework with Composition API	All .vue files
Naive UI (2.42.0+)	Component library (forms, tables, modals)	packages/ui/src/components/
Vite (6.0+)	Build tool and dev server	vite.config.ts files
TypeScript (5.8.2+)	Type safety	All .ts files
Vue I18n (10.0.6+)	Internationalization	packages/ui/src/locales/
Markdown-it (14.1.0)	Markdown rendering	packages/ui/src/components/OutputDisplay.vue
Highlight.js (11.11.1)	Code syntax highlighting	Used with Markdown renderer

Backend/Core Stack

Technology	Purpose	Key Files
OpenAI SDK (4.83.0+)	OpenAI API client	packages/core/src/llm/adapters/openai.ts
Google GenAI (1.0.0+)	Gemini API client	packages/core/src/llm/adapters/gemini.ts
Anthropic SDK (0.65.0+)	Claude API client (MCP only)	packages/mcp-server/
Dexie (4.0.11)	IndexedDB wrapper	packages/core/src/storage/
Mustache (4.2.0)	Template engine	packages/core/src/template/processor.ts
Zod (3.22.4+)	Schema validation	Throughout core services
UUID (11.0.5)	Unique ID generation	Record chain IDs, model keys

Platform-Specific Stack

Platform	Technology	Purpose
Electron	electron (37.1.0), electron-builder (24.0.0)	Desktop application packaging
Electron	electron-updater (6.3.9)	Auto-update mechanism
Electron	undici (6.19.8)	HTTP client with proxy support
Docker	Nginx (alpine)	Reverse proxy and static file serving
Docker	Node.js (20-alpine)	MCP server runtime
MCP	@modelcontextprotocol/sdk (1.16.0)	MCP protocol implementation

Sources: package.json63-84 packages/core/package.json32-42 packages/ui/package.json31-39 packages/desktop/package.json23-29

---

Project Structure

The project follows a pnpm monorepo structure with workspace packages:

Package Dependency Rules:

1. @prompt-optimizer/core has zero dependencies on other workspace packages (foundational layer)
2. @prompt-optimizer/ui depends only on core (presentation layer)
3. Application packages (web, extension, desktop, mcp-server) depend on core and optionally ui
4. Build order: core → ui → applications (enforced by package.json12-19)

Key Directories:

Path	Purpose	Key Files
packages/core/src/	Core business logic	llm/, model/, template/, history/, favorite/
packages/ui/src/	UI components	components/, composables/, locales/
packages/web/src/	Web application	main.ts, App.vue
packages/extension/	Extension files	manifest.json, background.ts
packages/desktop/	Electron files	main.js, preload.js
packages/mcp-server/src/	MCP implementation	index.ts, tools/
docker/	Docker configuration	Dockerfile, nginx.conf, generate-auth.sh

Sources: package.json1-96 directory structure from file listings

---

Key Design Decisions

1. Pure Client-Side Architecture

Decision: All AI API calls originate from the client with no intermediary backend server.

Rationale:

• Eliminates infrastructure costs and maintenance
• Ensures data privacy (no data passes through third-party servers)
• Simplifies deployment (static site hosting)

Tradeoffs:

• Subject to browser CORS limitations (mitigated by desktop app)
• API keys stored client-side (acceptable for personal use)
• Cannot implement server-side API key rotation

Implementation: Direct provider SDK usage in packages/core/src/llm/adapters/

2. Service Injection via Interfaces

Decision: Core services implement TypeScript interfaces, injected into UI layer via composables.

Rationale:

• Enables platform-specific implementations (e.g., Electron IPC proxies)
• Facilitates testing with mock implementations
• Decouples UI from storage/network implementation details

Implementation:

• Interfaces: packages/core/src/llm/types.ts packages/core/src/model/types.ts
• Injection: packages/ui/src/composables/usePromptOptimizer.ts
• Electron proxies: packages/desktop/src/services/

3. Adapter Pattern for AI Providers

Decision: Each AI provider has an adapter implementing a common interface, registered in a central registry.

Rationale:

• Allows adding providers without modifying core logic
• Enables runtime provider selection based on model configuration
• Encapsulates provider-specific API differences

Implementation:

• Registry: packages/core/src/llm/registry.ts
• Base interface: packages/core/src/llm/types.ts (TextAdapter)
• Adapters: packages/core/src/llm/adapters/openai.ts packages/core/src/llm/adapters/gemini.ts etc.

4. Self-Contained Model Configurations

Decision: Each TextModelConfig embeds full provider and model metadata, not just IDs.

Rationale:

• Enables offline capability (no need to fetch model lists)
• Preserves historical accuracy (config remembers model's capabilities even if provider changes)
• Supports portability (configs can be exported/imported without external dependencies)

Tradeoffs:

• Larger storage footprint
• Potential metadata staleness (requires manual updates)

Implementation: packages/core/src/model/types.ts (TextModelConfig structure)

5. Streaming-First API Design

Decision: All LLM interactions use streaming APIs with callback-based token delivery.

Rationale:

• Provides real-time feedback to users (perceived performance)
• Supports reasoning models (separate reasoning token stream)
• Aligns with modern LLM provider SDKs

Implementation:

• Streaming interface: packages/core/src/llm/types.ts (sendMessageStream method)
• Callback handling: packages/core/src/prompt/service.ts (optimizePromptStream)
• UI integration: packages/ui/src/composables/usePromptOptimizer.ts

6. Monorepo with Shared Packages

Decision: Single repository with pnpm workspaces, sharing core and ui packages across platforms.

Rationale:

• Maximizes code reuse (estimated 80%+ shared code)
• Ensures consistency across platforms
• Simplifies dependency management
• Enables atomic cross-package changes

Tradeoffs:

• More complex build orchestration
• Requires careful dependency management
• Larger repository size

Implementation:

• Workspace definition: Root package.json1-96
• Build orchestration: package.json12-26 (build scripts)
• Dependency links: workspace:* protocol in package.json files

Sources: README.md1-435 README_EN.md1-437 architecture analysis from diagrams, packages/core/src/ packages/ui/src/

---

Getting Started

To begin exploring the codebase:

1. Understand the architecture: Read Architecture Overview for service dependencies and design patterns
2. Explore core services: Start with Core Services to understand business logic
3. Learn the UI layer: Review User Interface for component structure
4. Choose a platform: See Platform Applications for platform-specific implementations
5. Set up development: Follow Development Workflow for local setup

For immediate hands-on experience, visit the live demo at https://prompt.always200.com or install the desktop application from GitHub Releases.

Sources: README.md73-310 README_EN.md73-313