Architecture
The parts of Zapbird, where each one runs, and what passes between them.
Zapbird is a small system with two ends. A server runs on your computer next to your project, and a runner app runs on your phone. They meet over your own network. There is nothing in between: no cloud service and no account.
- Your projectYour computer
- Dart files in lib/
- Assets
- pubspec.yaml
- zapbird.yaml
- zapbirdYour computer
- File watcher
- Compiler
- TLS server
- QR code and pairing
- Doctor
- SDK manager
- Runner SDKYour computer
- Compiler files that match one runner build
- Your networkLocal Wi-Fi or Tailscale
- TLS with the server certificate from the QR code
- Local addresses only
- Zapbird runnerYour phone
- Pairing and approval
- Checks new code
- Applies changes in place
- Shows errors
- Recent projects
#The parts
| Part | Runs on | Responsible for |
|---|---|---|
| Your project | Your computer | Your Flutter app. Zapbird reads it and never changes it, except when you ask doctor --fix to set package versions. |
| zapbird | Your computer | Watching files, compiling, serving the phone, pairing and the checks in doctor. |
| Runner SDK | Your computer | The compiler files for one build of the runner. Installed and switched by zapbird sdk. |
| Zapbird runner | Your phone | Connecting to the server, running your app and showing what happens to it. |
#From save to screen
- The file watcher in zapbird sees that you saved a file.
- The compiler turns your project into bytecode, using the runner SDK.
- zapbird offers the new code to the paired phone over the TLS connection.
- The runner downloads the new code and checks it before using it.
- The runner applies the change in place, keeping your app state for supported edits.
If your code does not compile, the error is shown on the phone and printed in your terminal. The last working version keeps running.
#How a phone joins
Pairing ties one phone to one server session. The server makes a new certificate each time it starts and puts it in the QR code, so the phone talks only to the server it scanned.
- The QR code carries the server address, a secret and the certificate.
- Typing an address instead of scanning needs a 6-digit code you type in the terminal.
- The QR code works for 24 hours, or once with
--single-use-qr, and a new one (p) ends the old one.
#Two ways to run
| Mode | Compiled by | Updates |
|---|---|---|
| Bytecode | The runner SDK | Every save reaches the phone by itself. |
| Kernel | Your Flutter | You press r to reload and R to restart. |
Without a runner SDK installed, zapbird start serves kernel mode. With one, it chooses bytecode on its own.
#Where the boundaries are
#What stays on your computer
Your source files. The phone gets compiled bytecode and your assets, unless you start with --allow-phone-edit.
#What the phone keeps
Pairing details in memory, and a list of recent projects for the session.
#What leaves your network
Nothing about your project. The only outside connection zapbird makes is to the SDK download host, when you install or upgrade an SDK. Read Data and network for the full list.