Habit Tracker

A full-stack habit tracking application built with React and Express. The system supports Supabase authentication, real-time updates over Socket.io, wellness logging, and AI-generated habit insights.

Technology

Layer	Stack
Frontend	React 19, Vite, Tailwind CSS, Recharts
Backend	Node.js, Express
Database	MongoDB with Mongoose
Auth	Supabase Auth and Storage
Real-time	Socket.io
AI	OpenRouter (GPT-4o-mini)

Repository Layout

habit-tracker/
  package.json          Root command shortcuts

  frontend/
    public/             Static assets
    src/
      pages/
        auth/           Login, signup, password reset
        habits/         Habits, history, statistics
        wellness/       Water, sleep, exercise, mood
      components/       Shared UI and feature components
      context/          Auth, theme, toast, notifications
      hooks/            Socket and reminder hooks
      lib/              Client-side helpers
      services/         HTTP and WebSocket clients

  backend/
    .env.example        Environment variable template
    server.js           Application entry point
    loadEnv.js          Loads the root .env file
    scripts/
      verify.js         Integration verification suite
      migrations/       Database migration scripts
    src/
      config/           Database, CORS, Supabase setup
      controllers/      HTTP request handlers
      services/         Business logic
      models/           Mongoose schemas
      routes/           API route definitions
      middleware/       Authentication and uploads
      jobs/             Scheduled tasks
      socket/           Real-time event handling
      utils/            Shared backend helpers

Request Flow

Frontend: pages use components, hooks, and context, then call services to reach the API.

Backend: routes pass through middleware, then controllers call services, which read and write MongoDB models.

Prerequisites

1. Node.js 18 or later
2. A running MongoDB instance or MongoDB Atlas connection string
3. A Supabase project with authentication enabled
4. An OpenRouter API key if AI insights are requires

Environment Setup

1. Copy backend/.env.example to .env in the project root.
2. Fill in every variable in .env.
3. In Supabase, enable email authentication and create a public storage bucket named habit-tracker.
4. Keep VITE_API_URL=/api so the Vite dev server proxies API traffic to the backend.

Installation

Install dependencies in each application folder. The project root does not maintain its own node_modules directory.

cd backend
npm install
cd ../frontend
npm install
cd ..

Running the Application

Start both servers from the project root:

npm run dev

Service	URL
Frontend	http://localhost:5173
Backend API	http://localhost:5055/api

To run each part separately:

npm run dev:backend
npm run dev:frontend

Available Commands

Command	Description
npm run dev	Start backend and frontend together
npm run dev:backend	Start the backend only
npm run dev:frontend	Start the frontend only
npm run stop	Stop Node processes on Windows
npm run build	Build the frontend for production
npm run start	Start the backend in production mode
npm test	Run backend integration verification

Application Modules

Module	Route	Purpose
Authentication	/login, /signup	Sign in, registration, password recovery
Dashboard	/	Daily habit summary and activity overview
Habits	/habits	Create, edit, pause habits and view insights
History	/history	Past habit activity
Statistics	/stats	Streaks, completion rates, weekly charts
Wellness	/wellness	Water, sleep, exercise, and mood tracking
Settings	/settings	Theme, notifications, and account options
Notifications	/notifications	In-app notification history

Scheduled Tasks

Schedule	Action
Daily midnight	Mark missed habits and prepare the next daily log set
Monday 08:00	Generate weekly AI insights for active habits
Real-time	Push dashboard and habit updates through Socket.io

API Endpoints

Prefix	Responsibility
/api/auth	Profile and avatar management
/api/habits	Habit creation, updates, pause, resume
/api/tracking	Complete or skip habits
/api/dashboard	Dashboard summary data
/api/stats	Habit statistics
/api/ai	Daily and weekly habit insights
/api/settings	Theme and notification preferences
/api/notifications	Notification listing and read state
/api/wellness	Wellness logs and weekly summaries