# Heart-Tracking

**Repository Path**: GallifreY/heart-tracking

## Basic Information

- **Project Name**: Heart-Tracking
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-17
- **Last Updated**: 2025-12-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Heart - Couple Anniversary Tracker

A beautiful Android app for couples to track their relationship journey with daily check-ins displayed in a heart-shaped grid.

## ✨ Features

### Core Functionality
- **365-Day Heart Grid**: Visualize your first year together with 365 days arranged in a heart shape
- **Daily Check-ins**: Tap any day to check in and mark it as completed
- **Rich Details**: Add notes, photos (up to 5), and mood ratings (1-5 stars) for each day
- **Smart Date Mapping**: Set your relationship start date and the app automatically maps days
- **Today Highlight**: Automatically highlights today's cell in the grid

### Statistics & Insights
- **Total Days Together**: See how many days you've been together
- **Check-in Count**: Track how many days you've checked in
- **Current Streak**: Monitor your consecutive check-in streak
- **Longest Streak**: View your best streak record
- **Completion Percentage**: See your overall check-in completion rate

### Data Management
- **Local Storage**: All data stored securely on your device using Room database
- **Export Data**: Export your check-ins to JSON format for backup
- **ZIP Export with Photos**: Export all data including photos in a single ZIP file
- **Import Data**: Import previously exported data to restore or merge
- **Backup Reminder**: Automatic reminder after 30 days to backup your data
- **Photo Attachments**: Attach and view photos for memorable days
- **Share**: Share your backup files via Android share sheet

### UI/UX
- **Beautiful Heart Theme**: Pink and rose-colored theme perfect for couples
- **Material 3 Design**: Modern Android design with smooth animations
- **Haptic Feedback**: Feel each interaction with tactile feedback
- **Empty State**: Helpful guidance when starting your journey
- **Loading States**: Smooth loading indicators throughout the app
- **Error Handling**: Clear error messages for better user experience

## 📱 Screenshots

[Screenshots would go here]

## 🏗️ Architecture

The app follows Clean Architecture principles with MVVM pattern:

### Project Structure
```
app/src/main/java/com/kerong/heart/
├── data/
│   ├── local/          # Room database, DAOs, DataStore
│   ├── model/          # Data models and entities
│   └── repository/     # Repository pattern implementation
├── domain/
│   └── statistics/     # Business logic for statistics
├── ui/
│   ├── components/     # Reusable Compose components
│   ├── screens/        # App screens
│   ├── theme/          # Theme and styling
│   └── viewmodel/      # ViewModels
└── util/               # Utilities and helpers
```

### Tech Stack
- **Language**: Kotlin
- **UI**: Jetpack Compose with Material 3
- **Architecture**: MVVM + Clean Architecture
- **Database**: Room
- **Preferences**: DataStore
- **Navigation**: Jetpack Navigation Compose
- **Image Loading**: Coil
- **Async**: Kotlin Coroutines & Flow
- **DI**: Manual dependency injection (lightweight)

## 🚀 Getting Started

### Prerequisites
- Android Studio Hedgehog or newer
- JDK 11 or newer
- Android SDK with minimum API 24 (Android 7.0)

### Building the Project
1. Clone the repository
2. Open the project in Android Studio
3. Sync Gradle files
4. Run the app on an emulator or physical device

### First Time Setup
1. Launch the app
2. Select your relationship start date
3. Tap the "Start Tracking" button
4. Begin your journey by checking in days!

## 💝 How to Use

### Checking In
- **Quick Check-in**: Tap an unchecked day to quickly mark it as checked
- **Detailed Check-in**: Tap a checked day to add notes, photos, and mood rating
- **Uncheck**: Long-press a checked day to uncheck it (with confirmation)

### Managing Data
- **Export JSON**: Tap menu → "Export Data" to save check-ins as JSON (without photos)
- **Export ZIP**: Use the ZIP export option to include photos in the backup
- **Import**: Tap menu → "Import Data" to restore from a backup (supports both JSON and ZIP)
- **Backup Reminder**: The app will remind you every 30 days to backup your data
- **Jump to Today**: Tap the floating action button to quickly view today

### Adding Details
- **Notes**: Add text notes to remember what made the day special
- **Photos**: Attach up to 5 photos per day from your gallery
- **Mood**: Rate your day with 1-5 stars
- **Edit**: All details are editable at any time

## 🎨 Customization

The app uses a romantic heart theme with customizable colors in:
- `ui/theme/Color.kt` - Color definitions
- `ui/theme/Theme.kt` - Theme configuration

## 📦 Data Storage

### Local Database
- Check-ins are stored in a Room database (`HeartDatabase`)
- Photos are stored as URIs with optional local copies
- Settings stored in DataStore (relationship start date, last backup)

### Export Format

**JSON Export** (lightweight, no photos):
```json
{
  "version": 1,
  "relationshipStartDate": "2024-01-01",
  "exportTimestamp": 1704067200000,
  "checkIns": [
    {
      "dayNumber": 1,
      "date": "2024-01-01",
      "timestamp": 1704067200000,
      "note": "Our first day together!",
      "moodRating": 5,
      "photoUris": "[\"content://...\"]"
    }
  ]
}
```

**ZIP Export** (includes photos):
- Contains `backup.json` with check-in data
- Contains `photos/` directory with all attached images
- Preserves photo-to-check-in relationships
- Fully portable and restorable

## 🛠️ Development

### Key Components
- **HeartViewModel**: Main app state and business logic
- **HeartShapeLayout**: Mathematical heart shape generation for 365 cells
- **StatisticsCalculator**: Streak and statistics calculations
- **ExportImportUtils**: Data backup and restore functionality

### Database Schema
```kotlin
@Entity(tableName = "checkins")
data class CheckInEntity(
    @PrimaryKey val dayNumber: Int,  // 1-365
    val date: String,                // ISO-8601 format
    val timestamp: Long,             // Check-in time
    val note: String?,               // Optional note
    val moodRating: Int?,            // 1-5 rating
    val photoUris: String?           // JSON array of URIs
)
```

## 🤝 Contributing

This is a personal project, but suggestions and feedback are welcome!

## 📄 License

[Your chosen license]

## 🙏 Acknowledgments

- Heart shape algorithm inspired by mathematical heart curves
- Material Design 3 guidelines from Google
- Jetpack Compose for modern Android UI

## 📞 Contact

[Your contact information]

---

Made with ❤️ for couples everywhere