🎯 Focus Quest

A dopamine-driven productivity planner designed for users with ADHD

Features • Installation • Documentation • Contributing

---

📝 About

Focus Quest is a dopamine-driven productivity planner designed specifically for users with ADHD. It focuses on overcoming executive dysfunction, time blindness, and task initiation paralysis through gamification and low-friction interactions.

🎯 Core Principles

• Anti-Shame Design: No guilt trips, just progress
• Low Friction: Create tasks in seconds, not minutes
• Gamification: Earn XP, level up, unlock achievements
• Dopamine Optimization: Visual feedback, streaks, and instant gratification
• Local-First & Cloud Sync: Data lives on your device, with optional cloud backup

✨ Key Features

• Quest Management: Anti-shame, low-friction task creation with categories and energy levels
• Sub-Quests: 5-minute micro-tasks to combat overwhelm
• Focus Mode: Pomodoro-style timer with strict mode, pause tracking, and state persistence
• Cloud Sync: Secure Google Sign-In with cross-device synchronization (Firestore)
• Progress System: XP, leveling, streaks, and achievements
• Smart Notifications: Persistent timer alerts and pause reminders
• Personalized Experience: Dynamic time-based greetings and user display name
• Theme Support: Light/Dark mode with persistent preference
• Multi-Platform: Fully responsive design for Android, iOS, macOS, Linux, Windows, and Web

📖 See detailed feature list →

📐 Design & Architecture

The project follows a Local-First with Cloud Sync architecture. The local Sembast database acts as the single source of truth for the UI to ensure instant reactivity, while a background SyncService handles data synchronization with Cloud Firestore.

For a detailed breakdown of the system architecture, module breakdown, and technical stack, please refer to:

• Features Overview
• High-Level Design (HLD) Plan
• Theme System Documentation

📁 Folder Structure

lib/
├── core/
│   ├── theme/
│   ├── constants/
│   ├── utils/
│   └── widgets/
├── features/
│   ├── auth/         # Login, Sign up, Auth State
│   ├── tasks/        # Quests, SubQuests, Brain Dump
│   ├── journal/      # Daily Reflection, Mood
│   ├── timer/        # Focus Mode, Pomodoro, Session Tracking
│   ├── profile/      # XP, Level, Stats, Heatmap
│   └── settings/     # Sync Controller, Theme Toggle
├── l10n/             # Localization ARB files
├── models/           # Quest, FocusSession, JournalEntry, UserProgress
├── providers/        # State Management
└── services/         # Sembast, Firestore, Notifications, Audio/Haptics

---

🚀 Installation

Prerequisites

• Flutter SDK (3.0 or higher)
• Dart SDK (3.0 or higher)
• Platform-specific requirements:
  • Android: Android Studio, SDK 21+
  • iOS: Xcode 13+, macOS
  • Web: Chrome (for development)
  • Desktop: Platform-specific toolchains

Setup

1. Clone the repository

   git clone https://github.com/yourusername/focus_quest.git
   cd focus_quest

2. Install dependencies

   flutter pub get

3. Generate localization files

   flutter gen-l10n

4. Run the app

   # For development on your default device
   flutter run
   
   # For specific platforms
   flutter run -d chrome          # Web
   flutter run -d macos           # macOS
   flutter run -d android         # Android
   flutter run -d ios             # iOS

Building for Production

# Android APK
flutter build apk --release

# Android App Bundle
flutter build appbundle --release

# iOS
flutter build ios --release

# macOS
flutter build macos --release

# Web
flutter build web --release

# Windows
flutter build windows --release

# Linux
flutter build linux --release

---

📖 Documentation

• Features Overview - Detailed feature breakdown
• High-Level Design (HLD) - System architecture and technical stack
• Theme System - Theming implementation guide
• Contributing Guidelines - How to contribute
• Firebase Configuration - Firebase setup (optional)

---

🌍 Internationalization (i18n)

This project uses Flutter's official localization system with ARB (Application Resource Bundle) files.

Initial Setup (Already Completed)

The following setup has been completed for this project:

1. Dependencies Added to pubspec.yaml

dependencies:
  flutter_localizations:
    sdk: flutter
  intl: ^0.20.2

2. Enable Code Generation in pubspec.yaml

flutter:
  generate: true

3. Configuration File l10n.yaml

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart

4. MaterialApp Configuration in main.dart

import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:focus_quest/l10n/app_localizations.dart';

MaterialApp(
  localizationsDelegates: const [
    AppLocalizations.delegate,
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
  ],
  supportedLocales: const [
    Locale('en'),
    Locale('es'),
  ],
  // ...
)

---

Adding New Translations

Follow these steps to add new translatable strings:

Step 1: Add the String to English ARB (Template)

Edit lib/l10n/app_en.arb:

{
  "@@locale": "en",
  "appTitle": "FocusQuest",
  "@appTitle": {
    "description": "The application title"
  },
  "welcomeMessage": "Welcome to FocusQuest!",
  "@welcomeMessage": {
    "description": "Welcome message shown on the home screen"
  }
}

Note: The @<key> entries are metadata (description, placeholders) and are only needed in the template file (app_en.arb).

Step 2: Add Translations to Other Locales

Edit lib/l10n/app_es.arb:

{
  "@@locale": "es",
  "appTitle": "FocusQuest",
  "welcomeMessage": "¡Bienvenido a FocusQuest!"
}

Step 3: Generate Localization Code

Run Flutter build or generate command:

flutter gen-l10n

Or simply run your app — Flutter auto-generates on build:

flutter run

The generated files will appear in lib/l10n/:

• app_localizations.dart
• app_localizations_en.dart
• app_localizations_es.dart

Step 4: Use the Localized String in Code

import 'package:focus_quest/l10n/app_localizations.dart';

// In your widget:
Text(AppLocalizations.of(context)!.welcomeMessage)

---

Using Placeholders in Translations

For dynamic values, use placeholders:

ARB File (app_en.arb)

{
  "questsCompleted": "You completed {count} quests today!",
  "@questsCompleted": {
    "description": "Message showing number of completed quests",
    "placeholders": {
      "count": {
        "type": "int",
        "example": "5"
      }
    }
  }
}

Spanish Translation (app_es.arb)

{
  "questsCompleted": "¡Completaste {count} misiones hoy!"
}

Usage in Code

Text(AppLocalizations.of(context)!.questsCompleted(5))

---

Adding a New Language

Step 1: Create a New ARB File

Create lib/l10n/app_<locale>.arb (e.g., app_fr.arb for French):

{
  "@@locale": "fr",
  "appTitle": "FocusQuest",
  "welcomeMessage": "Bienvenue sur FocusQuest!"
}

Step 2: Add the Locale to supportedLocales

Update main.dart:

supportedLocales: const [
  Locale('en'),
  Locale('es'),
  Locale('fr'),  // Add new locale
],

Step 3: Regenerate Localization Files

flutter gen-l10n

---

Pluralization

For plural forms, use the ICU message format:

ARB File

{
  "itemCount": "{count, plural, =0{No items} =1{1 item} other{{count} items}}",
  "@itemCount": {
    "description": "Shows the number of items",
    "placeholders": {
      "count": {
        "type": "int"
      }
    }
  }
}

Usage

Text(AppLocalizations.of(context)!.itemCount(items.length))

---

Best Practices

1. Always add descriptions to your template ARB file (app_en.arb) — they help translators understand context.

2. Use meaningful keys — prefer welcomeMessage over msg1.

3. Keep translations in sync — when adding a key to app_en.arb, add it to all other locale files.

4. Test all locales — verify translations display correctly, especially for longer text that might overflow UI elements.

5. Use placeholders for dynamic content — never concatenate translated strings.

---

Getting Started

This project is a starting point for a Flutter application.

For help getting started with Flutter development, view the online documentation.