Grova

Goal Tracking & Daily Habit Building SaaS Platform

Transform your long-term goals into visual streaks, daily consistency heatmaps, and community accountability.

Table of Contents

• Overview
• Key Features
• Tech Stack
• Database Schema & Architecture
• Getting Started
  • Prerequisites
  • Installation
  • Environment Variables
• Available Scripts
• Commit Hooks & Code Quality
• Documentation & Guides
  • Deploying on Vercel
  • Neon PostgreSQL Database Setup
• Community & Contributing
• License

Overview

Grova is a modern, high-performance web application designed to help individuals and teams track their habits, reach ambitious targets, and maintain daily accountability. Taking inspiration from activity contribution graphs, Grova turns progress into interactive color-coded heatmaps, streak tracking algorithms, and real-time social feeds.

Whether you're tracking coding hours, fitness routines, reading targets, or financial savings, Grova provides an intuitive dashboard with rich visual feedback.

Note

Simple & Easy to Self-Host: Grova is kept intentionally lightweight and straightforward so that anyone can quickly self-host and customize it. This is a personal/hobby project created for ease of deployment and simplicity.

Key Features

• 🟩 Contribution Heatmap Grid: Visual 365-day activity grid displaying your daily effort intensity across all active goals.
• 🔥 Smart Streak Calculations: Real-time tracking of your current streak, longest streak, total contributions, and percentage completion rate.
• 🎯 Flexible Goal Structures:
  • TOTAL_TARGET: Cumulative target tracking (e.g. read 24 books or code 500 hours over a year).
  • DAILY_RECURRING: Daily habitual targets (e.g. meditate 20 mins every day).
  • WEEKLY_RECURRING: Weekly goal checkpoints.
• 🏷️ Categorized Management: Group goals into Work, Study, Health, Mindfulness, Finance, Creative, Social, or custom categories.
• 📝 Daily Logging & Quick Notes: Record daily progress, log partial or full completion status, and attach contextual quick notes to any day.
• 👥 Social Accountability Feed: Follow other achievers, explore public profiles, and stay inspired by community activity.
• 🔔 Intelligent Notifications: Receive alerts for streak milestones, goals at risk of falling behind, and friend achievements.
• 🌙 Modern Dark/Light UI: Built with Radix UI components, smooth Framer Motion micro-interactions, Tailwind CSS v4, and Lucide icons.
• 🔒 Enterprise-Grade Auth: NextAuth.js (Auth.js v5) integration supporting OAuth providers and secure session state.

Tech Stack

Core Framework & Runtime

• Framework: Next.js 16 (App Router)
• Library: React 19
• Language: TypeScript 5

Database & ORM

• Database: Neon Serverless PostgreSQL
• ORM: Prisma ORM v7

Authentication & API

• Auth Engine: NextAuth.js v5 (Auth.js) with @auth/prisma-adapter
• Schema Validation: Zod v4

Styling & Data Visualization

• Styling: Tailwind CSS v4 & PostCSS
• UI Components: Radix UI Primitives & class-variance-authority
• Icons: Lucide React
• Animations: Framer Motion v12
• Charts & Graphs: Recharts
• Toast Notifications: Sonner

Code Quality & Git Infrastructure

• Package Manager: pnpm v10
• Code Formatter: Prettier v3
• Linter: ESLint v9
• Commit Hooks: Husky v9 & lint-staged
• Commit Validation: Commitlint (Conventional Commits)

Database Schema & Architecture

Grova's database architecture leverages relational PostgreSQL models with optimized indexes and denormalized counters for lightning-fast reads:

erDiagram
    User ||--o{ Account : "authenticates via"
    User ||--o{ Session : "maintains"
    User ||--o{ Goal : "owns"
    User ||--o{ DailyLog : "logs"
    User ||--o{ QuickNote : "writes"
    User ||--o{ Notification : "receives"
    User ||--o{ Follow : "follows / followed by"
    Goal ||--o{ DailyLog : "tracks progress in"

    User {
        string id PK
        string email UK
        string username UK
        int currentStreak
        int longestStreak
        int totalContributions
        float completionRate
    }

    Goal {
        string id PK
        string userId FK
        string title
        GoalType type
        GoalStatus status
        GoalCategory category
        float targetAmount
        float completedAmount
        datetime startDate
        datetime endDate
    }

    DailyLog {
        string id PK
        string userId FK
        string goalId FK
        date date
        float completedAmount
        LogStatus status
    }

Loading

Getting Started

Prerequisites

Ensure you have the following installed on your local development machine:

• Node.js: v20.x or higher
• pnpm: v9.x or v10.x (npm i -g pnpm)
• PostgreSQL: A running instance or a free Neon PostgreSQL database URL.

Installation

1. Clone the repository:

   git clone https://github.com/RanitManik/Grova.git
   cd Grova

2. Install project dependencies:

   pnpm install

3. Configure Environment Variables: Create a .env file in the root directory by copying .env.example:

   cp .env.example .env

4. Initialize Database Schema: Generate Prisma Client and push schema to your database:

   pnpm db:push

5. Start Development Server:

   pnpm dev

   Open http://localhost:3000 to view Grova running locally.

Environment Variables

Variable	Description	Example / Default
DATABASE_URL	PostgreSQL connection string (Neon or standard Postgres)	postgresql://user:pass@ep-xxx.neon.tech/grova?sslmode=require
NEXTAUTH_SECRET	Secret token used to encrypt NextAuth JWT tokens	Generate via openssl rand -base64 32
NEXTAUTH_URL	Base URL of your application	http://localhost:3000 (Dev) / https://yourdomain.com (Prod)
AUTH_GITHUB_ID	GitHub OAuth App Client ID	Obtained from GitHub Developer Settings
AUTH_GITHUB_SECRET	GitHub OAuth App Client Secret	Obtained from GitHub Developer Settings
AUTH_GOOGLE_ID	Google OAuth App Client ID	Obtained from Google Cloud Console
AUTH_GOOGLE_SECRET	Google OAuth App Client Secret	Obtained from Google Cloud Console

Available Scripts

In the project root, you can run the following scripts using pnpm:

Command	Description
pnpm dev	Starts the Next.js development server with hot reloading.
pnpm build	Runs production migrations (prisma migrate deploy), generates Prisma client, and compiles Next.js for production.
pnpm start	Starts the Next.js production server.
pnpm validate	Full QA run: Tailwind class check, formatting, linting, type-checking & build test.
pnpm format	Auto-formats all codebase files using Prettier.
pnpm format:check	Verifies code formatting compliance without modifying files.
pnpm lint	Runs ESLint to catch syntax, import, and code style issues.
pnpm type-check	Performs strict TypeScript type checks (tsc --noEmit).
pnpm db:generate	Generates Prisma Client TypeScript definitions.
pnpm db:push	Pushes Prisma schema directly to the configured database.
pnpm db:migrate	Runs database migrations in development mode (prisma migrate dev).
pnpm db:deploy	Runs pending database migrations safely in production mode (prisma migrate deploy).
pnpm db:reset	Drops and resets the development database schema (prisma migrate reset).
pnpm db:studio	Launches Prisma Studio GUI at http://localhost:5555.

Commit Hooks & Code Quality

Grova uses Husky, Commitlint, and lint-staged to enforce code standard consistency on every commit:

• Pre-commit Hook: Automatically formats and lints only staged files before code can be committed (lint-staged).
• Commit-msg Hook: Ensures commit messages follow the Conventional Commits specification (feat: ..., fix: ..., docs: ..., refactor: ..., etc.).

Example of a valid commit:

git commit -m "feat(analytics): add monthly completion breakdown chart"

If a commit message does not comply with the convention, the commit will be rejected with actionable feedback.

Documentation & Guides

• System Architecture: Read our Technical Architecture & System Design guide for details on Next.js App Router patterns, RSC boundaries, and database schema mechanics.
• Deployment & Self-Hosting: For step-by-step instructions on Vercel deployment, Neon PostgreSQL configuration, and custom self-hosting (Docker/VPS/Node), read our full Deployment & Self-Hosting Guide.
• Automated CI/CD & Releases: For details on our GitHub Actions verification workflows, Dependabot auto-merge, Changeset versioning, and GitHub release automation, see the CI/CD Pipeline Documentation.

Deploying on Vercel

The easiest and recommended way to deploy Grova is using Vercel:

1. Push your code to your GitHub repository.
2. Import the repository into your Vercel Dashboard.
3. Vercel will automatically detect Next.js.
4. Set the Build Command to pnpm build (or npx prisma generate && next build).
5. Add all required Environment Variables (DATABASE_URL, NEXTAUTH_SECRET, NEXTAUTH_URL, OAuth keys) in Vercel settings.
6. Click Deploy.

Neon PostgreSQL Database Setup

1. Create a free account on Neon.tech.
2. Create a new project named grova-db.
3. Copy your Pooled & Direct Connection Strings.
4. Set DATABASE_URL in your Vercel environment settings.
5. Execute database schema sync:

   pnpm db:push

Community & Contributing

We welcome and appreciate contributions of all kinds! Please read our community guidelines before opening an issue or pull request:

• Contributing Guide — Detailed steps on local setup, branch conventions, and PR workflow.
• Community Standards — Code quality checklists, architectural constraints, and review rules.
• Support Guidelines — How to get help, report bugs, ask questions, or request features.
• Project Governance — Maintainer responsibilities, decision-making, and release management.
• Code of Conduct — Community behavior standards and pledge.
• Security Policy — Guidelines for reporting security vulnerabilities.
• Pull Request Template — Checklist for submitting PRs.

License

This project is open-source software licensed under the MIT License.

---

Built with ❤️ by Ranit Manik and the Open Source Community.