forked from eva/focus-flow
167 lines
4.7 KiB
Markdown
167 lines
4.7 KiB
Markdown
<!-- 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.
|
|
|
|
The compact Today screen can toggle completion for currently rendered task
|
|
cards. Backlog widgets and quick-capture controls exist for tests and focused
|
|
composition paths, but the sidebar Backlog navigation remains out of scope for
|
|
this screen.
|
|
|
|
## 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
|
|
{
|
|
"LogLevel": "fine",
|
|
"LogfileLocation": "~/ADHD_Scheduler/debug/"
|
|
}
|
|
```
|
|
|
|
`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
|
|
|
|
- Sidebar navigation.
|
|
- Date navigation and calendar buttons.
|
|
- Compact/Normal toggle.
|
|
- Settings button.
|
|
- Show upcoming.
|
|
- Timeline card action icons.
|
|
- Modal Push, Move to Backlog, and Break up buttons.
|
|
|
|
## 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
|
|
|
|
- Wire visible Backlog navigation and quick-capture UI into the main shell.
|
|
- Wire functional Push, Move to Backlog, and Break up actions.
|
|
- Add real navigation/settings.
|
|
- Add Shield/Recovery only in a later scope.
|