Architecture Overview
JetStart is a modular monorepo of TypeScript and Kotlin packages that work together to deliver instant hot reload for Android Jetpack Compose.
System Architecture
Core Components
@jetstart/cli
The jetstart command-line tool. Developers interact with JetStart entirely through this package.
- Project creation and scaffolding (
jetstart create) - Starting the development server (
jetstart dev) - Building APKs with release security hardening (
jetstart build) - Streaming live device logs (
jetstart logs) - Android emulator management (
jetstart android-emulator) - Environment dependency auditing (
jetstart install-audit)
@jetstart/core
The server that does the real work. Runs three networked services and owns the entire hot reload pipeline.
Servers:
| Service | Port | Purpose |
|---|---|---|
| HTTP (Express) | 8765 | REST API, APK downloads, web emulator redirect |
| WebSocket | 8766 | Real-time comms with devices and browser |
| (Logs delegated to @jetstart/logs) | 8767 | Log aggregation |
Hot reload pipeline:
File change (chokidar)
→ KotlinCompiler (kotlinc + Compose plugin → .class files)
→ OverrideGenerator ($Override companion classes, InstantRun-style)
→ DexGenerator (d8 → classes.dex, minApi 24)
→ WebSocketHandler.sendDexReload() (core:dex-reload to all Android clients)
@jetstart/shared
Single source of truth for all TypeScript types, the WebSocket protocol definition, validation helpers, and constants. Every other TypeScript package imports from here.
@jetstart/web
React + Vite web emulator hosted at https://web.jetstart.site. Auto-opened when the HTTP server redirects http://localhost:8765. Receives core:js-update (compiled Kotlin/JS ES module) and renders a live Compose UI preview in the browser.
@jetstart/logs
Standalone WebSocket log server on port 8767. Maintains an in-memory ring buffer of up to 10,000 log entries. The jetstart logs CLI command connects here to stream logs to the terminal.
Client App (Android)
The Kotlin/Compose companion app. Scans the QR code, authenticates with the session token, triggers the initial build, downloads and installs the APK, and then loads incoming DEX patches via hot-reload-runtime for all subsequent changes.
Hot Reload Data Flow
Communication Protocols
HTTP (port 8765)
| Endpoint | Purpose |
|---|---|
GET / | Redirects to web emulator with session params |
GET /health | Health check |
GET /version | Server version |
POST /session/create | Create session + QR code |
GET /session/:id | Get session info |
GET /download/:filename | Download built APK |
WebSocket (port 8766)
Key message types:
| Direction | Type | Purpose |
|---|---|---|
| Client → Core | client:connect | Auth with sessionId + token |
| Client → Core | client:log | Forward device logs |
| Client → Core | client:heartbeat | Keep-alive (every 30s) |
| Core → Client | core:connected | Auth confirmed |
| Core → Client | core:build-complete | APK ready with download URL |
| Core → Client | core:dex-reload | Hot reload: base64 DEX + class names |
| Core → Client | core:js-update | Web emulator: base64 ES module |
See WebSocket Protocol for the complete specification.
Package Dependencies
@jetstart/cli ──► @jetstart/core ──► @jetstart/shared
@jetstart/web ─────────────────────► @jetstart/shared
@jetstart/logs ─────────────────────► @jetstart/shared
[`packages/client`](../packages/client.md) (Kotlin — no npm deps, implements WS protocol independently)
[`packages/gradle-plugin`](../packages/gradle-plugin.md) (Kotlin — no npm deps)
[`packages/hot-reload-runtime`](../packages/hot-reload-runtime.md) (Kotlin — the ClassLoader used by the client app)
Security Model
Session tokens — Every jetstart dev run generates a fresh sessionId and token. Both are embedded in the QR code. Any device presenting the wrong sessionId is closed immediately with WebSocket code 4001; wrong token with 4002. A device built during a previous session cannot reconnect to a new one — the user must rescan the QR.
Release builds — jetstart build --release strips the dev-server URL and session token from BuildConfig before compiling, and restores build.gradle to its original state even if the build fails. No dev credentials appear in production binaries.
Performance
| Operation | Typical time |
|---|---|
| Hot reload (Kotlin → DEX → device) | 62 – 135 ms |
| Initial Gradle debug build (incremental) | 10 – 30 s |
| Initial Gradle debug build (clean) | 30 – 60 s |
| APK download over local Wi-Fi | 500 ms – 2 s |
Related Documentation
- Hot Reload System — full pipeline details
- Build System — Gradle build and ADB integration
- WebSocket Protocol — complete message specification
- Session Management — session lifecycle
- Package Structure — detailed monorepo layout