FreedomRTC

Overview

FreedomRTC is a peer-to-peer VPN application that lets Android users share internet connections. One device acts as a Server (shares internet), while another acts as a Client (uses the shared VPN). Traffic flows through encrypted WebRTC data channels — no centralized VPN server is needed.

System Architecture

The system consists of three main components:

Component	Technology	Purpose
Android App	Kotlin, Jetpack Compose	VPN client/server with P2P connectivity
Signaling Server	Node.js, Socket.IO, Nginx	Room management, SDP/ICE relay for WebRTC
STUN/TURN Server	Coturn	NAT traversal, relay when P2P fails

How It Works

1. Server device shares its internet connection
2. Client device connects via WebRTC data channel
3. All client traffic routes through the encrypted P2P tunnel
4. Server forwards packets to the real internet and returns responses

Android Application

Modular Architecture

The app follows modular architecture principles with clear separation of concerns:

Layer	Components	Responsibility
Presentation	Jetpack Compose, ViewModels, StateFlow	UI and user interaction
Domain	Repository interfaces, Models	Business logic contracts
Data	Repository implementations, DataStore, Room DB	Data persistence and network
WebRTC	WebRTCClient, SessionManager, ICE config	P2P connection management
VPN	VpnService, PacketReader/Writer, NAT forwarding	Traffic tunneling

Key Components

VPN Client Mode

• TUN interface with virtual IP (10.0.0.2/24)
• Routes all traffic (0.0.0.0/0) through WebRTC tunnel
• VpnPacketReader/Writer for TUN ↔ WebRTC data flow

VPN Server Mode

• ServerPacketForwarder implements user-space NAT
• TCP session management with full handshake (SYN→SYN-ACK→ACK)
• UDP sessions via NIO Selector with 30s timeout
• IP packet parsing and checksum calculation

WebRTC Layer

• PeerConnection with STUN/TURN ICE servers
• Ordered, reliable DataChannel for VPN traffic
• Automatic ICE candidate gathering and exchange

Dependency Injection (Hilt)

Module	Provides
AppModule	DataStore, Room Database, DAOs, Repository bindings
NetworkModule	OkHttpClient, GeoLocationApi, SignalingClient
WebRTCModule	IceServerConfig, WebRTCClient, SessionManager

Signaling Server

Node.js + Socket.IO Architecture

The signaling server handles peer discovery and WebRTC connection establishment:

REST Endpoints

• GET /status - Server status and statistics
• GET /health - Health check for monitoring
• GET /rooms - List of active rooms

Socket.IO Events

Client → Server	Server → Client
create-room, join-room, leave-room	room-created, room-joined, room-left
offer, answer, ice-candidate	Relayed to target peer
update-role, get-room-users	user-joined, user-left, user-updated
heartbeat (20s interval)	room-users-sync

Background Jobs

• Stale session cleanup every 15s removes inactive users
• Auto-delete empty rooms
• Notify room members of removed users

STUN/TURN Configuration

ICE servers enable NAT traversal for P2P connectivity:

Server Type	Address	Purpose
Google STUN	stun.l.google.com:19302	Public IP discovery
Custom STUN	Configurable	Self-hosted option
Custom TURN	UDP/TCP 3478, TURNS 5349	Relay when P2P fails
Fallback TURN	openrelay.metered.ca	Free relay service

VPN Packet Flow

Complete flow when a client opens a website:

1. Client App → IP packet to TUN interface
2. VpnPacketReader → Reads from TUN, sends via WebRTC
3. WebRTC Data Channel → Encrypted P2P transfer
4. ServerPacketForwarder → Parses IP/TCP/UDP headers
5. Real Socket → Connects to actual destination
6. Response → Reverse path back to client app

TCP Session Handling

The server implements full TCP state machine:

• SYN → Socket.connect() to destination
• Data → Forward payload, return ACK
• FIN → Graceful close with FIN-ACK

WebRTC Connection Flow

1. Server clicks “Share Internet” → Sends update-role to signaling
2. Client clicks “Use VPN” → Creates offer SDP
3. Offer/Answer exchange via signaling server
4. ICE Candidates gathered and exchanged bidirectionally
5. DataChannel established (P2P or via TURN relay)
6. VPN Traffic flows over encrypted channel

Use Cases

• Network Freedom - Bypass restrictions using a peer’s connection
• Secure P2P - End-to-end encrypted communication
• Internet Sharing - Share mobile data with trusted peers
• Privacy - No centralized VPN server logging traffic