Local-First on One Device: What Flowo's Architecture Costs

What local-first means in Flowo

In Flowo, the phone holds the only copy of a person's tasks and schedule, in Hive boxes encrypted on the device.

No server holds a second copy. Jobs that a hosted product hands to its database and its operators become jobs for the app. The app has to open storage in a safe order, keep two writers apart, apply a change completely or leave the previous plan in place, and delete everything when the person asks.

We describe the absence of multi-device sync in a separate article. This one covers what the design costs inside a single install.

The startup order

Flowo starts in four steps that always run in the same order: secure storage, environment, security checks, storage.

The first step resolves the storage key from the iOS Keychain or the Android Keystore. No box can be opened without that key, so it comes before everything else and a failure here stops the launch.

The storage step registers every Hive type adapter, initialises Hive and claims a lease file. Only then does the first box open. Boxes that hold a person's data are opened one at a time through a single encrypted-open call in our storage service, and that service is the only place in the app that calls Hive's own open function.

If a step throws, the app shows a failure screen with the name of the step, a retry button and a way to copy the technical detail. If startup has not finished after 8 seconds, the splash screen changes its text to say it is taking longer.

Opening boxes is the heaviest file work at launch. We pause for 32 milliseconds between the heavy opens so the splash animation keeps drawing. An earlier 16 millisecond pause was too short, because one Hive file operation sometimes takes 8 to 12 milliseconds.

One writer at a time

Two parts of Flowo can touch the same files: the app on screen, and a background job that tops up reminders about once a day.

On Android that job runs in a second isolate of the same process. Hive keeps separate box instances for each isolate, and its file lock is advisory and held per process, so both isolates acquire it. A background isolate that opens the tasks box while the app is halfway through appending a record sees an incomplete final frame. Hive's crash recovery then truncates the file at that point.

We prevent this with a lease, a plain file that holds a UTC timestamp. The app writes it before opening its first box and rewrites it every 2 minutes. The background job reads it before doing anything else and exits when the stamp is younger than 10 minutes.

The lease expires by age because a process killed by the operating system never gets to release it. A lease that cannot be parsed counts as held, and so does one stamped in the future. Skipping one top-up costs a few late reminders, and a wrong guess could cost a person's tasks.

The background isolate also receives a narrower storage service. It may open a box that is already encrypted with the current key, and it refuses any box that would need migration or recovery.

Planning on a copy

The planner does not edit the stored schedule while it works. It copies the timeline into an in-memory source, plans there, and returns a report with a status for every task. Nothing has been written at that point.

The planner gateway runs the computation in a separate isolate. The request is encoded into primitive values and carries a schema version, currently 12, and a worker that receives any other version rejects the message. If the planning inputs change while the worker is running, the result is thrown away as stale and the app plans again, up to 3 times.

Hive has no transaction across boxes, so the commit is built by hand. Before writing, the timeline source records the previous value of every block it is about to touch. It writes the additions and then the deletions. If a write fails, it removes what was newly added and puts the old values back.

Storage sits behind small interfaces for tasks, the timeline, days and date overrides. Each interface has a Hive implementation and a memory implementation. The planner uses the memory one for its working copy, and our tests use it to run the engine with no disk.

One inventory of stores

Every Hive box that Flowo owns is listed in one registry, which has 24 entries today. Each entry declares the same fields.

• A data classification.
• Whether encryption is required.
• A retention rule.
• Whether the box is included in a data export.
• How the box is erased.
• A backup policy.
• The module that owns it.

The delete flow takes its list of boxes from this registry, and a test compares the two sets. A box that is registered and missing from erasure fails that test.

Erasure deletes every box file from disk and then deletes the storage key from the Keychain or Keystore. If any box fails to delete, the key is kept and the failure is reported. Tests cover both branches.

What the design suits and what it costs

This design suits data that belongs to one person and outputs that can be rebuilt from inputs. A Flowo schedule is computed from tasks and settings, and reminders are computed from the schedule. A damaged timeline can be planned again.

The first cost is that the plan exists on one device. The second is that every guarantee described here is code we wrote and have to test, and it runs on phones we cannot inspect.

A storage bug that we ship reaches data of which we hold no copy. That is the reason each mechanism above fails toward keeping what is already on disk. An unreadable lease is treated as held, and a failed write is rolled back.