README.md

Vectorizer Sync

A cross-platform desktop application built with Electron and SQLite for managing and synchronizing project directories with Vectorizer workspaces (local or remote).

✨ Key Features

• 🗂️ Project Directory Management: Select and manage multiple project directories with intuitive UI
• 📝 Workspace Configuration Export: Export workspace.yml files in Vectorizer format for local use
• ☁️ Cloud Synchronization: Automatic file synchronization to HiveHub Cloud (when enabled)
• 🔄 Real-Time File Monitoring: File system watcher detects changes and syncs automatically
• 🚫 Smart File Filtering: Automatic exclusion of modules, builds, and large files (>100KB)
• 📊 Quota Management: Respect HiveHub plan limits with real-time quota monitoring
• 🔔 Notification System: Receive alerts from HiveHub and internal notifications
• 💾 Local Data Storage: All data stored in SQLite in user's home directory (persistent across updates)
• 🔧 Configuration Import/Export: Import and export application configurations
• 🖥️ Cross-Platform: Native support for Windows, macOS, and Linux
• 🔒 Secure Storage: API tokens and credentials stored in OS keychain/credential store

🚀 Quick Start

Prerequisites

• Node.js: 20.x or later
• npm or pnpm: Package manager
• Windows: Windows 10 or later
• macOS: macOS 10.15 (Catalina) or later
• Linux: Ubuntu 20.04+, Fedora 33+, or equivalent

Development Setup

# Clone repository
git clone https://github.com/hivellm/vectorizer-sync.git
cd vectorizer-sync

# Install dependencies
npm install

# Run in development mode
npm run dev

Building from Source

# Build for current platform
npm run build

# Build for specific platform
npm run build:win
npm run build:mac
npm run build:linux

# Build for all platforms
npm run build:all

Production Installation

Windows:

• Download installer from releases
• Run .exe installer
• Application installed to C:\Users\<username>\AppData\Local\vectorizer-sync\

macOS:

• Download .dmg from releases
• Open DMG and drag to Applications
• Application installed to /Applications/vectorizer-sync.app

Linux:

• Download AppImage, DEB, or RPM from releases
• Install using package manager or run AppImage directly

📊 Performance

Metric	Value
File Change Detection	< 5 seconds
Database Queries	< 100ms (simple queries)
Application Startup	< 3 seconds
Memory Usage	< 500MB (normal operation)
Test Coverage	95%+ (target)

🔄 Feature Comparison

Feature	Vectorizer Sync	Manual Setup	Other Tools
Workspace Export	✅ Automatic	❌ Manual	⚠️ Partial
Cloud Sync	✅ Automatic	❌ Manual	⚠️ Limited
File Filtering	✅ Smart	❌ Manual	⚠️ Basic
Quota Monitoring	✅ Real-time	❌ Manual	❌ None
Cross-Platform	✅ Windows/macOS/Linux	✅ All	⚠️ Limited
Local Storage	✅ SQLite	❌ None	⚠️ Varies
Notifications	✅ Integrated	❌ None	⚠️ Basic
Configuration	✅ Import/Export	❌ Manual	⚠️ Limited

🎯 Use Cases

• Project Management: Manage multiple Vectorizer workspaces from a single interface
• Team Collaboration: Sync project files to HiveHub Cloud for team access
• Local Development: Export workspace.yml for local Vectorizer instances
• Automated Workflows: Automatic file synchronization on changes
• Documentation Sync: Keep documentation synchronized across environments

🔧 Workspace Configuration

Vectorizer Sync exports workspace.yml files in the Vectorizer format:

global_settings:
  file_watcher:
    enabled: true
    auto_discovery: true
    enable_auto_update: true
    exclude_patterns: []
    hot_reload: true
    watch_paths:
      - /workspace

projects:
  - name: my-project
    path: /workspace/my-project
    description: My Project
    collections:
      - name: source-code
        description: Source code
        include_patterns:
          - "src/**/*.ts"
          - "src/**/*.tsx"
        exclude_patterns:
          - "node_modules/**"
          - "dist/**"

See Workspace Format Documentation for complete specification.

📚 Documentation

• Architecture - System architecture, components, and design decisions
• DAG - Directed Acyclic Graph showing system dependencies and data flow
• Requirements - Functional and non-functional requirements
• Workspace Format - Vectorizer workspace.yml format specification
• Database Schema - SQLite database structure and schema
• File Filtering - File exclusion rules and filtering logic
• HiveHub API - HiveHub Cloud API documentation (future implementation)
• Development Guide - Development setup and workflow
• Status - Current project status and roadmap
• Documentation Index - Complete documentation index

🔄 HiveHub Cloud Integration

Authentication (Future)

Vectorizer Sync will support OAuth 2.0 authentication with HiveHub Cloud:

• Secure token storage in OS keychain
• Automatic token refresh
• Account management UI
• Session management

Sync Features

• Automatic Sync: Files sync automatically when changes are detected
• Quota Monitoring: Real-time quota usage and warnings
• Conflict Resolution: Handle sync conflicts intelligently
• Batch Operations: Efficient batch uploads for multiple files

See HiveHub API Documentation for API details.

🚫 File Filtering

Vectorizer Sync automatically excludes:

• Module Directories: node_modules/, vendor/, packages/, etc.
• Build Artifacts: dist/, build/, out/, .next/, etc.
• Large Files: Files larger than 100KB (configurable)
• Binary Files: .exe, .dll, .so, .dylib, etc.
• Temporary Files: *.tmp, *.temp, *.cache, etc.

See File Filtering Documentation for complete rules.

💾 Data Storage

All application data is stored locally in SQLite:

• Windows: C:\Users\<username>\vectorizer-sync\database.db
• macOS: ~/vectorizer-sync/database.db
• Linux: ~/vectorizer-sync/database.db

Stored Data:

• Project configurations
• Workspace settings
• File metadata
• Sync history
• User preferences
• Notifications

See Database Schema Documentation for schema details.

🧪 Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test suite
npm run test:unit
npm run test:integration
npm run test:e2e

Test Coverage Target: 95%+

🔧 Development

See Development Guide for detailed development instructions.

Project Structure

vectorizer-sync/
├── src/
│   ├── main/              # Electron main process
│   │   ├── index.ts        # Main entry point
│   │   ├── database/       # Database management
│   │   ├── sync/           # Sync engine
│   │   ├── watcher/        # File system watcher
│   │   └── api/            # HiveHub API client
│   ├── renderer/           # Electron renderer (React)
│   │   ├── components/     # React components
│   │   ├── pages/          # Page components
│   │   ├── hooks/          # React hooks
│   │   ├── store/          # State management
│   │   └── utils/          # Utility functions
│   └── shared/             # Shared code
│       ├── types/           # TypeScript types
│       └── constants/       # Constants
├── tests/                   # Test files
├── docs/                    # Documentation
├── scripts/                 # Build scripts
└── public/                  # Static assets

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Follow coding standards (see Development Guide)
2. Write tests for new features (95%+ coverage target)
3. Ensure all tests pass
4. Update documentation as needed
5. Submit pull request

📄 License

Apache License 2.0 - See LICENSE for details

🗺️ Roadmap

See Status Documentation for current status and roadmap.

Current Status: Documentation Phase (v0.1.0 Pre-release)

Planned Features:

• ✅ Documentation (Complete)
• ⏳ Core Infrastructure (Planned)
• ⏳ Project Management (Planned)
• ⏳ Workspace Export (Planned)
• ⏳ File Synchronization (Planned)
• ⏳ HiveHub Integration (Planned)
• ⏳ Notification System (Planned)

🆘 Support

For issues and questions:

• Open an issue on GitHub
• Check Documentation Index for guides
• Review Development Guide for setup help

🔗 Related Projects

• Vectorizer - High-performance vector database and search engine
• HiveHub Cloud - Cloud platform for Vectorizer workspaces