ZapbirdDocs

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.

  1. Your projectYour computer
    • Dart files in lib/
    • Assets
    • pubspec.yaml
    • zapbird.yaml
  2. zapbirdYour computer
    • File watcher
    • Compiler
    • TLS server
    • QR code and pairing
    • Doctor
    • SDK manager
  3. Runner SDKYour computer
    • Compiler files that match one runner build
  4. Your networkLocal Wi-Fi or Tailscale
    • TLS with the server certificate from the QR code
    • Local addresses only
  5. Zapbird runnerYour phone
    • Pairing and approval
    • Checks new code
    • Applies changes in place
    • Shows errors
    • Recent projects
Zapbird from your editor to your phone.

#The parts

PartRuns onResponsible for
Your projectYour computerYour Flutter app. Zapbird reads it and never changes it, except when you ask doctor --fix to set package versions.
zapbirdYour computerWatching files, compiling, serving the phone, pairing and the checks in doctor.
Runner SDKYour computerThe compiler files for one build of the runner. Installed and switched by zapbird sdk.
Zapbird runnerYour phoneConnecting to the server, running your app and showing what happens to it.

#From save to screen

  1. The file watcher in zapbird sees that you saved a file.
  2. The compiler turns your project into bytecode, using the runner SDK.
  3. zapbird offers the new code to the paired phone over the TLS connection.
  4. The runner downloads the new code and checks it before using it.
  5. 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

ModeCompiled byUpdates
BytecodeThe runner SDKEvery save reaches the phone by itself.
KernelYour FlutterYou 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.

Was this doc helpful?

Zapbird sends no analytics. Read about security.

Flutter and the related logo are trademarks of Google LLC. Zapbird is not endorsed by or affiliated with Google LLC.

esc