ClockWise

Time Tracking Application

🌟 If you find this helpful, please star this repo — it helps others discover these resources!

Table of contents

• Overview
• Features
• Links
• Quick Start
  • Prerequisites
  • Installation & Setup
  • Running the Application
• How to Use
  • Setup Your Projects and Tasks
  • Track Time
  • Quick Task Switching
  • View Daily Totals
• Data Storage
• Time Tracking Rules
• Architecture
• API Endpoints
• Project Structure
• Development
  • Testing
• Licence
• Authors

Overview

A web-based time tracking application that helps you keep track of how much time you spend on tasks during your working day.

Features

• Project Management - Create and organize projects (includes a built-in "No Project")
• Task Management - Add tasks and link a single task per project via checkbox
• Real-time Timer - Track time with minute-level precision (HH:MM format)
• Daily Summary - View total time by task, by project, by task-per-project, plus a chronological entries list
• Daily Isolation - Data is organized by day with a 4 AM boundary and proper overlap handling
• Timesheet PDF - Generate a daily PDF with totals and chronological entries
• Persistent Storage - All data is stored locally in SQLite

Screenshot

Links

• Deployed Application
• GitHub Repo

Quick Start

Prerequisites

• Node.js (v16 or higher)
• npm

Installation & Setup

1. Install backend dependencies:

   cd backend
   npm install

2. Install frontend dependencies:

   cd ../frontend
   npm install

Running the Application

1. Start the backend (Terminal 1):

   cd backend
   npm run dev

   The backend will run on http://localhost:3001

2. Start the frontend (Terminal 2):

   cd frontend
   npm run dev

   The frontend will run on http://localhost:3000

3. Open your browser and navigate to http://localhost:3000

How to Use

Setup Your Projects and Tasks

1. Use the Projects section to create projects (or use the default "No Project")
2. Select a project and use the Tasks section to create tasks
3. Link a task to the selected project by checking its checkbox (one task per project)

Track Time

1. Click on a task in the Tasks section to select it
2. In the Timer section, click the Start button to begin tracking
3. The timer will show elapsed time in HH:MM:SS format
4. Click End to stop tracking and record the entry
   • Entries shorter than 1 minute are automatically discarded

Quick Task Switching

• Use Quick Task Switching to set the active task for the timer
• Quick switch auto-links the task to the selected project and starts timing
• If a timer is running, it ends it and switches to the new task automatically

View Daily Totals

The Daily Summary section shows:

• Total Time by Task - Time spent on each task
• Total Time by Project - Time spent on each project
• Total Time by Task per Project - Breakdown of each task within each project
• Today's Entries (Chronological) - Start/end times with durations

Data Storage

All data is stored locally in a SQLite database at:

~/Library/Application Support/ClockWise/clockwise.db

Time Tracking Rules

• Time precision: Recorded to the minute (start and stop times)
• Minimum duration: Entries must be at least 1 minute to be recorded
• Non-overlapping tasks: Starting a new task automatically ends the previous one
• Daily boundary: New days start at 4 AM (time before 4 AM belongs to the previous day)
• Overlap handling: Entries spanning multiple days are split into the correct day window

Architecture

• Backend: Node.js + Express + SQLite3
• Frontend: React + Vite
• Data: Local SQLite database
• Communication: REST API over HTTP

API Endpoints

Method	Path	Purpose
GET	/api/projects	List projects
POST	/api/projects	Create project
PUT	/api/projects/:id	Rename project
DELETE	/api/projects/:id	Delete project
GET	/api/tasks	List tasks
POST	/api/tasks	Create task
PUT	/api/tasks/:id	Rename task
DELETE	/api/tasks/:id	Delete task
GET	/api/timer/current	Fetch active timer
POST	/api/timer/start	Start timer for task
POST	/api/timer/end	End active timer
GET	/api/totals	Daily totals summary
GET	/api/timesheet/entries	Daily time entries (chronological)

Project Structure

ClockWise/
├── backend/
│   ├── database.js       - Database initialization and helpers
│   ├── utils.js          - Time calculation utilities
│   ├── server.js         - Express server and API endpoints
│   └── package.json
├── frontend/
│   ├── src/
│   │   ├── App.jsx       - Main application component
│   │   ├── main.jsx      - React entry point
│   │   ├── index.css     - Global styles
│   │   └── components/
│   │       ├── ProjectManager.jsx  - Project CRUD
│   │       ├── TaskManager.jsx     - Task CRUD
│   │       ├── Timer.jsx           - Timer controls
│   │       └── Totals.jsx          - Daily summary display
│   ├── index.html
│   ├── vite.config.js
│   └── package.json
├── README.md
└── LICENSE

Development

To work on the application:

1. Run both servers together from repo root with npm run dev
2. Backend changes automatically reload with npm run dev
3. Frontend changes automatically reload with Vite's hot module replacement
4. Make API changes in backend/server.js
5. Make UI changes in frontend/src/

Testing

Run the full test suite from the repo root:

npx vitest run --no-cache

License

This project is licensed under the MIT License. See the LICENSE file for details.

Authors

• GitHub - YTasheva | Yuliya Tasheva
• For any questions, suggestions, or issues, please contact our team at

Email info@yuliya-tasheva.co.uk  ·  Copyright © 2026 All Rights Reserved. Site By Yuliya Tasheva®