init

docs/repository-structure.md

@@ -0,0 +1,49 @@
+# Repository and Package Structure
+
+## Android Project
+
+```text
+apps/android/app
+apps/android/core/domain
+apps/android/core/engine
+apps/android/feature/share
+apps/android/service/gateway
+```
+
+## Kotlin Packages
+
+```text
+org.vpnshare.app
+org.vpnshare.domain.model
+org.vpnshare.engine
+org.vpnshare.feature.share
+org.vpnshare.gateway
+org.vpnshare.gateway.discovery
+org.vpnshare.gateway.transport
+```
+
+Guidelines:
+
+- Domain module contains no Android platform APIs.
+- Engine module defines Kotlin-facing core interfaces and FFI adapters.
+- Gateway service module owns Android network, USB, NSD, hotspot, and
+  foreground-service integration.
+- Feature modules own Compose UI only.
+
+## Rust Workspace
+
+```text
+crates/vpnshare-proto
+crates/vpnshare-core
+crates/vpnshare-transport
+crates/vpnshare-ffi
+clients/desktop
+```
+
+Guidelines:
+
+- `vpnshare-proto` owns stable wire format.
+- `vpnshare-core` owns packet tunnel domain logic.
+- `vpnshare-transport` owns transport-independent I/O traits.
+- `vpnshare-ffi` is the narrow C ABI/JNI bridge.
+- Platform clients bind the Rust core to virtual NIC and OS lifecycle APIs.