ADHD Scheduler Workspace

SQLite-first Dart workspace for the ADHD scheduler backend, persistence adapters, notifications, exports, backups, integration tests, and CI scripts.

Workspace Layout

• documentation/ contains Codex plans, human-facing product documentation, archived plans, and documentation handoffs.
• generted_files/ is the single root for project-controlled generated API docs, coverage, release outputs, packaged builds, and test artifacts.
• archives/ contains manually retained files that are no longer relevant to the active application and is excluded from builds.
• apps/, packages/, installer/, and scripts/ contain maintained source and validation code. Workspace-level tests live in packages/scheduler_integration_tests/test/.

The generted_files spelling is intentional and is part of the repository path contract. Flutter and Dart may still create toolchain-required .dart_tool/ and app-local build/ caches; those are ignored and are not release outputs.

Local Workflow

Set up the workspace and local SQLite path:

scripts/bootstrap_dev.sh

On Windows, use the PowerShell wrapper:

.\scripts\bootstrap_dev.ps1

Run the local app during development:

scripts/dev.sh

On Windows:

.\scripts\dev.ps1

Run the full local quality gate:

scripts/test.sh

The test gate runs analyzer, tests with coverage, combines LCOV output, and fails below 80% package lib/ coverage. It discovers workspace tests from packages/scheduler_integration_tests/test/.

Build a local desktop bundle with the host toolchain:

scripts/package_release.sh --platform current --artifact local-bundle --output generted_files/build/releases

On Windows:

.\scripts\package_release.ps1 -Platform windows -Artifact local-bundle -Output generted_files\build\releases

Equivalent Dart entry points:

dart run scripts/dev.dart
dart run scripts/build.dart --platform current --artifact local-bundle --output generted_files/build/releases

The dev script prints the SQLite path, starts dart run build_runner watch, and launches Flutter desktop with SCHEDULER_SQLITE_PATH passed as a dart define. Normal Flutter startup uses that SQLite file for scheduler state rather than inserting seeded demo tasks.

Prerequisites:

• Dart stable SDK
• Flutter stable SDK with desktop support enabled
• platform desktop toolchain: Xcode for macOS, Visual Studio Build Tools for Windows, and Linux desktop build dependencies for Linux

For Windows setup and troubleshooting details, see apps/focus_flow_flutter/windows/README.md.

Optional flags:

dart run scripts/dev.dart --device linux --sqlite /tmp/scheduler.sqlite

Earthly Workflow

Earthly is the supported containerized build path going forward. It builds a Linux desktop Flutter bundle and exports a runnable application under generted_files/builds/.

Install prerequisites on the host:

• Earthly
• Docker or another Earthly-compatible container runtime

Set up the Earthly build image:

earthly +setup

Copy code and resolve Dart/Flutter dependencies inside Earthly:

earthly +code

Run all style and metadata checks:

earthly +lint

Run all Dart and Flutter tests:

earthly +test

Build and package the runnable Linux desktop app:

earthly +build

Run lint, all tests, build, and package in one command:

earthly +all

Smoke-run the Earthly-built Linux desktop app under a virtual display:

earthly +run

Earthly outputs:

generted_files/builds/focus_flow_linux_x64/
generted_files/builds/focus_flow_linux_x64.zip

Useful focused lint targets:

earthly +format
earthly +dart-analyze
earthly +flutter-analyze
earthly +reuse
earthly +docs
earthly +pre-commit

Flutter UI

The provisional UI app lives outside the root Dart workspace at apps/focus_flow_flutter so backend package gates can stay Dart-only while the Flutter foundation settles.

From the repository root, start the desktop UI with the default local SQLite database:

scripts/bootstrap_dev.sh
cd apps/focus_flow_flutter
flutter pub get
flutter run -d linux

Replace linux with macos or windows on those hosts. Use flutter devices to list available device IDs. The desktop runners are committed; do not regenerate them during normal development.

For a disposable dev database, pass an explicit SQLite path:

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

The default database path is ~/ADHD_Scheduler/scheduler.sqlite. To reset local UI data, close the app and delete the SQLite file you used.

Windows users can use the dedicated PowerShell workflow in apps/focus_flow_flutter/windows/README.md instead of the Bash examples above.

cd apps/focus_flow_flutter
flutter analyze
flutter test

Local Installers

./installer/linux/install.sh
./installer/linux/recompile.sh
./installer/linux/uninstall.sh

macOS and Windows provide matching per-user installer entry points:

./installer/mac/install.sh
./installer/mac/uninstall.sh

.\installer\windows\install.ps1
.\installer\windows\uninstall.ps1

Ordinary uninstall preserves ~/ADHD_Scheduler or %USERPROFILE%\ADHD_Scheduler. Purging that user data requires both explicit purge flags. See installer/README.md for paths, overrides, and dry-run commands.

Build Artifacts

dart run scripts/build.dart --platform current --artifact local-bundle --output generted_files/build/releases

The local-bundle artifact is the supported installer input:

• macOS: Flutter desktop support and Xcode; produces generted_files/build/releases/macos/FocusFlow.app
• Windows: Flutter desktop support and Visual Studio Build Tools; produces a release bundle folder under generted_files/build/releases/windows/bundle
• Linux: Flutter desktop support and Linux desktop build dependencies; produces a raw release bundle under generted_files/build/releases/linux/bundle

Public distribution formats such as MSIX, signed DMG/PKG, AppImage, DEB/RPM, Flatpak, Snap, and app-store packages are deferred until separate packaging and signing work exists.