HabitFlow

Fullstack habit tracker built with a modern Android stack and a lightweight Node.js backend.

A portfolio project focused on polished mobile UX, local-first data flow, API integration, and real-world Android/backend debugging.

---

Demo

Full demo video: docs/fulldemo.mp4

---

Features

Mobile Experience

• Large progress header with daily completion summary
• Empty state presentation for first-time use
• Pull-to-refresh synchronization
• Swipe-to-delete habit cards
• Animated completion states and microinteractions
• Haptic feedback on key actions

Android Architecture

• Jetpack Compose UI with Material 3 styling
• MVVM structure with a dedicated repository layer
• Hilt dependency injection
• Room for local persistence
• Retrofit + OkHttp for API communication
• Coroutines and Flow for reactive updates

Backend Integration

• Node.js + Express API
• PostgreSQL persistence
• Input validation and meaningful API responses
• Health endpoint for local verification
• Prepared for future user-scoped behavior through optional request headers

---

What This Project Demonstrates

HabitFlow was built to show practical engineering skills that matter in real work:

• shipping a polished Android UI instead of a raw prototype
• structuring a maintainable mobile codebase
• integrating a real backend and database
• making local-first UX decisions for responsiveness
• debugging Gradle, network, HTTP/HTTPS, and device-to-backend issues end to end

---

Architecture

HabitFlow follows a local-first sync flow:

1. UI actions are sent to HabitViewModel
2. HabitViewModel delegates operations to HabitRepository
3. HabitRepository updates Room immediately for responsive UX
4. Retrofit syncs changes with the backend API
5. Compose observes Room through Flow and updates reactively

This keeps the app fast for the user while still demonstrating realistic mobile/backend synchronization.

---

Repository Structure

HabitFlow/
|- app/                  Android application
|- backend/              Node.js API
|- docs/                 GIFs, video, screenshots
|- gradle/
|- build.gradle.kts
`- README.md

---

Tech Stack

Layer	Technology
Android	Kotlin, Jetpack Compose, Material 3
Architecture	MVVM, Hilt, Repository Pattern
Local Storage	Room
Networking	Retrofit, OkHttp
Async	Coroutines, Flow
Backend	Node.js, Express
Database	PostgreSQL

---

API

Implemented routes:

• GET /health
• GET /habits
• POST /habits
• PATCH /habits/:id
• DELETE /habits/:id

---

Local Setup

Backend

From the backend folder:

npm install

Create .env from .env.example:

DATABASE_URL=postgresql://postgres:password@localhost:5432/habitflow
PORT=3000
HOST=0.0.0.0

Then run:

npm start

Android

Open the project in Android Studio and run it on an emulator or real device.

The client uses:

http://127.0.0.1:3000/

For a real device connected over USB:

& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" reverse tcp:3000 tcp:3000

You can verify backend availability through:

GET /health

---

Challenges Solved

• Fixed Gradle, Kotlin, Hilt, and plugin compatibility issues
• Resolved real-device backend communication using adb reverse
• Corrected HTTP/HTTPS mismatch and localhost networking issues
• Reworked backend persistence flow to correctly save habits in PostgreSQL
• Improved repository sync behavior and error messaging
• Refactored the UI from prototype quality to a more polished portfolio presentation

---

Why This Repo Belongs In A Portfolio

HabitFlow is not only a UI showcase. It demonstrates the ability to:

• build a complete Android app with modern architecture
• connect mobile, API, and database layers
• debug fullstack integration issues
• make thoughtful UX decisions
• ship a project in a presentation-ready state

---

Status

The project currently supports the full habit CRUD flow across Android, backend API, and PostgreSQL database, and is ready to be presented as a portfolio repository.