🎯 Goal Tracker

A modern, self-hosted goal tracking and task management system built with TypeScript, React, and PostgreSQL.

---

📖 Overview

Goal Tracker is a comprehensive personal productivity system that combines goal management with task planning. Track yearly, monthly, and weekly goals while managing daily tasks in an integrated calendar view. Built as a monorepo with separate API and web applications, designed for easy self-hosting via Docker.

✨ Key Features

• 🎯 Hierarchical Goal System: Create yearly goals with monthly/weekly sub-goals
• ✅ Task Management: Separate task entities with size estimation and scheduling
• 📅 Integrated Planner: Calendar view combining goals and tasks
• 📊 Progress Tracking: Multiple modes (task-based, manual, habit tracking)
• 🔗 Goal-Task Linking: Many-to-many relationships between goals and tasks
• 📱 PWA Support: Install as a standalone app on any device
• ⌨️ Keyboard Accessibility: Optimized keyboard navigation and mobile keyboard handling
• 🐳 Docker Deployment: Complete containerized stack with GitHub Actions CI/CD
• ⚡ Performance Optimized: Efficient API calls with server-side data fetching

---

🚀 Quick Start

Prerequisites

• Docker and Docker Compose installed
• Node.js 18+ and pnpm (for local development)
• PostgreSQL 15 (or use Docker container)

Option 1: Docker Compose (Recommended)

# Clone the repository
git clone https://github.com/YOUR_USERNAME/goal-tracker.git
cd goal-tracker

# Create environment file
cp .env.example .env
# Edit .env with your settings

# Start all services
docker compose up -d

# Access the application
# Web UI: http://localhost:5173
# API: http://localhost:3000

Option 2: Local Development

# Install dependencies
pnpm install

# Set up database
cd apps/api
cp .env.example .env
# Configure DATABASE_URL in .env

# Run migrations
pnpm prisma migrate dev

# Start development servers (from root)
pnpm dev

# Access at:
# Web: http://localhost:5173
# API: http://localhost:3000

---

📁 Project Structure

goal-tracker/
├── apps/
│   ├── api/              # Express.js REST API
│   │   ├── prisma/       # Database schema & migrations
│   │   └── src/          # Route handlers & services
│   └── web/              # React + Vite frontend
│       └── src/          # Components, pages, hooks
├── packages/shared/      # Shared utilities & types
├── scripts/              # Deployment helpers
├── docs/                 # Documentation
└── docker-compose.yml    # Docker configuration

---

🛠️ Technology Stack

Layer	Technology
Frontend	React 18, TypeScript, TailwindCSS
Backend	Node.js, Express, Prisma ORM
Database	PostgreSQL 15
Build Tools	Vite, pnpm workspaces
DevOps	Docker, GitHub Actions
UI Library	shadcn/ui, Radix UI

---

📱 Core Concepts

Goals vs Tasks

Goals are long-term objectives with measurable progress:

• Yearly, Monthly, Weekly, or Standalone scopes
• Progress modes: Task-based, Manual Total, or Habit tracking
• Example: "Read 12 books this year"

Tasks are actionable work items:

• Can link to multiple goals
• Have size estimation (in days)
• Schedule on specific dates
• Example: "Read Chapter 1" (size: 1 day)

Progress Tracking Methods

1. Task-Based: Progress calculated from completed linked tasks
2. Manual Total: Directly increment progress amount
3. Habit: Binary completion tracking (done or not done)

---

🚢 Deployment

Quick Deploy (GitHub Actions)

Setup:

1. Create Docker Hub account and GitHub secrets:

   • DOCKER_USERNAME, DOCKER_PASSWORD
   • SSH_PRIVATE_KEY, SERVER_HOST, SERVER_USER
   • DATABASE_URL

2. Run server setup script:

   curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/goal-tracker/main/scripts/server-setup.sh | bash

3. Push to main branch - deployment starts automatically

Local Deployment

# Build Docker images
docker compose -f docker-compose.prod.yml build

# Deploy
docker compose -f docker-compose.prod.yml up -d

Database Configuration

Option A: Dedicated PostgreSQL (default)

# Use included PostgreSQL container
docker compose up -d

Option B: Shared PostgreSQL (existing database)

# Use docker-compose.shared-network.yml
docker compose -f docker-compose.shared-network.yml up -d

---

🔧 Configuration

Environment Variables

API (apps/api/.env):

DATABASE_URL=postgresql://user:pass@localhost:5432/goaltracker
AUTH0_ISSUER=https://your-auth0-domain/
AUTH0_AUDIENCE=https://your-api-audience

Web (apps/web/.env):

VITE_API_URL=http://localhost:3000/api
VITE_AUTH0_DOMAIN=your-auth0-domain
VITE_AUTH0_CLIENT_ID=your-client-id
VITE_AUTH0_AUDIENCE=https://your-api-audience

Database Migrations

cd apps/api

# Create new migration
pnpm prisma migrate dev --name migration_name

# Check status
pnpm prisma migrate status

# View data UI
pnpm prisma studio

---

📚 Documentation

• Quick Start - Get started in 5 minutes
• Deployment Guide - Production setup details
• Database Setup - PostgreSQL options
• HTTPS Setup - SSL with Tailscale
• Code Style - Formatting conventions
• PWA Setup - Progressive Web App config
• Architecture Notes - Design decisions

For authentication implementation details, see .copilot-instructions.md

---

🗺️ Roadmap

✅ Completed

• Core CRUD operations
• Calendar planner with drag-and-drop
• Goal hierarchy & progress rollup
• Bulk task creation
• Docker deployment
• GitHub Actions CI/CD
• PWA support
• Keyboard accessibility (useKeyboardHeight hook)
• API performance optimization
• TypeScript & Prisma fixes

🚧 Planned

• React Query migration
• TypeScript strict mode
• Component library extraction
• Testing suite (Vitest + RTL)
• Advanced search & filtering
• Mobile UX improvements

---

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Commit with conventional messages
4. Push and open a Pull Request

Code Standards

# Format code
pnpm format

# Check types
pnpm type-check

# Run linter
pnpm lint

# Build
pnpm build

---

🔒 Security

• Self-hosted: No cloud dependencies
• Single-user: Designed for personal use
• Network: Run behind VPN/firewall for extra security
• HTTPS: Optional but recommended with Tailscale

For security issues: security@example.com

---

📄 License

MIT License - see LICENSE file

---

🙏 Thanks

Built with shadcn/ui, Prisma, Tailwind CSS, React, and Vite

---

⬆ Back to Top

Made with ❤️ for productivity enthusiasts