Skip to content

README.md

Latest commit

 

History

History
111 lines (87 loc) · 8.6 KB

README.md

File metadata and controls

111 lines (87 loc) · 8.6 KB

SelfGoals 🎯

A high-polish, local-first Android application designed to help you define, track, and achieve your life goals. Built with a modern iOS 18-inspired aesthetic, SelfGoals combines powerful functionality with a fluid, tactile user experience.

🌐 Visit the Live Landing Page

✨ Features

  • iOS 18 Design Language: Modular "widget" layouts, glassmorphism, bold typography, and fluid squircle shapes.
  • Custom Adaptive Icon: A unique brand identity featuring a growth-oriented design with a vibrant blue-to-purple gradient.
  • Haptic Feedback: Tactile "clicks" and physical confirmation for key interactions (toggles, archiving, adding items) for a premium, responsive feel.
  • Intelligent Analytics: Real-time activity dashboard showing goal and task completion rates via modular overview tiles.
  • Goal Management: Create, edit, and track goals with detailed descriptions, custom categories, and Priority status (marked with a ⭐).
  • Milestones (Sub-tasks): Break down large goals into smaller, actionable milestones with automated progress tracking and manual reordering (Up/Down controls).
  • Advanced Sorting: Organize your dashboard by Deadline, Progress, Creation Date, Name, or Priority.
  • Custom Theme Control: Persistent Light/Dark mode settings using Jetpack DataStore that remember your preference across app restarts.
  • Goal Archives: Keep your dashboard focused by archiving completed goals. A dedicated view lets you manage and unarchive your history.
  • Search & Filtering: Dynamic, iOS-style search bar and interactive category tags for instant goal discovery.
  • Smart Reminders: Schedule local notifications using WorkManager to stay on top of your deadlines.
  • Localization Ready: All UI strings are externalized to res/values/strings.xml, ready for translation.
  • Visual Deadlines: Integrated Material 3 DatePicker with overdue highlighting (Red alert for past-due tasks).
  • Data Export: Share a comprehensive, beautifully formatted text summary of your goals, milestones, and stats with other apps.

📱 Visuals

Dashboard Goal Details

🛠 Tech Stack

  • Language: Kotlin 1.9.22
  • UI Framework: Jetpack Compose (Declarative UI)
  • Architecture: MVVM (Model-View-ViewModel)
  • Dependency Injection: Hilt 2.50
  • Local Persistence: Room Database 2.6.1 & Jetpack DataStore
  • Background Tasks: WorkManager (for robust reminders)
  • Asynchronous Flows: Kotlin Coroutines & StateFlow
  • Testing: JUnit 4, MockK, Turbine, and Hilt Testing
  • Build System: Gradle 9.5.0 with KSP (Kotlin Symbol Processing)

📂 Project Structure

SelfGoals/
├── app/
│   ├── src/main/
│   │   ├── java/com/example/selfgoals/
│   │   │   ├── data/           # Entities, DAOs, and Repositories (Settings & Goals)
│   │   │   ├── di/             # Hilt Dependency Injection modules
│   │   │   ├── ui/             # Compose Screens (Dashboard), ViewModels, and Themes
│   │   │   ├── worker/         # WorkManager background workers
│   │   │   └── utils/          # Helpers (Notifications, formatting)
│   │   ├── res/values/         # externalized strings.xml and colors
│   │   └── AndroidManifest.xml # App manifest and configuration
│   ├── src/test/               # DashboardViewModel Unit Tests
│   └── src/androidTest/        # Compose UI Instrumented Tests
└── build.gradle.kts            # Root project dependencies

🏗 Architecture & Design Patterns

SelfGoals strictly follows Clean Architecture principles coupled with the MVVM (Model-View-ViewModel) architectural pattern. It is designed to be highly modular, decoupled, and exceptionally testable.

1. Data Layer (Robust Local-First Persistence)

  • Room SQLite Relational Mapping: Instead of simple flat tables, SelfGoals models real-world complexity using foreign key relations (onDelete = ForeignKey.CASCADE for milestones, and onDelete = ForeignKey.SET_NULL for categories).
  • Embedded & Relation Models: Models like GoalDetails dynamically bind goals, categories, and milestones via Room's @Relation queries. This structure avoids manual SQL join logic and leverages Room's transactional runtime safely.
  • Jetpack Preferences DataStore: User preferences (e.g., active theme, sorting selection, and archives view) are persisted asynchronously using Jetpack DataStore to eliminate main-thread UI blockage.

2. Domain & Presentation Layer (Reactive & Resource-Efficient)

  • StateFlow & Cold Flow Combinators: The DashboardViewModel transforms Room's persistent cold query streams into UI-bound hot StateFlow streams.
  • Highly Performant Combining Logic: Multiple state sources (_allGoals, _searchQuery, showArchived, _selectedCategoryId, sortOption) are combined reactively via standard Flow operators to dynamically recalculate UI lists and stats under a resource-saving lifecycle context (SharingStarted.WhileSubscribed(5000)).
  • Intelligent Activity Stats: Analytics computation runs entirely reactively, automatically updating active milestone completion rates, goal status fractions, and category-level metrics as data mutates.

3. Background Services & Native Integration

  • WorkManager Scheduling: Reminders are managed via Android's modern GoalReminderWorker and WorkManager APIs, guaranteeing notification execution even if the application is closed or the device reboots.
  • Haptic Tactile Feedback Engine: Crucial state mutations (completing goals, toggling priority, or saving entities) trigger native OS haptic ticks (HapticFeedbackType.LongPress) to offer a premium, premium physical feedback sensation.

🧪 Testing Strategy

Quality is a core pillar of the SelfGoals engineering philosophy. The test suite covers both logic flows and end-to-end integration:

  1. Unit Testing (src/test): Powered by JUnit 4, MockK (for mock behaviors), and Turbine (for native Flow/StateFlow test streams). Tests validate:
    • Dynamic search query filtering.
    • Core analytics and stats calculations.
    • Repository interactions upon user events (e.g., goal completion).
  2. Instrumented UI Testing (src/androidTest): Implemented using Jetpack Compose UI Testing library and Hilt Android Testing.
    • Uses a custom HiltTestRunner to wire up real viewmodels with mock/faked injection trees for predictable test states.
    • Tests assert main header visibility and verify dialog popup transitions.
    • Runs seamlessly on physical devices and AVD emulators (verified on medium_phone AVD with automated connectedAndroidTest in 9 seconds).

🚀 Getting Started

  1. Clone the repository.
  2. Open the project in Android Studio Hedgehog or newer.
  3. Sync Gradle and run on an emulator or physical device (API 24+).
  4. Run Tests: Execute ./gradlew test for unit tests or ./gradlew connectedAndroidTest for UI tests.

✅ Project Status: v1.3 Refined

  • Milestone Sorting Fix: Enforced robust position-based sorting (sortedBy { it.position }) across both Jetpack Compose UI rendering and viewmodel reordering logic to resolve milestone ordering deviations.
  • AVD Verified: Successfully executed the entire test suite on a local AVD emulator (medium_phone), verifying main layouts, checkmarks, stats, and navigation flow.
  • Interactive States Verified: Conducted step-by-step state verification including active goal creation, overdue red-alert visuals, real-time searching, and priority sorting.
  • Robust Testing: Comprehensive suite of unit and on-device instrumented Compose UI tests. Instrumented tests run and pass seamlessly in 9 seconds.
  • Brand Identity & Persistence: Features high-polish iOS 18-inspired custom icons, responsive haptic feedback, and local preference storage via Jetpack DataStore.

SelfGoals is built with care using modern Android standards and a focus on UX.