GSoC 2026 Proposal Draft - Idea 9: LAN Sync - Yousef Genedy

GSoC GSoC Proposal Drafts
1

GSoC 2026 Proposal Draft - Idea 9: LAN Sync - Yousef Genedy

1. Links

2. Contributions to Joplin

I started contributing to Joplin around the end of January 2026 to better understand the project and its development workflow. During this time, I read through much of the available documentation and explored different parts of the codebase to get familiar with the architecture and how the application works.

Since then, I have been making small contributions to the project while continuing to learn more about the codebase. My contributions so far include:

Link Description Status
PR #14574 Start sync when app opens or resumes Merged
PR #14360 Make notebook search accent-insensitive in GotoAnything Merged
PR #14429 E2EE setup dialog theme and cancel validation Closed
PR #14818 Implement note attachments management screen Merged
Issue #14428 Desktop: E2EE setup dialog inconsistent with dark theme and shows “key required” after Cancel Closed

I am continuing to contribute during the proposal period and plan to submit more improvements as I explore the codebase further.

3. Introduction

My name is Yousef Genedy. I am a software engineer with experience building backend systems and engineering platforms. I have worked on scalable services and data processing systems, and I am particularly interested in distributed systems, and open-source software.

I am particularly interested in extending Joplin sync toward robust device-to-device synchronization over LAN.

4. Project Summary

Joplin currently synchronizes notes and resources using external sync targets such as Joplin Server, WebDAV, cloud providers, or filesystem sync. These methods require either internet access or additional tools acting as a shared backend.

The goal of this project is to add LAN synchronization, enabling Joplin devices on the same local network to synchronize directly with each other without relying on external services.

This feature would provide several benefits:

  • Synchronization without requiring internet access
  • Improved privacy since data remains within the local network
  • Faster synchronization between nearby devices
  • Simpler setup without configuring external sync tools

This proposal introduces a Virtual Sync Target over Multiple Peers architecture. Joplin continues interacting with a single logical sync target, while internally coordinating synchronization across multiple devices on the network.

The virtual layer discovers peers, exchanges metadata, and builds a unified logical namespace. To the existing synchronization system, it behaves like a normal backend while internally routing reads and writes between participating devices.

5. Goals

  • Enable synchronization without internet dependency.
  • Keep data exchange within local network boundaries.
  • Reuse Joplin sync architecture instead of redesigning it.
  • Provide a practical foundation for true multi-peer LAN synchronization.

6. Technical Approach

6.1 Design Overview

The goal of this project is to enable peer-to-peer synchronization between Joplin devices on the same local network without requiring an external server.

To achieve this, the proposal introduces a virtual LAN sync backend that represents multiple peers as a single logical synchronization target. The synchronizer continues interacting with one target, while the LAN implementation internally coordinates communication with multiple devices.

Synchronizer → LAN Sync Target → Virtual Coordination Layer → Multiple Peers

The virtualization layer ensures that the synchronizer still interacts with a single logical backend while internally coordinating communication across multiple devices.

The virtualization layer manages peer discovery, trusted devices, and distributed synchronization operations, while exposing a unified remote state to the synchronizer. This allows LAN peer-to-peer synchronization to integrate with the existing sync system while encapsulating the distributed coordination logic inside the LAN target.

Benefits of the Virtual Sync Target Approach

  1. Compatibility with the current sync model: the synchronizer continues interacting with a single logical backend.
  2. Multi-device synchronization: multiple peers can participate without requiring a dedicated server.
  3. Improved availability: devices can synchronize with any reachable peer on the network.
  4. Extensibility: the coordination layer allows future improvements such as better peer selection or replication strategies.

Special attention will be given to cross-platform compatibility. The implementation will ensure that LAN synchronization works consistently across desktop and mobile environments, particularly addressing known performance limitations of filesystem-based synchronization on Android.

6.2 How the Virtual Backend Works

The virtual backend presents multiple LAN peers as a single logical synchronization target.
Each synchronization session follows a deterministic process:

  1. Discover reachable peers and verify trust.
  2. Fetch peer inventories and metadata.
  3. Build one merged logical namespace.
  4. Select a lock / lease authority peer.
  5. Route reads through canonical peer mapping.
  6. Commit writes through the authority peer.
  7. Propagate writes to other peers.
  8. Apply deterministic info.json authority policy

This design balances high-level behavior, where multiple peers appear as a single logical backend, with low-level safety guarantees, including correct SYNC / EXCLUSIVE lock handling and preservation of info.json synchronization invariants.

6.3 Architectural Diagrams

High-level architecture

High-level architecture
High-level architecture1600×480 39.9 KB

End-to-End Sync Flow

End-to-End Sync Flow
End-to-End Sync Flow1600×693 81.3 KB

Discovery and trust sequence diagram

Discovery and trust sequence diagram
Discovery and trust sequence diagram1600×665 109 KB

Read operation sequence

Read operation sequence
Read operation sequence1600×651 96.9 KB

Write and propagation sequence

Write and propagation sequence
Write and propagation sequence1600×602 99.6 KB

Lock and lease sequence

Lock and lease sequence
Lock and lease sequence1600×825 123 KB

6.4 Changes to the Joplin codebase

This section centralizes all planned modifications to the Joplin codebase required to support LAN peer-to-peer synchronization.

New Files / Modules

  • New sync target and driver

    • packages/lib/SyncTargetLanP2P.ts
    • packages/lib/file-api-driver-lanP2P.ts

  • New LAN services

    • Directory:
      • packages/lib/services/lanP2P/
    • Modules:
      • PeerDiscoveryService.ts
      • PeerDirectory.ts
      • PeerSessionClient.ts
      • VirtualTargetCoordinator.ts
      • PeerMergeIndex.ts
      • PeerLockCoordinator.ts
      • SyncInfoMergePolicy.ts

    These services provide peer discovery, session management, metadata coordination, and conflict-safe synchronization logic across peers.

Updates to Existing Code

packages/lib/BaseApplication.ts

  • Register the new SyncTargetLanP2P in SyncTargetRegistry
  • Initialize and manage any LAN runtime side effects such as peer discovery services

packages/lib/models/settings/builtInMetadata.ts

Add configuration settings for:

  • peer discovery mode
  • manual peer endpoints
  • trust/bootstrap configuration

packages/lib/SyncTargetRegistry.ts

  • Include metadata describing the new synchronization target
  • Register the target in the synchronization option order

Configuration UI paths (existing settings rendering)

  • Surface the new settings using the sync.<id>.* configuration namespace.

Components Intentionally Unchanged

The following core synchronization components will remain unchanged to preserve compatibility with the existing architecture:

  • Core synchronization algorithm: packages/lib/Synchronizer.ts
  • Public file API contract: packages/lib/file-api.ts
  • Existing lock coordination mechanism: packages/lib/services/synchronizer/LockHandler.ts

6.5 Libraries and Technologies

The implementation will primarily rely on technologies already used in the Joplin codebase to ensure compatibility across desktop and mobile platforms.

Core Implementation

  • TypeScript will be used for all new LAN synchronization modules.
  • Reuse of Joplin’s existing SyncTarget and FileApi abstractions so the synchronizer can interact with LAN peers as a normal backend.

LAN Discovery

  • mDNS / DNS-SD (Bonjour-compatible discovery) will be used for automatic peer discovery on local networks.
  • A manual peer configuration mechanism will be provided as a fallback when multicast discovery is not available

Peer Communication

  • Reuse of the existing LAN networking patterns already present in:
    • packages/lib/file-api-driver-lan.ts
    • packages/lib/services/lan/LanSyncService.ts
  • Peers will communicate through a lightweight API supporting operations such as metadata exchange, object transfer, and lock/lease coordination.

Security and Transport Protection

  • TLS encryption for all peer-to-peer communication.
  • Device pairing / trust model so users explicitly approve participating devices.
  • Authentication tokens or signed requests to prevent unauthorized access.

6.6 Potential Challenges and Risks

Distributed Lock Consistency

  • Risk: Conflicting lock ownership across peers in a distributed environment.
  • Mitigation: Use a single authority lease peer per session with strict TTL refresh and cancel the session on lease loss.

info.json Authority Conflicts

  • Risk: Divergent synchronization metadata across peers due to concurrent updates.
  • Mitigation: Use one authoritative info.json source per session with deterministic merge and write policies.

Peer Divergence on Partial Propagation

  • Risk: Authority commit succeeds while propagation to replicas fails, causing temporary divergence.
  • Mitigation: Use a durable retry queue, divergence markers, and automatic repair during the next synchronization.

Clock Skew and Ordering Ambiguity

  • Risk: Timestamp-only ordering can produce incorrect merges when device clocks differ.
  • Mitigation: Use deterministic tie-breakers and metadata-aware selection rules.

Network Instability and Peer Churn

  • Risk: Peers may disconnect during synchronization, interrupting the session.
  • Mitigation: Freeze the authority within the session, fail safely on disconnect, and retry in the next session.

Debugging Complexity

  • Risk: Multi-peer failures can be difficult to reproduce and analyze.
  • Mitigation: Use structured tracing IDs and deterministic integration test scenarios.

Project Scope and Timeline

  • Risk: The project scope may exceed the GSoC timeline due to the complexity of distributed synchronization.
  • Mitigation: Prioritize a stable core implementation during GSoC and agree with mentors on the deliverables. Remaining improvements can continue after the program.

6.7 Testing Strategy

The implementation will include automated testing to validate multi-peer synchronization behavior.
Testing will include:

  • Unit tests for peer discovery, merge index, and coordinator logic
  • Integration tests simulating multiple peers exchanging objects
  • Fault-injection tests for network failures and partial propagation
  • Lock and lease validation tests to ensure compatibility with Joplin’s existing synchronization guarantees
  • Testing will use existing Joplin test infrastructure and mock peer nodes where necessary.

7. Implementation Plan

  1. Community Bonding Period
    • Refine the LAN P2P architecture and synchronization workflow based on mentor feedback.
    • Study Joplin synchronization internals in more depth (Synchronizer, SyncTarget, FileApi, lock handling, and info.json behavior).
  2. Week 1–2 — Project setup and LAN sync target foundation
    • Implement the base LAN sync target and driver (SyncTargetLanP2P, file-api-driver-lanP2P) and register it in SyncTargetRegistry.
    • Add initial configuration settings and basic integration tests for the new sync target.
  3. Week 3–4 — Peer discovery and trust
    • Implement peer discovery using mDNS / DNS-SD and manual peer configuration fallback.
    • Implement PeerDirectory and device pairing / trust verification.
  4. Week 5–6 — Peer communication layer
    • Implement PeerSessionClient for peer-to-peer API communication and metadata exchange.
    • Define lightweight peer endpoints for object retrieval, upload, and coordination operations.
  5. Week 7–8 — Virtual synchronization layer
    • Implement VirtualTargetCoordinator and PeerMergeIndex to build the merged logical namespace.
    • Route read operations (list, get, delta) through canonical peer selection.
  6. Week 9–10 — Write coordination and propagation
    • Implement authority-based write commit through a selected peer.
    • Implement replication and retry mechanisms for propagating updates to other peers.
  7. Week 11–12 — Lock and metadata coordination
    • Implement PeerLockCoordinator to provide lease-based lock compatibility with Joplin sync locks.
    • Implement deterministic info.json authority and merge policy.
  8. Week 13–14 — Testing and documentation
    • Add integration tests for multi-peer synchronization scenarios and failure cases.
    • Write technical documentation explaining the architecture and synchronization behavior.

8. Deliverables

At the end of the project:

  • New LAN sync target implementation based on virtualization (SyncTargetLanP2P)
  • FileApi-compatible multi-peer backend driver (FileApiDriverLanP2P)
  • Peer discovery, trust directory, and peer communication services
  • Merged virtual namespace for read operations
  • Authority commit + propagation model for write operations
  • Lease/lock compatibility with Joplin sync lock behavior
  • Deterministic info.json policy for multi-peer sessions
  • Tests and technical documentation for architecture and usage
  • Configuration UI and documentation for enabling LAN synchronization

9. Availability

  • Weekly availability during GSoC
    I can dedicate approximately 30 hours per week on average to the project throughout the GSoC period.

  • Timezone
    Cairo, Egypt Standard Time (GMT+2).

  • Other commitments during the programme
    I currently work as a software engineer with a flexible schedule, which allows me to consistently dedicate the required time to the GSoC project. I will prioritize the project and maintain regular communication with mentors.

10. Future Work

Possible extensions after GSoC include:

  • Improved peer selection and replication strategies
  • Background synchronization optimization for mobile devices
  • Optional conflict diagnostics and visualization tools
  • Extended peer discovery mechanisms across subnet boundaries
2

May I ask, what would be the benefit of adding a host based LAN sync to Joplin? You could just host any open source WebDAV server on the local network (not exposed to the internet) and it would essentially offer the same?

My guess is that this proposal is intended to be hostless device to device sync

3

I think your point about using a local WebDAV server is valid and could provide similar functionality. My idea with the host-based approach was mainly about simpler UX, instead of installing and configuring WebDAV, a user could just enable something like “LAN Host Mode” in Joplin and other devices could connect to it directly, and this approach work without internet as well.

Regarding this comment, I wanted to ask: is the idea expected to be true P2P sync between devices? And if so, should this be another sync target option, or should it work alongside existing sync targets (for example syncing to cloud and LAN when available)?

4

Just keep in mind we already have the File System sync target which many people already use to perform LAN syncing. What does a host based sync model provide over using that existing target?

Also, I appreciate that this was made before the guidance post was pinned here but could you make sure update the draft to the template - GSoC 2026: How to Submit Your Proposal Draft

5

So what this proposal is about is device-to-device synchronisation, without going through a third device. Maybe investigate what already exists? How is it usually implemented? Isn't SyncThing working like this?

6

Yes, Syncthing is a good example. I believe it has both a host mode and peer to peer mode. Technically Syncthing will allow peer to peer sync with Joplin via file system sync, but support for file system sync on mobile has severe performance issues on Android. So a built in peer to peer LAN sync would enable a smooth experience across both the desktop and mobile apps, and without the need to run any kind of background / foreground service on the mobile app

7

My approach with Host-Based LAN Sync is that it is easier to set up and provides better UX. It would be built directly into Joplin with integrated device discovery, built-in pairing, and a simple way to enable something like “LAN Host Mode”, without any external tools. And it also fits well with the current sync architecture which assumes that there is a sync target.

Based on your comments, it seems the intention of the project is closer to true device-to-device (P2P) synchronization.

I’ll look more into Syncthing and similar approaches and refine my proposal.

8

Thanks for the feedback and discussion earlier. After researching different approaches, I decided to focus on a virtual sync target over multiple peers model.

In this approach, devices on the same local network discover each other and exchange synchronization data directly. Instead of relying on a single host device, every device can participate as a peer. A coordination layer then aggregates the available peers and presents their combined state as a single logical backend for the synchronization process.

I’ve prepared a draft proposal describing the architecture, design considerations, potential risks, and implementation plan. I’d really appreciate any feedback or suggestions for improvements.

Links:

9

Hi please see here for information on how to submit your draft:

I've upgraded your account so you should be able to modify your top post

10

I've updated the post to match the guidelines and waiting for feedback from mentors and contributors

11

Hi @Daeraxa and @CalebJohn,

I noticed from the idea list repo that you are the potential mentors for the LAN Sync project.

I’ve shared a draft proposal for the LAN Sync idea and would really appreciate your feedback when you have time.

Thanks

12

The idea of synching from multiple peers is interesting, but I can’t think of a reason that would justify the complexity. Is the idea that synching speed can be increased?

I would also like to see an expansion of what the experience is like for a user. For example, I initiate a LAN sync from my phone; does this mean I am unable to make writes on my computer (because it is sensing data to the phone)?

13

Initially, I explored a host-based LAN sync approach. However, based on earlier feedback, it seems the intention of this project is closer to a pure (P2P) model. The main comment is that we can simulate (with some workarounds and configurations) the host-based LAN sync, so I shifted to a design that provide a more native P2P experience.

The main idea is not just increasing speed, but enabling a true peer-to-peer sync model while still fitting into Joplin’s sync system, and some benefits for this is the following:

  • Pure P2P from user perspective with no need to set up or manage a host/server device
  • Works offline
  • More than two devices can join and sync without relying on a single node
  • If one device is offline, others can still sync
  • This approach of virtualization layer avoids reimplementing the entire sync logic and instead adapts it to a distributed setting

So the goal is to behave like a P2P system externally, while internally mapping it to a model that Joplin can work with.

About the user experience, this is how can I think about it:

  1. The user selects “LAN Sync” from the sync target dropdown
  2. A LAN-specific settings section appears:
    • automatic discovery of nearby devices (similar to LocalSend)
    • optional manual entry if discovery is not available
  3. When a new device is found:
    • the user initiates pairing
    • the other device receives a confirmation request
    • once approved, the device becomes trusted
  4. After pairing:
    • devices appear in a list of available peers
    • sync can be triggered normally (like any other sync target)
  5. During sync:
    • devices can continue reading and writing locally
    • synchronization happens in the background
    • conflicts are handled using the existing Joplin sync logic

so, for your question:

yes, devices are not locked globally. The system uses coordination (locks/leases) only for sync-critical sections, similar to how current sync works with remote targets. Normal usage remains unaffected.