Skip to content

Commit e0acaae

Browse files
Shrey113Shrey113
committed
docs: add comprehensive HTML documentation site for Android DEX system architecture and modules
1 parent 0253bff commit e0acaae

9 files changed

Lines changed: 1423 additions & 0 deletions

‎index.html‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
6+
<title>Android DEX | Integrated Technical Documentation</title>
7+
<!-- Combined Typography & System Fonts -->
8+
<link rel="preconnect" href="https://fonts.googleapis.com">
9+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
10+
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Outfit:wght@600;700&family=JetBrains+Mono&display=swap" rel="stylesheet">
11+
<link rel="stylesheet" href="web/style.css">
12+
</head>
13+
<body>
14+
<aside class="sidebar">
15+
<div class="logo-container">
16+
<div class="logo-icon">📱</div>
17+
<span class="logo-text">Android<span>DEX</span></span>
18+
</div>
19+
20+
<nav class="nav-menu">
21+
<div class="nav-group">
22+
<div class="nav-group-title">Getting Started</div>
23+
<div class="nav-item">
24+
<a href="index.html" class="nav-link active">Introduction</a>
25+
</div>
26+
</div>
27+
28+
<div class="nav-group">
29+
<div class="nav-group-title">Deep Dive</div>
30+
<div class="nav-item">
31+
<a href="web/architecture.html" class="nav-link">Architectural Design</a>
32+
</div>
33+
<div class="nav-item">
34+
<a href="web/boot-flow.html" class="nav-link">Boot & Initialization</a>
35+
</div>
36+
<div class="nav-item">
37+
<a href="web/reconnection.html" class="nav-link">Reconnection System</a>
38+
</div>
39+
<div class="nav-item">
40+
<a href="web/data-model.html" class="nav-link">Real-Time Data Model</a>
41+
</div>
42+
<div class="nav-item">
43+
<a href="web/error-handling.html" class="nav-link">Error Handling</a>
44+
</div>
45+
<div class="nav-item">
46+
<a href="web/modules.html" class="nav-link">System Modules</a>
47+
</div>
48+
<div class="nav-item">
49+
<a href="web/device-manager.html" class="nav-link">Device Manager</a>
50+
</div>
51+
</div>
52+
</nav>
53+
54+
<div class="sidebar-footer">
55+
<span class="version-badge">DEX-STABLE-104-SINGLE</span>
56+
</div>
57+
</aside>
58+
59+
<main class="main-content">
60+
<header class="page-header">
61+
<div class="breadcrumb">Documentation / Overview</div>
62+
<h1>Your Phone, Reimagined as a Desktop</h1>
63+
<p class="description">Architectural deep-dive into the synchronization between Windows NT and Android Linux environments. Reimagining Android as a high-performance desktop experience.</p>
64+
</header>
65+
66+
<section class="doc-section">
67+
<h2>Quick Start</h2>
68+
<p>Connect your device via USB or Wi-Fi to begin. The system auto-detects your device and initiates the secure handshake protocol.</p>
69+
<table>
70+
<thead>
71+
<tr>
72+
<th>Mode</th>
73+
<th>Setup</th>
74+
</tr>
75+
</thead>
76+
<tbody>
77+
<tr>
78+
<td><strong>USB</strong></td>
79+
<td>Plug in your phone · Enable **USB Debugging**</td>
80+
</tr>
81+
<tr>
82+
<td><strong>Wi-Fi</strong></td>
83+
<td>Same network · Enable **Wireless Debugging**</td>
84+
</tr>
85+
</tbody>
86+
</table>
87+
88+
<h3>Launch Options</h3>
89+
<pre><code># Auto-detect — recommended for first use
90+
android_dex_win.exe
91+
92+
# Force USB connection
93+
android_dex_win.exe --usb
94+
95+
# Connect to a specific IP address
96+
android_dex_win.exe 192.168.1.100
97+
98+
# Connect with explicit port
99+
android_dex_win.exe 192.168.1.100:5555</code></pre>
100+
<blockquote>
101+
<p><strong>Smart Auto-Detection:</strong> With no arguments, the app scans for available devices. One device found → connects automatically. Zero or multiple → the ADB Manager dialog opens to let you choose — no restart needed.</p>
102+
</blockquote>
103+
</section>
104+
105+
<section class="doc-section">
106+
<h2>The Handshake Protocol</h2>
107+
<p>A three-layer cryptographic-style handshake ensures all components are ready before the desktop UI unlocks.</p>
108+
109+
<div id="mermaid-protocol" class="mermaid">
110+
sequenceDiagram
111+
participant PC as Windows Side (Flutter/ADB)
112+
participant JAR as Android Logic Engine (Java JAR)
113+
participant APK as Android App Hub (Kotlin APK)
114+
115+
Note over PC: 1. ADB Initialization (startAdbBlocking)
116+
PC->>PC: 2. Local Server Setup (JarServer & ApkServer .start)
117+
118+
Note over PC,JAR: Phase 1: Engine Deployment (Bridge)
119+
PC->>JAR: Push JAR to Device (via ADB Pipe)
120+
PC->>JAR: Launch JAR Runtime (adb.startJarRuntime)
121+
JAR-->>PC: Handshake Response: "jar.hello" (Logic Engine Ready)
122+
123+
Note over PC,APK: Phase 2: Feature Manager Startup (Hub)
124+
PC->>APK: Check Install & Install if Missing
125+
PC->>APK: Trigger Service startup (ServerStartService)
126+
APK-->>PC: WebSocket Handshake: "apk.hello" (App Hub Ready)
127+
128+
PC->>APK: 3. Start Extended Notification & Media Services
129+
Note over PC,APK: System Synchronized: Desktop UI Unlocked
130+
</div>
131+
</section>
132+
133+
<section class="doc-section">
134+
<h2>Key Features</h2>
135+
<table>
136+
<thead>
137+
<tr>
138+
<th>Feature</th>
139+
<th>Description</th>
140+
</tr>
141+
</thead>
142+
<tbody>
143+
<tr><td><strong>Multi-Window Apps</strong></td><td>Each Android app runs in its own resizable, movable Windows window</td></tr>
144+
<tr><td><strong>Live Telemetry</strong></td><td>Real-time Battery, Volume, Wi-Fi, BT, Data & more</td></tr>
145+
<tr><td><strong>Notifications</strong></td><td>Android notifications pushed instantly to Windows desktop</td></tr>
146+
<tr><td><strong>Media Control</strong></td><td>Artwork, metadata & playback controls</td></tr>
147+
<tr><td><strong>Low Latency</strong></td><td>Shell-level commands bypass UI overhead</td></tr>
148+
<tr><td><strong>Auto-Healing</strong></td><td>Multi-stage recovery restores connection seamlessly</td></tr>
149+
</tbody>
150+
</table>
151+
</section>
152+
153+
<footer class="page-footer">
154+
<div></div> <!-- Spacer -->
155+
<a href="web/architecture.html" class="footer-link">
156+
<span>Next Section</span>
157+
<strong>Architectural Design →</strong>
158+
</a>
159+
</footer>
160+
</main>
161+
162+
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
163+
<script>
164+
mermaid.initialize({ startOnLoad: true, theme: 'dark' });
165+
</script>
166+
</body>
167+
</html>

‎web/architecture.html‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
6+
<title>Architecture — Android DEX</title>
7+
<link rel="preconnect" href="https://fonts.googleapis.com">
8+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
9+
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Outfit:wght@600;700&family=JetBrains+Mono&display=swap" rel="stylesheet">
10+
<link rel="stylesheet" href="style.css">
11+
</head>
12+
<body>
13+
<aside class="sidebar">
14+
<div class="logo-container">
15+
<div class="logo-icon">🏗️</div>
16+
<span class="logo-text">Android<span>DEX</span></span>
17+
</div>
18+
19+
<nav class="nav-menu">
20+
<div class="nav-group">
21+
<div class="nav-group-title">Getting Started</div>
22+
<div class="nav-item">
23+
<a href="../index.html" class="nav-link">Introduction</a>
24+
</div>
25+
</div>
26+
27+
<div class="nav-group">
28+
<div class="nav-group-title">Deep Dive</div>
29+
<div class="nav-item">
30+
<a href="architecture.html" class="nav-link active">Architectural Design</a>
31+
</div>
32+
<div class="nav-item">
33+
<a href="boot-flow.html" class="nav-link">Boot & Initialization</a>
34+
</div>
35+
<div class="nav-item">
36+
<a href="reconnection.html" class="nav-link">Reconnection System</a>
37+
</div>
38+
<div class="nav-item">
39+
<a href="data-model.html" class="nav-link">Real-Time Data Model</a>
40+
</div>
41+
<div class="nav-item">
42+
<a href="error-handling.html" class="nav-link">Error Handling</a>
43+
</div>
44+
<div class="nav-item">
45+
<a href="modules.html" class="nav-link">System Modules</a>
46+
</div>
47+
<div class="nav-item">
48+
<a href="device-manager.html" class="nav-link">Device Manager</a>
49+
</div>
50+
</div>
51+
</nav>
52+
53+
<div class="sidebar-footer">
54+
<span class="version-badge">DEX-STABLE-104-SINGLE</span>
55+
</div>
56+
</aside>
57+
58+
<main class="main-content">
59+
<header class="page-header">
60+
<div class="breadcrumb">Documentation / Deep Dive / Architecture</div>
61+
<h1>Three-Layer System Design</h1>
62+
<p class="description">How Android DEX distributes responsibilities across execution contexts to enable near-zero latency commands and deep system control.</p>
63+
</header>
64+
65+
<section class="doc-section">
66+
<h2>System Overview</h2>
67+
<div class="mermaid">
68+
graph TD
69+
PC[Windows Side: Flutter/ADB] -->|TCP| JAR[⚡ Logic Engine: Java JAR]
70+
PC -->|WebSocket| Hub[📱 Feature Hub: Kotlin APK]
71+
PC -->|Pipe| ADB[ADB Shell Context]
72+
ADB --> JAR
73+
Hub --> System[Android System Context]
74+
</div>
75+
<p>Both Android-side components <strong>connect back to the Windows side</strong> — the Windows app runs the servers; Android clients connect to them.</p>
76+
</section>
77+
78+
<section class="doc-section">
79+
<h2>Layer 1 — Windows Side</h2>
80+
<p><strong>Role:</strong> Orchestrator, UI host, server infrastructure, and rendering engine.</p>
81+
<table>
82+
<thead>
83+
<tr>
84+
<th>Domain</th>
85+
<th>What It Does</th>
86+
</tr>
87+
</thead>
88+
<tbody>
89+
<tr><td><strong>ADB Lifecycle</strong></td><td>Starts ADB server, connects device, sets up reverse port forwarding</td></tr>
90+
<tr><td><strong>Servers</strong></td><td>Runs 4 TCP/WebSocket servers that Android components connect to</td></tr>
91+
<tr><td><strong>JAR Deployment</strong></td><td>Locates, pushes, and launches the Logic Engine on the device</td></tr>
92+
<tr><td><strong>APK Management</strong></td><td>Detects, installs, and starts the companion APK service</td></tr>
93+
<tr><td><strong>Rendering</strong></td><td>Embeds scrcpy windows as native Win32 child windows inside Flutter</td></tr>
94+
<tr><td><strong>Reconnection</strong></td><td>Monitors connection state; auto-heals without user restart</td></tr>
95+
</tbody>
96+
</table>
97+
</section>
98+
99+
<section class="doc-section">
100+
<h2>Layer 2 — Logic Engine (Java JAR)</h2>
101+
<p><strong>Role:</strong> Shell-level command executor running with elevated ADB daemon privileges.</p>
102+
<p>The JAR, launched via <code>adb shell app_process</code>, executes at the <strong>ADB shell user level</strong> — allowing volume manipulation via <code>AudioService</code> and control over the <code>ActivityManager</code> without launcher process restrictions.</p>
103+
104+
<h3>Core Responsibilities</h3>
105+
<ul>
106+
<li><strong>Volume Control:</strong> Direct <code>AudioManager</code> stream access at shell level.</li>
107+
<li><strong>App Launch:</strong> <code>ActivityManager.startActivity()</code> with foreground flags.</li>
108+
<li><strong>App Kill:</strong> <code>ActivityManager.forceStopPackage()</code>.</li>
109+
<li><strong>Screen State:</strong> PowerManager + WakeManager invocation.</li>
110+
</ul>
111+
</section>
112+
113+
<section class="doc-section">
114+
<h2>Layer 3 — Feature Hub (Kotlin APK)</h2>
115+
<p><strong>Role:</strong> Permission-holding daemon for all telemetry and high-level Android APIs.</p>
116+
<p>Includes access to listener APIs that require app registration, such as <code>NotificationListenerService</code> and <code>MediaSessionManager</code>.</p>
117+
</section>
118+
119+
<footer class="page-footer">
120+
<a href="../index.html" class="footer-link">
121+
<span>Previous Section</span>
122+
<strong>← Introduction</strong>
123+
</a>
124+
<a href="boot-flow.html" class="footer-link">
125+
<span>Next Section</span>
126+
<strong>Boot & Initialization →</strong>
127+
</a>
128+
</footer>
129+
</main>
130+
131+
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
132+
<script>
133+
mermaid.initialize({ startOnLoad: true, theme: 'neutral' });
134+
</script>
135+
</body>
136+
</html>

0 commit comments

Comments
 (0)