focus-flow/apps/focus_flow_flutter/README.md

<!-- SPDX-FileCopyrightText: 2026 FocusFlow contributors -->
<!-- SPDX-License-Identifier: AGPL-3.0-only -->

# FocusFlow Flutter

Flutter desktop app target for the FocusFlow UI work.

## Current Scope

The app launches into the compact Today timeline. Normal startup now opens an
on-disk SQLite database and bootstraps owner settings plus the default Home
project when they are missing.

cards. The sidebar Backlog navigation opens the board surface backed by public
scheduler application APIs. Backlog supports the four board buckets, search,
filters, sort/group controls, summary data, the right-anchored detail drawer,
task creation, scheduling, Break Up child-task creation, Someday tagging, and
non-destructive archive/remove from active Backlog.

Backlog notes, project edits, and freeform tag edits intentionally remain
read-only or non-mutating placeholders until the deferred metadata migration and
application command are implemented.

The sidebar Settings item and top bar Settings button both open a dialog bound
to persisted `OwnerSettings`/`BacklogStalenessSettings`, covering time zone, day
window, compact-mode toggle, and backlog staleness thresholds.

## Runtime Data

Normal runtime uses `lib/app/persistent_scheduler_composition.dart`, which reads
`SCHEDULER_SQLITE_PATH` from a Dart define. If no define is present, it uses the
local dev convention:

```text
~/ADHD_Scheduler/scheduler.sqlite
```

Static demo data still lives in `lib/app/demo_scheduler_composition.dart`, but
it is for deterministic widget/visual tests and explicit demo composition only.
It is not inserted during normal startup.

Widgets consume `TodayScreenData` from `lib/models/today_screen_models.dart`.
Scheduler core remains the source of truth for task state and Today ordering.

## Runtime Config

The app optionally reads a JSON config file from:

```text
~/ADHD_Scheduler/config.json
```

Override the config path with:

```sh
flutter run -d linux --dart-define=FOCUS_FLOW_CONFIG_PATH=/tmp/focus_flow_config.json
```

Supported optional keys:

```json
{
  "Timezone": "UTC",
  "LogLevel": "fine",
  "LogfileLocation": "~/ADHD_Scheduler/debug/"
}
```

`Timezone` accepts a three-letter time-zone code without regard to character
case, such as `UTC`, `GMT`, `PST`, or `PDT`. Common daylight-saving pairs such
as `PST`/`PDT`, `MST`/`MDT`, `CST`/`CDT`, and `EST`/`EDT` are resolved once when
the config loads, so either seasonal abbreviation uses the correct current
offset for that zone during the app session. The setting is an app/UI reference
only: it controls wall-clock timeline display, selected-day startup, and
time-relative actions such as pushing a task to the next slot or tomorrow. Task
instants and all persistence data remain stored as UTC/GMT values.

`LogLevel` accepts `finest`, `finer`, `fine`, `debug`, `info`, `warn`, or
`error`.
`LogfileLocation` is treated as a directory, and the app writes
`focus_flow.log` inside it. If either key is absent or invalid, file logging is
not enabled and the app ignores that setting.

Verbose log levels can include automatic caller information without requiring
each call site to pass it manually. `finest` includes caller frames for every
written message. `fine`, `finer`, and `finest` include caller frames for
warnings and errors. This caller lookup is skipped when the configured level
does not require it.

For expensive debug/detail messages, pass a lazy closure so work is skipped when
the configured level would not write the log:

```dart
logger.debug(() => 'state=${expensiveStateDump()}');
```

## Package Boundary

Allowed app imports include public scheduler APIs such as:

```dart
import 'package:scheduler_core/scheduler_core.dart';
```

The persistent composition root may import
`package:scheduler_persistence_sqlite/sqlite.dart` and `dart:io` for runtime
path resolution. Widgets/controllers must not import scheduler `src/` files,
Drift, SQLite adapters, desktop notification implementations, backup/export
packages, or direct OS APIs. `test/forbidden_imports_test.dart` enforces that
boundary.

## Intentionally No-op

- Compact/Normal toggle (Settings persists the flag, but the Today pipeline
  does not yet read it; see Forgejo issue #11).
- Show upcoming.
- Timeline card Schedule and Protect time icons.
- Backlog drawer project selector, add-tag control, and View day shortcut.

## Persistence Proof

Current focused tests prove:

- first run opens an empty SQLite file without seeded task rows,
- quick capture writes a backlog task,
- scheduling writes planned Today placement,
- done and not-done state persists,
- closing and reopening the same SQLite file reloads the task state.

Manual verification:

```sh
scripts/bootstrap_dev.sh
scripts/dev.sh --sqlite /tmp/focus_flow_persistence_plan_1.sqlite
```

Use the same `--sqlite` path after closing the app to confirm state persists. To
reset local dev data, close the app and delete the chosen `.sqlite` file. This is
only a dev reset; backup/restore UI remains out of scope.

## Commands

Run `scripts/bootstrap_dev.sh` once from the repository root to create the
default SQLite directory.

Run the desktop UI from this directory:

```sh
flutter pub get
flutter run -d linux
```

Replace `linux` with `macos` or `windows` on those hosts. The default database
path is `~/ADHD_Scheduler/scheduler.sqlite`. If Flutter reports that the
desktop project is not configured for that platform, generate the missing
runner from this directory:

```sh
flutter create --platforms=linux .
```

Use `--platforms=macos` or `--platforms=windows` for those hosts.

Use a disposable dev database when needed:

```sh
flutter run -d linux --dart-define=SCHEDULER_SQLITE_PATH=/tmp/focus_flow_dev.sqlite
```

Check the app from this directory:

```sh
flutter analyze
flutter test
```

Run these from `apps/focus_flow_flutter/`.

## Next Plans

- Give the Compact/Normal toggle real backing state (the live Today pipeline
  has no compact-mode concept yet; see Forgejo issue #11).
- Add migration-backed notes, project edits, and freeform tags for Backlog
  metadata.
- Add Shield/Recovery only in a later scope.