Adati

A beautiful habit tracking app with timeline visualization

📥 Download

Current Version: 0.2.7+1

Pre-built releases are available on GitHub Releases.

Android

Option 1: Obtainium (Recommended) - Automatic Updates

Manual Setup: Install Obtainium from F-Droid or GitHub Releases, then:
- Open Obtainium and tap the "+" button
- Select "GitHub Releases" as the source
- Enter repository: Zyzto/Adati
Obtainium will automatically track new releases and notify you of updates

Option 2: Google Play Store WIP

Available on Google Play Store (when published)
Automatic updates through Play Store

Option 3: Direct Install (APK)

Download adati-VERSION-android.apk from GitHub Releases
Enable "Install from unknown sources" in your Android settings
Tap the downloaded APK file to install

Linux

AppImage (Recommended)

Download adati-VERSION-linux-x86_64.AppImage from GitHub Releases
Make it executable:
```
chmod +x adati-*-linux-x86_64.AppImage
```
Run it:
```
./adati-*-linux-x86_64.AppImage
```

Note: AppImage is portable and doesn't require installation. It includes all dependencies and works on most modern Linux distributions (requires GLIBC 2.31+, Ubuntu 20.04+).

Windows

ZIP Package (Recommended)

Download adati-VERSION-windows-x64.zip from GitHub Releases
Extract the ZIP file to a folder (e.g., C:\Program Files\Adati\)
Run adati.exe from the extracted folder

Standalone EXE

Download adati-VERSION-windows-x64.exe (requires DLLs from the ZIP package to run properly)
Note: The ZIP package is recommended as it includes all required dependencies

macOS & iOS

Build instructions are available in the Building for Production section. Pre-built releases for macOS and iOS may be available in future releases.

Web

Web builds are available for development. See the Building for Production section for build instructions.

📱 About

Adati is a modern, feature-rich habit tracking application built with Flutter. It helps you build and maintain good habits through visual tracking, streak monitoring, and an intuitive timeline interface. The app supports multiple languages, themes, and runs seamlessly across all major platforms.

✨ Features

Core Functionality

Habit Management: Create, edit, and delete habits with custom names, descriptions, colors, and icons
Multiple Tracking Types:
- Completed: Simple yes/no tracking (e.g., "Meditated today")
- Measurable: Track numeric values with units (e.g., "Walked 5 km", "Drank 8 glasses of water")
- Occurrences: Track multiple occurrences per day (e.g., "Exercised: Morning, Evening")
Good & Bad Habits: Track both positive habits you want to build and negative habits you want to break
- Configurable Bad Habit Logic: Choose how bad habits affect your timeline completion (see Settings)
Goal Setting: Set daily, weekly, or monthly goals for measurable habits
Streak Tracking: Automatic calculation and display of current and longest streaks (separate for good/bad habits)
Tag System: Organize habits with custom tags for better categorization
Timeline Visualization: Beautiful calendar grid showing your completion history at a glance
Day Details: View and edit all entries for a specific date
Habit Details: Comprehensive view of each habit with calendar modal, statistics, and management options
Reminders: Set up daily reminders for your habits
Data Import/Export: Import and export your data in JSON or CSV format

User Experience

Material Design 3: Modern, beautiful UI following Material Design principles
Dark & Light Themes: System-aware theme with manual override option
Multi-language Support: Currently supports English and Arabic (RTL support included)
Smooth Animations: Polished transitions and loading states
Responsive Layout: Optimized for phones, tablets, and desktop
Skeleton Loading: Better perceived performance with skeleton screens

Technical Features

Offline-First: All data stored locally using SQLite
Database Migrations: Seamless schema updates without data loss
Notifications: Local notifications support (with permission handling)
Preferences: Persistent user settings and preferences
Timezone Support: Accurate date handling across timezones
Logging: Comprehensive logging for debugging and error tracking
Desktop Mouse Support: Custom scroll behavior enables mouse drag gestures on desktop platforms (Linux, Windows, macOS) for PageView and other scrollable widgets

Platform Support

✅ Android
✅ iOS
✅ Linux
✅ macOS
✅ Windows
✅ Web

📖 Usage

Creating a Habit

Navigate to the Timeline or Habits tab
Tap the "+" button or "New Habit" option
Enter habit name, optional description, choose a color and icon
Select habit type (Good or Bad habit)
Choose tracking type:
- Completed: Simple completion tracking
- Measurable: Set unit (minutes, km, glasses, etc.) and goal value
- Occurrences: Define occurrence names (e.g., "Morning", "Evening")
Set goal period (daily, weekly, or monthly) for measurable habits
Optionally enable reminders and set reminder time
Add tags to organize your habits
Save to start tracking

Tracking Habits

Completed Habits

Tap on a day in the calendar grid to mark habits as complete/incomplete
Add optional notes to any entry

Measurable Habits

Tap on a day to enter a numeric value
The app automatically marks as complete when goal is reached
Track values like: minutes exercised, km walked, glasses of water, pages read, etc.

Occurrences Habits

Tap on a day to select which occurrences happened
Track multiple occurrences per day (e.g., "Exercised in the morning and evening")

Viewing Timeline

The main timeline shows a calendar grid with color-coded completion status
Completion Calculation: The timeline uses a weighted completion system that respects your bad habit logic mode setting:
- Negative Mode: (good completed - bad marked) / total good habits. If only bad habits exist, starts at 100% and decreases by bad marked / total bad habits. Completion rate is clamped to 0-100%.
- Positive Mode: (good completed + bad not marked) / total habits. Completion rate is clamped to 0-100%.
Tap any day to view and edit all entries for that date
Statistics at the top show your overall progress
Filter habits by tags or search by name

Habit Details

Tap on any habit card to see:
- Calendar view with completion history
- Current and longest streaks
- Statistics and progress
- Edit or delete the habit

Data Management

Export Data: Export all data, habits only, or settings only (JSON or CSV format)
Import Data: Import data from exported files (supports JSON and CSV)
Auto-Backup: Automatic daily backups with configurable retention (see Settings)
Manual Backup: Create backups on-demand from Settings
Backup Restoration: Restore from previous backups
Database Statistics: View database size and record counts
Reset Habits: Option to reset all habits and tracking data

Settings

Language: Switch between English and Arabic (with RTL support)
Theme: Choose Light, Dark, or System theme
Bad Habit Logic Mode: Choose how bad habits affect timeline completion
- Negative Mode (Default): Marking a bad habit counts as negative, reducing completion rate. Good habits add +1, bad habits subtract -1 when marked. If you only have bad habits, the timeline starts at 100% and decreases when you mark them.
- Positive Mode: Not marking a bad habit counts as positive. Good habits add +1 when completed, bad habits add +1 when NOT marked. This is the traditional behavior where avoiding bad habits is rewarded.
Data & Export: Import/export your data
Advanced: Database statistics and reset options
All preferences are saved automatically

🖥️ Desktop-Specific Features

Mouse Drag Support

The app includes a custom scroll behavior (AppScrollBehavior) that enables mouse drag gestures on desktop platforms. This allows users to:

Click and hold to drag PageView slides (e.g., in the onboarding screen)
Use mouse drag for all scrollable widgets throughout the app
Support trackpad gestures

Implementation: The custom behavior extends MaterialScrollBehavior and includes PointerDeviceKind.mouse and PointerDeviceKind.trackpad in the allowed drag devices. This is applied globally via MaterialApp.scrollBehavior.

Why it's needed: Flutter's default MaterialScrollBehavior only allows drag gestures for touch devices, stylus, and inverted stylus. Without this custom behavior, users on desktop platforms cannot drag scrollable widgets with a mouse.

🚀 Getting Started

Prerequisites

Flutter SDK (3.9.2 or higher)
Dart SDK (3.9.2 or higher)
For platform-specific builds:
- Android: Android Studio with Android SDK
- iOS: Xcode (macOS only)
- Linux: CMake and required development libraries
- Windows: Visual Studio with C++ tools
- Web: Chrome (for development)

Installation

Clone the repository

git clone https://github.com/Zyzto/Adati.git
cd Adati

Install dependencies
```
flutter pub get
```

Generate code (for Drift database)

flutter pub run build_runner build --delete-conflicting-outputs

Run the app
```
flutter run
```

Building for Production

Android

flutter build apk --release --no-tree-shake-icons
# or for app bundle
flutter build appbundle --release --no-tree-shake-icons

iOS

flutter build ios --release

Linux

flutter build linux --release --no-tree-shake-icons

macOS

flutter build macos --release

Windows

flutter build windows --release --no-tree-shake-icons

Web

flutter build web --release

Automated Releases

The project includes GitHub Actions workflows for automated builds and releases:

Automatic Release: Push a tag (e.g., v0.1.0) to automatically build and release for Android, Linux, and Windows
Manual Trigger: Use the "Run workflow" button in GitHub Actions to manually trigger builds
Artifacts: Built apps are automatically uploaded to GitHub Releases

See .github/workflows/release-beta.yml for the complete workflow configuration.

🏗️ Project Structure

lib/
├── main.dart                 # App entry point and initialization
├── app.dart                  # Main app widget and routing
│
├── core/                     # Core functionality
│   ├── database/            # Database models, DAOs, and connection
│   │   ├── models/          # Drift table definitions
│   │   ├── daos/            # Data Access Objects
│   │   └── app_database.dart
│   ├── services/            # App-wide services
│   │   ├── notification_service.dart
│   │   ├── preferences_service.dart
│   │   ├── logging_service.dart
│   │   ├── reminder_service.dart
│   │   ├── export_service.dart
│   │   ├── import_service.dart
│   │   ├── auto_backup_service.dart
│   │   └── demo_data_service.dart
│   ├── theme/               # App theming
│   │   ├── app_theme.dart
│   │   └── app_scroll_behavior.dart  # Custom scroll behavior for desktop mouse support
│   └── utils/               # Utility functions
│
└── features/                 # Feature modules
    ├── habits/              # Habit management
    │   ├── habit_repository.dart  # Data layer (repository)
    │   ├── pages/           # Page widgets
    │   ├── providers/       # Riverpod providers
    │   └── widgets/         # Reusable widgets
    ├── timeline/            # Timeline visualization
    │   ├── pages/           # Timeline pages
    │   └── widgets/         # Timeline widgets
    ├── settings/            # Settings page
    │   ├── pages/           # Settings pages
    │   └── providers/       # Settings providers
    └── onboarding/          # Onboarding flow
        ├── pages/           # Onboarding pages
        └── widgets/         # Onboarding widgets

📚 Documentation

SERVICES.md - Comprehensive documentation for all services in the codebase, including usage examples and API reference
SECURITY.md - Security guidelines, best practices, and how to handle sensitive information

🛠️ Technology Stack

Framework: Flutter
Language: Dart
State Management: Riverpod
Navigation: GoRouter
Database: Drift (SQLite ORM)
Localization: EasyLocalization
Notifications: flutter_local_notifications
UI Animations: animations
Loading States: skeletonizer
File Handling: file_picker (for import/export)

🧪 Development

Debug Menu

When running the app in debug mode (flutter run or debug builds), a debug menu button (🐛 bug icon) appears next to the settings button in the main timeline page. This menu provides quick access to debugging tools:

Available Debug Tools

Log All Preferences - Logs all stored preferences (keys and values) to the console
Log All Habits - Logs detailed information about all habits (ID, name, type, color, icon)
Log All Tags - Logs all tag data (ID, name, color)
Log All Entries - Logs all tracking entries (habitId, date, completed status, notes)
Log All Streaks - Logs all streak data (combined, good, bad, current, longest streaks)
Database Path - Shows the database file location in a dialog (useful for manual database inspection)
Force Refresh - Invalidates all providers to force a refresh of the UI
Performance Indicator - Toggles a real-time FPS counter overlay in the top-right corner
Test Reminder (Immediate) - Test the reminder system with an immediate notification
Test Notification (30s) - Schedule a test notification in 30 seconds
Reschedule All Reminders - Manually reschedule all habit reminders

Using the Debug Menu

Run the app in debug mode: flutter run
Navigate to the main timeline page
Look for the bug icon (🐛) in the app bar next to the settings button
Tap the bug icon to open the debug menu
Select any option to execute the debug action

Note: The debug menu is only available in debug mode and will not appear in release builds. All logs are written using the app's logging system and can be viewed in the console or exported via the Settings → Advanced → Logs section.

Running Tests

flutter test

Code Generation

When you modify database models or DAOs, regenerate the code:

flutter pub run build_runner build --delete-conflicting-outputs

Generating Icons

After updating assets/icon.png, regenerate platform-specific icons:

flutter pub run flutter_launcher_icons

Linting

The project uses flutter_lints for code quality:

flutter analyze

CI/CD

The project uses GitHub Actions for automated builds and releases:

Workflow files:
- .github/workflows/release-beta.yml - Beta releases (triggers on v* tags)
- .github/workflows/release-production.yml - Production releases
- .github/workflows/build.yml - Build workflow
Triggers on version tags (v*) or manual dispatch
Builds for Android (APK/AAB), Linux (AppImage), and Windows (ZIP)
Automatically creates GitHub releases with artifacts

📝 Database Schema

The app uses SQLite with the following main tables:

habits: Stores habit information including:
- Basic info: name, description, color, icon
- Type: good (0) or bad (1) habit
- Tracking type: completed, measurable, or occurrences
- Measurable config: unit, goal value, goal period (daily/weekly/monthly)
- Occurrences config: JSON array of occurrence names
- Reminders: enabled flag and reminder time
tracking_entries: Daily tracking records with:
- Completion status (for completed habits)
- Numeric value (for measurable habits)
- Occurrence data as JSON array (for occurrences habits)
- Optional notes
streaks: Calculated streak data for each habit:
- Combined streak (main display)
- Good streak (for good habits)
- Bad streak (for bad habits - days not doing the bad habit)
- Longest streaks for each type
tags: Habit tags for organization (name, color, icon)
habit_tags: Junction table linking habits to tags (many-to-many relationship)

Entity Relationship Diagram

erDiagram
    HABITS ||--o{ TRACKING_ENTRIES : "has"
    HABITS ||--|| STREAKS : "has"
    HABITS ||--o{ HABIT_TAGS : "has"
    TAGS ||--o{ HABIT_TAGS : "has"
    
    HABITS {
        int id PK
        string name
        string description
        int color
        string icon
        int habitType "0=good, 1=bad"
        string trackingType "completed, measurable, occurrences"
        string unit "for measurable tracking"
        real goalValue "for measurable tracking"
        string goalPeriod "daily, weekly, monthly"
        string occurrenceNames "JSON array for occurrences tracking"
        bool reminderEnabled
        string reminderTime "JSON format"
        datetime createdAt
        datetime updatedAt
    }
    
    TRACKING_ENTRIES {
        int habitId PK,FK
        datetime date PK
        bool completed
        real value "for measurable tracking"
        string occurrenceData "JSON array for occurrences tracking"
        string notes
    }
    
    STREAKS {
        int id PK
        int habitId FK "unique"
        int combinedStreak "main streak shown on main page"
        int combinedLongestStreak
        int goodStreak "for good habits"
        int goodLongestStreak
        int badStreak "for bad habits (not doing bad habit)"
        int badLongestStreak
        int currentStreak "backward compatibility"
        int longestStreak "backward compatibility"
        datetime lastUpdated
    }
    
    TAGS {
        int id PK
        string name
        int color
        string icon
        datetime createdAt
    }
    
    HABIT_TAGS {
        int habitId PK,FK
        int tagId PK,FK
    }

🌍 Localization

Currently supported languages:

English (en)
Arabic (ar) - with RTL support

To add a new language:

Add translation files in assets/translations/
Update main.dart to include the new locale
Add language option in settings

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📄 License

This project is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License - see the LICENSE file for details.

CC BY-NC-SA 4.0 means:

✅ You can share and adapt the code
✅ You must give appropriate credit
❌ You cannot use it for commercial purposes
✅ You must share adaptations under the same license

👤 Author

Zyzto

GitHub: @Zyzto

🙏 Acknowledgments

Built with Flutter
Icons and UI elements follow Material Design
Database powered by Drift

📞 Support

If you encounter any issues or have questions, please open an issue on GitHub.

Made with ❤️ using Flutter

Name		Name	Last commit message	Last commit date
Latest commit History 206 Commits
.cursor		.cursor
.github/workflows		.github/workflows
.vscode		.vscode
android		android
assets		assets
integration_test		integration_test
ios		ios
lib		lib
linux		linux
macos		macos
packages		packages
test		test
web		web
windows		windows
.actrc		.actrc
.cursorrules		.cursorrules
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
.metadata		.metadata
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
SERVICES.md		SERVICES.md
analysis_options.yaml		analysis_options.yaml
devtools_options.yaml		devtools_options.yaml
docker-compose.yml		docker-compose.yml
pubspec.lock		pubspec.lock
pubspec.yaml		pubspec.yaml

License

Zyzto/Adati

Folders and files

Latest commit

History

Repository files navigation

Adati

📥 Download

Android

Linux

Windows

macOS & iOS

Web

📱 About

✨ Features

Core Functionality

User Experience

Technical Features

Platform Support

📖 Usage

Creating a Habit

Tracking Habits

Completed Habits

Measurable Habits

Occurrences Habits

Viewing Timeline

Habit Details

Data Management

Settings

🖥️ Desktop-Specific Features

Mouse Drag Support

🚀 Getting Started

Prerequisites

Installation

Building for Production

Android

iOS

Linux

macOS

Windows

Web

Automated Releases

🏗️ Project Structure

📚 Documentation

🛠️ Technology Stack

🧪 Development

Debug Menu

Available Debug Tools

Using the Debug Menu

Running Tests

Code Generation

Generating Icons

Linting

CI/CD

📝 Database Schema

Entity Relationship Diagram

🌍 Localization

🤝 Contributing

📄 License

👤 Author

🙏 Acknowledgments

📞 Support

About

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages