English | Traditional Chinese

Lynavo Drive

A high-performance, local-LAN incremental media sync tool from mobile (iOS / Android) to desktop (macOS / Windows).

Product Preview • Key Features • OSS Boundaries • Developer Quick Start • Contributing • Community & Social

---

Project Status

Lynavo Drive is implemented and open for community source builds and contributions. This repository provides one public local source-build and package-verification path; it does not publish official signed installers, mobile store builds, auto-updates, or hosted services.

Surface	Current OSS scope
💻 Desktop	macOS and Windows application runtime
📱 Mobile	iOS and Android application runtime
🐧 Linux	Local source-build and package verification only
🌐 Network	Foreground sync over the same LAN
📦 Distribution	Community source builds and locally produced packages/binaries

📸 Product Preview

✨ Key Features

• Automatic incremental media sync: Scans the mobile photo library and queues unsynced photos and videos without manual file selection.
• Local discovery and pairing: Finds desktops through mDNS on the same LAN, then pairs with a QR code or six-digit pairing code.
• Resumable serial transfers: Uploads one file per phone at a time and continues unfinished queue items after foreground LAN reconnection.
• Read-only queue and history: Shows transfer progress, completed files, and completion-day statistics without delete, skip, or reorder controls.
• Shared-file access: Lets mobile users browse and download files exposed by the desktop's local shared directories. This is separate from automatic media upload.
• Local diagnostics: Exports desktop and mobile diagnostics without relying on a hosted diagnostics service.

🛡️ OSS Boundaries

Important

Local-LAN Open-Source Core

• Foreground automatic sync works without sign-in or an account service.
• The upload set comes only from the mobile photo-library scan and local pending queue; there is no manual file-selection fallback.
• The queue is read-only, and each phone uploads one file at a time.
• Missing non-OSS modules or account-service state do not block foreground LAN pairing and sync.

Warning

Not Included In This Repository

• Remote access, cloud relay, tunnel credentials, official accounts, and silent background continuation are unavailable and remain disabled.
• Official signing, notarization, mobile store distribution, package upload, and auto-update infrastructure are not provided.
• The source package does not redistribute Apple Bonjour for Windows. It uses a locally installed/configured Bonjour runtime when available, otherwise the zeroconf-compatible fallback.
• Linux remains a local build and package-verification target, not a supported desktop user surface.

🚀 Developer Quick Start

This is a contributor workflow, not an end-user installer. See the release playbook for local package builds and platform-specific verification.

💻 Setup & Start Commands

# 1. Enable the repository's pinned pnpm version and install dependencies
corepack enable
pnpm install --frozen-lockfile

# 2. Build shared packages
pnpm --filter @lynavo-drive/contracts build
pnpm --filter @lynavo-drive/design-tokens build

# 3. Start desktop development mode
pnpm dev:desktop

The Electron window opens automatically, and the desktop app starts the sidecar.

To run a mobile client, keep the desktop running and use another terminal:

📱 Mobile Development Commands

# Start Metro
pnpm dev:mobile

# Then launch one platform from another terminal
pnpm --filter @lynavo-drive/mobile ios
# or
pnpm dev:mobile:android

Platform prerequisites still apply: iOS requires macOS, Xcode, and CocoaPods; Android requires Android Studio plus the Android SDK/NDK.

Pair the applications:

1. Keep the phone and desktop on the same LAN.
2. Open Lynavo Drive on the desktop and set or view the six-digit pairing code.
3. On mobile, discover the desktop and scan its QR code or enter the pairing code.
4. Keep the mobile app in the foreground for OSS automatic LAN sync.

❓ FAQs & Troubleshooting

🔍 View Troubleshooting Guide & Common FAQs

📡 1. The mobile app cannot find my desktop client (mDNS discovery failure)

• Check Network: Ensure both mobile and desktop are on the same local LAN.
• Windows Firewall: Verify that Windows Defender Firewall allows incoming traffic for ports 39593 (TCP/LMUP file transport) and 39594 (HTTP API).
• Bonjour Runtime: The OSS build doesn't redistribute Apple Bonjour. Ensure Bonjour is installed on Windows, or rely on the zeroconf-compatible fallback.

☁️ 2. Why are some of my iCloud photos stuck/not transferring?

• Photos marked with iCloud must be exported from the Apple Photos cloud repository before transfer.
• While in cloud_downloading or preparing states, the phone is downloading the high-res original asset to local storage. Transfer begins automatically once complete.

📸 3. Can I manually select which photos/videos to sync?

• No. Automatic upload is driven by the mobile photo-library scan and strictly read-only pending queue. Checkbox picking is not part of the OSS workflow.

💤 4. What happens when the desktop sleeps or connection drops?

• LAN transfers will interrupt. With the mobile app in the foreground, the unfinished queue continues after the desktop wakes and LAN connectivity is restored.
• The OSS runtime does not provide silent background continuation.
• Enable "Prevent computer from sleeping while syncing" in the desktop app settings for uninterrupted transfers.

🏗️ Architecture Overview

flowchart TD
    subgraph Mobile["📱 Mobile Client (iOS / Android)"]
        RN["React Native UI"]
        subgraph SE["Native Sync Engine"]
            iOS["iOS (Swift)"]
            Android["Android (Kotlin)"]
        end
    end

    subgraph Desktop["💻 Desktop App (macOS / Windows)"]
        Electron["Electron Shell (React 18 UI)"]
        Preload["Preload Bridge"]
        subgraph Sidecar["Go Sidecar"]
            HTTP["HTTP API & WebSockets (Port 39594)"]
            LMUP["LMUP Receiver (Port 39593)"]
            DB[("SQLite DB")]
            FS["Filesystem Shared Dirs"]
        end
    end

    %% Communication Links
    RN <--> Preload
    Preload <--> Electron
    Electron <--> HTTP

    %% Network Sync Channels
    SE -- "mDNS Discovery / Pairing" --> HTTP
    SE -- "Presence & Metadata (HTTP/WS)" --> HTTP
    SE -- "Incremental Media Sync (LMUP/TCP)" --> LMUP

    classDef mobile fill:#fff0f5,stroke:#db7093,stroke-width:1px;
    classDef desktop fill:#f0f8ff,stroke:#4682b4,stroke-width:1px;
    classDef sidecar fill:#f5fffa,stroke:#2e8b57,stroke-width:1px;
    class Mobile,RN,SE,iOS,Android mobile;
    class Desktop,Electron,Preload desktop;
    class Sidecar,HTTP,LMUP,DB,FS sidecar;

Loading

🔧 Technical Infrastructure

🛠️ Tech Stack

Layer	Technology
📦 Monorepo	pnpm 10 + turborepo 2.8
💻 Desktop	Electron 41 + electron-vite 5 + electron-builder 26
🎨 Desktop UI	React 18.3 + zustand 5 + Tailwind CSS v4
📱 Mobile	React Native 0.84.1 + React 19 (iOS / Android)
🍎 iOS Native	Swift SyncEngine + BGTask + PhotoKit + Network.framework
🤖 Android Native	Kotlin bridge + NativeSyncEngine / MediaStore / NsdManager
⚡ Sidecar	Go 1.25.6 + SQLite + WebSocket
🔗 Shared	@lynavo-drive/contracts + @lynavo-drive/design-tokens
🧪 Test	vitest 4.1 + jest + go test

⚙️ Prerequisites

• macOS or Windows (desktop currently supports macOS / Windows; Linux is only for local build / package verification; iOS builds still require macOS + Xcode)
• Node.js >= 22.12.0
• pnpm >= 10
• Go >= 1.25.6 (sidecar development and tests)

📱 View Mobile & Platform-Specific SDK Requirements

• Xcode + CocoaPods (iOS builds and device debugging, macOS only)
• Android Studio + Android SDK / NDK (Android builds and debugging)

💻 Common Commands

🛠️ View Developer Command Reference

# Desktop
pnpm dev:desktop
pnpm build:desktop
pnpm package:desktop          # macOS local DMG
pnpm package:desktop:win      # Windows NSIS + zip (default desktop Windows package, no release profile)

# Mobile
pnpm dev:mobile
pnpm build:mobile
pnpm dev:mobile:android
pnpm build:mobile:android  # Android Debug build (assembleDebug)

# Sidecar
pnpm dev:sidecar
pnpm build:sidecar
pnpm test:sidecar

# Full repository validation
pnpm build
pnpm test
pnpm typecheck
pnpm format:check
pnpm check

📦 OSS Build & Package Verification

This OSS repository keeps contributor-local source-build paths and GitHub-hosted, secret-free unsigned build/package verification. Hosted outputs are verification artifacts, not official signed distributions. Linux remains local verification only and is not a supported desktop user surface.

🔬 View Verification & Build Pipelines

# Inspect the local build / package commands that would run
pnpm release --profile review --targets ios,android,mac,win,linux --dry-run

# Local iOS / Android Debug / Desktop build verification
pnpm build:mobile
pnpm build:mobile:ios:release
pnpm build:mobile:android
pnpm package:desktop

# Android Release source-build verification
pnpm release --profile review --targets android --dry-run
pnpm release --profile review --targets android

# Local desktop platform package
pnpm package:desktop

# Linux package verification (Linux host, one arch per run)
pnpm --filter @lynavo-drive/desktop package:linux -- --arch=x64
pnpm --filter @lynavo-drive/desktop package:linux -- --arch=arm64

release profiles only inject LYNAVO_RELEASE_CHANNEL and local build configuration, and only select local build/package commands.

GitHub-hosted workflows may invoke these commands using public source and no repository secrets. Third-party or external build services, code signing, notarization, store upload, auto-update, and private distribution infrastructure remain outside this OSS baseline.

The OSS Draft Release workflow accepts stable tags matching vX.Y.Z, rebuilds the complete verification set from that tagged commit, and creates or updates a draft GitHub Release. Manual dispatch is build-only. Release files are unsigned OSS build-verification outputs and include SHA-256 checksums; see the release playbook for the exact asset list, warnings, and maintainer procedure.

📁 Project Structure

📂 View Directory Structure Map

lynavo-drive/
├── apps/
│   ├── desktop/              # Electron desktop app
│   │   └── src/
│   │       ├── main/         # Main process (window, IPC, sidecar lifecycle)
│   │       ├── preload/      # Preload bridge
│   │       └── renderer/     # React 18 UI
│   └── mobile/               # React Native iOS/Android app + native sync
│       ├── ios/              # Xcode project and Swift native modules
│       ├── android/          # Android project, Kotlin bridge, native sync
│       ├── src/              # RN screens and hooks
│       └── __tests__/        # RN tests
├── packages/
│   ├── contracts/            # Shared DTOs / constants / events / error codes
│   └── design-tokens/        # Shared design tokens
├── services/
│   └── sidecar-go/           # Go sidecar (TCP/HTTP/SQLite/mDNS)
└── docs/
    ├── architecture/         # Architecture, state machine, data model
    ├── operations/           # Troubleshooting, diagnostics, sidecar runbook
    ├── product/              # Product constraints, OSS boundaries, non-goals
    ├── release/              # OSS build and package verification playbook
    └── testing/              # OSS verification matrix

🎯 Development Baseline

• Shared types, constants, event names, and port definitions come from @lynavo-drive/contracts.
• The renderer does not access the sidecar, filesystem, or SQLite directly; all access goes through the preload bridge / main process.
• The queue stays read-only. The UI cannot delete, reorder, or skip items.
• A given phone uploads only one file at a time.
• Guest/local foreground LAN sync is fail-open; remote access and background continuation fail closed.

📄 Documentation Reference

• ⚙️ Development constraints and operating rules: AGENTS.md
• 📘 System overview: docs/architecture/system-overview.md
• 🔄 Sync state machine: docs/architecture/sync-state-machine.md
• 📊 Data model and statistics semantics: docs/architecture/data-model.md
• 🔧 Troubleshooting guide: docs/operations/troubleshooting.md
• 📱 Mobile diagnostics package: docs/operations/mobile-diagnostics.md
• ⚡ Sidecar runbook: docs/operations/sidecar-runbook.md
• 🛡️ Product constraints, OSS boundaries, and non-goals: docs/product/constraints.md
• 📦 OSS build verification playbook: docs/release/release-playbook.md
• 🔬 OSS verification matrix: docs/testing/oss-verification-matrix.md
• 🔒 Security policy: SECURITY.md
• 🕵️ Privacy notice: PRIVACY.md
• 🤝 Contributing guide: CONTRIBUTING.md
• 📜 Code of conduct: CODE_OF_CONDUCT.md
• 📄 Third-party notices: THIRD_PARTY_NOTICES.md

💡 Contributing

Community contributions are welcome. To get started:

1. Fork the Repository: Create a personal fork and clone it locally.
2. Set Up the Workspace: Follow the Developer Quick Start and install the toolchain required by the platform you plan to change.
3. Verify Your Change: Run focused tests first, then the applicable repository checks before submitting a pull request:

⚙️ Verification Commands

pnpm test
pnpm typecheck
pnpm format:check
pnpm gate:release

For detailed coding standards, project layouts, and process rules, check out our Contributing Guidelines and Code of Conduct.

• Browse existing issues
• Report a bug
• Request a feature
• Report a vulnerability privately instead of posting exploitable details in a public issue.

🌐 Community & Social

Follow project news and updates across these channels:

• — @founder_im63606
• — @ViviDrop
• — @vividrop.bsky.social
• — Lynavo
• — YouTube Channel