Skip to content

context.md

Latest commit

 

History

History
91 lines (69 loc) · 4.59 KB

context.md

File metadata and controls

91 lines (69 loc) · 4.59 KB
Raw

Sync360 Project Context

Sync360 is an Android-first Kotlin Multiplatform / Compose Multiplatform app for nearby sharing over a local network.

open app -> discover nearby device -> choose content -> receiver approves -> send directly

The old AI-generated sync implementation was removed. The current app is being rebuilt manually so its maintainer can understand and own the complete discovery, request, transfer, and storage path.

Current implementation

  • Shared Compose Send/Receive UI, ViewModels, controllers, state, and Navigation 3.
  • Compact single-pane navigation and a 50/50 Send/Receive scene on wider windows.
  • Android discovery/registration through NsdManager.
  • Windows discovery/registration through the operating system dnsapi.dll DNS-SD API on all interfaces.
  • Current macOS/Linux discovery/registration through JmDNS on eligible IPv4 and IPv6 LAN addresses.
  • Application-lifetime network startup with separate discovery and registration lifecycle states.
  • Ktor HTTP offers, receiver decisions, metadata, and text payloads.
  • Raw TCP streaming for file bytes.
  • Multiple files sent sequentially over one accepted-batch connection.
  • Android file access through ContentResolver and Downloads writing through MediaStore.
  • Desktop native file selection, Java file streams, and safe Downloads writing through temporary .part files.
  • iOS Bonjour discovery, native document selection, streamed Ktor TCP transfer, and Files-visible Downloads storage.
  • Best-effort cancellation and batch-wide byte percentage.

Android-to-Android text and multiple-file flows have manual validation. Desktop-to-Android transfer has initial manual validation. In one Windows 11 Ethernet test, native Windows discovery added and removed Android promptly as its app opened and closed, while Android added and removed Windows promptly as the Desktop app opened and closed. The enabled iOS implementation has opened successfully in a cloud simulator, but same-LAN discovery and transfer could not be tested there. Laptop, macOS, Linux, physical iOS, and broader adapter/network behavior still need validation. The app is still development software, not a production-ready release.

Architecture rule

Compose screen -> ViewModel -> controller/service -> common contract -> platform implementation
  • UI renders state and calls ViewModel actions.
  • ViewModels own UI-facing operations and state.
  • Controllers coordinate network and transfer services.
  • Ktor DTOs remain at the HTTP boundary.
  • Blocking file/socket work runs on Dispatchers.IO.
  • Files are streamed; they are never loaded whole into memory.
  • Platform APIs stay in Android, JVM, and iOS source sets.

Protocol summary

Ktor HTTP is the control plane:

POST /sync360/text/offer
POST /sync360/text/transfer
POST /sync360/file/offer
POST /sync360/operation/cancel

Raw TCP is the file data plane:

one connection per accepted batch
  -> accepted operation ID as 16 raw UUID bytes
  -> repeat for each file:
       -> file index
       -> promised byte count
       -> exact file bytes
  -> sender flushes once
  -> receiver returns final success and completed-file count

Current shared transfer constants use a 512 KiB payload buffer, 5-second connect timeout, 60-second connected-socket timeout, and 30-second wait for the first file connection after acceptance.

Current priorities

  • Better receiver-side errors and per-file results.
  • Automatic registration repair after network/address changes.
  • Foreground/background lifecycle support.
  • Broader Desktop adapter, firewall, router, and operating-system validation.
  • Android 17 local-network permission-aware startup and serialized Android 13 legacy NSD resolution.
  • Closing the narrow shared Accept/Cancel response race.
  • Session validation, authentication, encryption, and integrity verification.

Important limitations

Sync360 currently uses cleartext local HTTP and raw TCP. Operation IDs correlate protocol messages and file sockets but do not authenticate a peer. The app has receiver approval but no authentication, encryption, or checksum. The current target-SDK-37 Android build also lacks Android 17's required local-network runtime-permission flow. Windows receiving depends on Windows Firewall allowing the application. Use development builds only on private networks you control.

For detailed and current information, read:

Source code wins if documentation and implementation ever conflict.