ClipFlow Clipboard Manager - Technical Specification

Document Information

Field	Value
Document Version	1.0.0
Created Date	2025-08-25
Status	Current Implementation
Language	Odin
Platform	Windows 10/11

1. Project Overview

Purpose Statement

ClipFlow is a high-performance, dual-interface clipboard history manager for Windows, providing real-time clipboard monitoring with both modern GUI and CLI interfaces.

Core Value Proposition

Zero Installation: Single executable, no dependencies
Dual Interface: Raylib GUI + Interactive CLI
Real-time Monitoring: Background clipboard tracking
Smart Management: Deduplication, source tracking, persistence
Performance Optimized: Sub-50ms command execution

Target Users

Developers: Code snippet management, API key handling
Power Users: Text workflow automation, content organization
System Administrators: Configuration management, reliability
Content Creators: Visual snippet library, metadata tracking

2. System Architecture

High-Level Architecture

graph TB
    subgraph "User Interfaces"
        A[GUI - Raylib Cards]
        B[CLI - Interactive Mode]
        C[Direct Commands]
    end
    
    subgraph "Core Services"
        D[Background Monitor Thread]
        E[Command Processor]
        F[Storage Manager]
        G[Windows API Integration]
    end
    
    subgraph "Data Layer"
        H[JSON Persistence]
        I[Memory Cache]
        J[Configuration]
    end
    
    A --> D
    B --> E
    C --> E
    D --> G
    E --> F
    F --> H
    G --> Windows_Clipboard
    I --> F
    J --> E

Thread Architecture

Main Thread: GUI rendering, user interactions
Background Thread: Clipboard monitoring (500ms polling)
Synchronization: Atomic stop signals, mutex-protected storage
Communication: Event-driven UI updates

3. Technical Requirements

Development Environment

Component	Requirement
Language	Odin (latest stable)
GUI Framework	Raylib 5.0+
Build System	Odin Compiler + MSVC
Target Platform	Windows 10/11 x64
Windows SDK	10.0.19041+

Build Configuration

# Development Build
odin build src -out:clipflow.exe -o:none -debug

# Release Build (GUI)
odin build src -out:clipflow_raylib.exe -o:speed -no-bounds-check

# Release Build (CLI)
odin build src -out:clipflow.exe -o:speed -no-bounds-check

Runtime Requirements

Resource	Minimum	Recommended
RAM	50MB	100MB
Storage	10MB	50MB
CPU	Any x64	Multi-core

4. Data Models

Core Data Structures

ClipboardEntry :: struct {
    id:        i64,      // Unix timestamp (unique identifier)
    content:   string,   // UTF-8 clipboard text content
    timestamp: string,   // ISO 8601 formatted timestamp
    app_name:  string,   // Source application window title
    hash:      u64,      // DJB2 hash for deduplication
    tags:      []string, // Extensible metadata (future use)
}

ClipboardHistory :: struct {
    version: string,           // History format version ("1.0")
    entries: []ClipboardEntry, // Chronological entry list
}

Config :: struct {
    max_entries:     int,    // Maximum history entries (1000)
    history_file:    string, // Storage path
    monitor_interval: f64,   // Check interval seconds (0.5)
    search_limit:    int,    // Max search results (50)
    enable_deduplication: bool, // Content deduplication (true)
}

JSON Storage Format

{
  "version": "1.0",
  "entries": [
    {
      "id": 1641234567890,
      "content": "Hello world",
      "timestamp": "2025-01-15T10:30:00Z",
      "app_name": "Microsoft Edge",
      "hash": 12345678901234567890,
      "tags": []
    }
  ]
}

5. Component Specifications

Main Entry Point (`src/main.odin`)

Responsibility: Mode routing and application bootstrap

main :: proc() {
    args := os.args
    
    // No args or double-click → GUI mode
    if len(args) <= 1 {
        core.run_clipboard_gui_app()
        return
    }
    
    // Parse and execute CLI commands
    command_args := cli.parse_args(args)
    
    if command_args.command == .INTERACTIVE {
        core.run_clipboard_gui_app()  // Interactive GUI
        return
    }
    
    // Direct CLI execution
    success := cli.execute_command(command_args, config)
}

Clipboard System (`src/clipboard/`)

Responsibility: Windows API integration, change detection

Key APIs

// Core clipboard operations
get_clipboard_text :: proc() -> (string, bool)
set_clipboard_text :: proc(text: string) -> bool
get_clipboard_sequence_number :: proc() -> u32
get_active_window_name :: proc() -> string

// Unicode conversion
utf16_to_utf8 :: proc(utf16_ptr: rawptr, utf16_len: c.int) -> (string, bool)
utf8_to_utf16_global :: proc(text: string) -> (rawptr, bool)

Background Monitoring

clipboard_monitor_worker :: proc(config: ^Config, stop_flag: ^bool) {
    last_sequence := get_clipboard_sequence_number()
    
    for !stop_flag^ {
        current_sequence := get_clipboard_sequence_number()
        
        if current_sequence != last_sequence {
            capture_clipboard_change()
            last_sequence = current_sequence
        }
        
        time.sleep(500 * time.Millisecond)
    }
}

GUI Module (`src/gui/`)

Responsibility: Raylib visual interface, card-based layout

Architecture

gui/
├── core/raylib_main.odin       # Main GUI loop
├── components/ui_components.odin # Reusable UI elements
├── entries/card_renderer.odin   # Entry card visualization
├── overlays/command_content.odin # Command palette
└── state/ui_state.odin         # Global UI state

Key Features

Card Layout: Dynamic grid with drag-drop reordering
Command Palette: Ctrl+K global shortcut access
Entry Details: Full content overlays with copy shortcuts
Visual Feedback: Animations, color-coded messages
Real-time Updates: Background monitoring integration

Storage System (`src/storage/history.odin`)

Responsibility: JSON persistence, history management

// Primary operations
load_history :: proc(config: Config) -> (ClipboardHistory, bool)
save_history :: proc(history: ClipboardHistory, config: Config) -> bool
add_entry :: proc(history: ^ClipboardHistory, entry: ClipboardEntry) -> bool

// Search and retrieval
find_entry_by_id :: proc(history: ClipboardHistory, id: i64) -> (ClipboardEntry, bool)
find_entries_containing :: proc(history: ClipboardHistory, query: string) -> []ClipboardEntry

// Deduplication
entry_exists :: proc(history: ClipboardHistory, hash: u64) -> bool
calculate_content_hash :: proc(content: string) -> u64

Command System (`src/commands/`)

Responsibility: Enhanced command processing with feedback

CommandType :: enum {
    LIST, CAPTURE, GET, SEARCH, DELETE, CLEAR,
    INTERACTIVE, STATUS, SETTINGS, HELP, QUIT,
}

CommandResult :: struct {
    success:    bool,
    message:    string,
    data:       rawptr,
    error_code: int,
}

execute_command :: proc(args: CommandArgs, config: Config) -> CommandResult

6. User Interface Specifications

GUI Design System

Visual Design

Theme: Dark Modern (customizable)
Layout: Card-based masonry grid
Typography: System font with monospace fallback
Colors: High contrast with blue accents

Interaction Patterns

Action	Method	Result
Open Command Palette	`Ctrl+K`	Command overlay appears
Copy Entry	`Ctrl+Alt+C`	Entry copied to clipboard
View Details	Double-click card	Full content overlay
Reorder Entries	Drag & drop	Visual reorganization
Search History	Type in command palette	Filtered results

CLI Interface

Interactive Mode

clipflow interactive

ClipFlow Interactive Mode
========================
Starting background daemon thread...
Background daemon started successfully

clipflow> list --compact
clipflow> search "important text"
clipflow> get 1
clipflow> quit

Direct Commands

clipflow capture          # Save current clipboard
clipflow list            # Show recent entries
clipflow get 5           # Restore entry #5
clipflow search "query"   # Search history
clipflow delete 3        # Remove entry
clipflow clear           # Clear all history

7. Performance Requirements

Execution Targets

Operation	Target	Maximum
Command Execution	< 25ms	50ms
Clipboard Capture	< 5ms	10ms
GUI Rendering	60 FPS	30 FPS
Search Operations	< 50ms	100ms
Application Startup	< 200ms	500ms

Resource Limits

Resource	Target	Maximum
Memory Usage	< 25MB	50MB
CPU (Idle)	< 1%	2%
CPU (Active)	< 10%	20%
Storage Growth	Linear	1MB/1000 entries

8. Security Specifications

Data Protection

// Content sanitization
sanitize_content :: proc(content: string) -> string {
    // Remove null characters, validate UTF-8, truncate length
}

// Sensitive content detection
is_sensitive_content :: proc(content: string) -> bool {
    patterns := []string{"password", "api_key", "secret", "token"}
    // Check content against sensitive patterns
}

File System Security

Restricted Permissions: Owner-only access to history files
Atomic Writes: Prevent corruption during saves
Path Validation: Prevent directory traversal attacks

9. Testing Strategy

Test Organization

src/
├── commands/command_processor_test.odin
├── clipboard/system_test.odin
├── storage/history_test.odin
└── utils/hash_test.odin

Test Categories

Type	Coverage	Framework
Unit Tests	Individual functions	Odin testing
Integration Tests	Module interactions	Custom framework
Performance Tests	Response times	Benchmark suite
GUI Tests	User interface	Manual + automated

Example Test

test_clipboard_capture :: proc(t: ^testing.T) {
    test_content := "Hello, World!"
    expected_hash := hash.djb2(transmute([]u8)test_content)
    
    entry := create_clipboard_entry(test_content, "test_app")
    
    testing.expect_value(t, entry.content, test_content)
    testing.expect_value(t, entry.hash, expected_hash)
    testing.expect_value(t, entry.app_name, "test_app")
    testing.expect(t, entry.id > 0, "Entry should have valid ID")
}

10. Configuration Management

Storage Locations

History File: %APPDATA%\ClipFlow\history.json
Daemon Logs: C:\temp\clipflow_daemon.log
Process State: C:\temp\clipflow_daemon_state.txt

Default Configuration

{
  "max_entries": 1000,
  "history_file": "%APPDATA%\\ClipFlow\\history.json",
  "monitor_interval": 0.5,
  "search_limit": 50,
  "enable_deduplication": true,
  "log_level": "INFO"
}

11. Deployment Specifications

Build Outputs

GUI Version: clipflow_raylib.exe (1.4MB)
CLI Version: clipflow.exe (smaller footprint)
Dependencies: None (static linking)

Installation

Download executable
Run directly (no installation required)
First run creates necessary directories
Optional: Add to Windows startup folder

Windows Integration

# Add to startup (optional)
copy clipflow_raylib.exe "%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\"

# Add to PATH (optional)
setx PATH "%PATH%;C:\ClipFlow" /M

12. Implementation Status ✅

Completed Features

Core Foundation: Clipboard capture, JSON storage, CLI commands
Interactive Mode: Background monitoring with thread-based architecture
Command System: 50+ commands with autocomplete and feedback
GUI Interface: Raylib cards with command palette and overlays
Advanced Features: Search, drag-drop, visual themes

Architecture Highlights

Modular Design: Clear separation of concerns across 50+ source files
Thread Safety: Proper synchronization between GUI and background monitoring
Performance: Optimized for sub-50ms response times
Extensibility: Command system supports easy feature additions
Cross-Interface: Shared core with dual UI approaches

Quality Metrics

Test Coverage: Unit tests for core functionality
Performance: Meets all target benchmarks
Memory Safety: Manual memory management with proper cleanup
Error Handling: Comprehensive error reporting and recovery
Documentation: Extensive code comments and user documentation

This specification serves as the authoritative technical reference for ClipFlow's current implementation and provides guidance for future development and maintenance.

FilesExpand file tree

TECHNICAL_SPECIFICATION.md

Latest commit

History