Life Hud

Life Hud is an offline-first task companion for Windows, macOS, and Android. It keeps your daily checklist close at hand with a translucent desktop overlay, rich recurrence rules, and a file-backed storage model that never requires the cloud. The project is intentionally open so contributors can help shape the roadmap toward future sync services, iOS support, and production-grade installers.

Highlights

• Cross-platform Flutter app targeting desktop and mobile with a shared Riverpod-powered state layer.
• Offline-first persistence using human-readable JSON files stored under a per-user .lifehud directory (or app-private storage on Android).
• Cron-inspired scheduling that offers guided presets for everyday users while retaining raw expressions for power users.
• Always-on overlay that hovers above other windows, becomes interactive after a configurable dwell time, and mirrors updates from the main app in real time.
• History & auditing with device-attributed metadata for every occurrence, easing diagnostics once multi-device sync arrives.

Supported Platforms

• Primary: Windows 10+, macOS 13 Ventura+, Android 12+
• Planned: iOS 16+ (post-desktop stabilization)

See the requirements document for scope details and distribution plans.

Architecture Overview

• Flutter 3.x with Dart governs the shared UI and business logic.
• Riverpod provides feature-scoped state management with immutable models.
• A file-backed repository stores tasks beneath the platform-specific data root (~/.lifehud, %USERPROFILE%\.lifehud, or Android’s app files directory) using the schemas described in json-schemas.md.
• Desktop overlays are orchestrated by native window controllers described in overlay-spec.md and bridged via platform channels.
• The curated toolset, CI targets, and packaging strategy are documented in tech-stack.md.

Offline File Layout

.lifehud/
├─ device-info.json
├─ task-config.json
└─ tasks/
   └─ <task-id>/
      ├─ active.json
      └─ <year>-<month>/
         └─ <day>-<hour>-<uuid>.json

Each write is performed via temporary files and atomic renames to guard against corruption. Audit fields (generated/updated timestamps and device IDs) are captured for every record. Dive into json-schemas.md for field-by-field definitions and migration guidance.

Desktop Overlay

• Runs in its own Flutter engine and native window so it can sit above other apps.
• Mirrors the main app’s state instantly—completing a task in either surface updates the other.
• Becomes fully opaque whenever the main window is in focus (or when hovered for a configurable delay when unfocused).
• Displays three sections: tasks completed today, tasks due today, and up to five upcoming tasks (if space permits).

Implementation notes, platform behaviors, and future enhancements live in overlay-spec.md.

Project Documentation

• requirements.md — product scope, platform roadmap, and UX constraints.
• tech-stack.md — framework choices, tooling, and build/distribution notes.
• json-schemas.md — canonical definitions for every JSON document on disk.
• overlay-spec.md — native window architecture and UX expectations.
• AGENTS.md — contributor guidelines, testing expectations, and commit conventions.

Getting Started

1. Install prerequisites

   • Flutter 3.x SDK (desktop + mobile toolchains configured)
   • Xcode (macOS) or Visual Studio Build Tools (Windows) for desktop builds
   • Android SDK/NDK for mobile builds

2. Clone & bootstrap

   git clone https://github.com/<your-org>/lifehud.git
   cd lifehud
   flutter pub get

3. Run the app

   flutter run -d macos     # or windows / android / ios (once enabled)

4. Launch the overlay

   • The overlay engine starts automatically when the desktop app boots. Hover to activate it or bring the main window into focus to force opacity.

Development Workflow

• Format code: dart format lib test integration_test
• Run unit/widget tests: flutter test
• Execute integration tests: flutter test integration_test
• When updating storage or recurrence logic, add/extend tests under test/features/... before submitting a PR.
• Follow the contribution playbook in AGENTS.md for branching strategy and review expectations.

Directory Layout

• lib/ — Flutter source organized by feature (features/tasks, features/overlay, core/storage, etc.).
• test/, integration_test/ — automated coverage mirroring the production structure.
• Platform directories (macos/, windows/, android/) — host runners and native plugins.
• Documentation and licenses at the repository root.

Contributing

Contributions are welcome! Read AGENTS.md for repository etiquette, coding style, and testing requirements before opening a pull request.

License

Life Hud is released under the BSD 3-Clause License. See LICENSE for details.