timetracker/README.md

Zeiterfassung (Time Tracking Application)

A full-stack time tracking application built with Node.js, Express, SQLite, and containerized with Docker.

Features

• ✅ Track work time entries (date, start time, end time)
• ✅ Automatic break calculation according to German labor laws
• ✅ Maximum 10-hour net time cap
• ✅ Date range filtering
• ✅ CSV export with German formatting
• ✅ Responsive UI with Tailwind CSS
• ✅ Modern date/time picker (Flatpickr)
• ✅ Docker containerization

Technology Stack

• Backend: Node.js, Express.js
• Database: SQLite (better-sqlite3)
• Frontend: Vanilla JavaScript, HTML, Tailwind CSS
• Containerization: Docker

Project Structure

/zeiterfassung
  ├── public/
  │   ├── index.html       # Main UI
  │   └── app.js           # Frontend logic
  ├── db/
  │   └── schema.sql       # Database schema
  ├── server.js            # Express server with API endpoints
  ├── Dockerfile           # Multi-stage Docker build
  ├── package.json
  └── README.md

German Break Rules

The application automatically calculates break times according to German labor law:

• > 6 hours worked: 30 minutes break deducted
• > 9 hours worked: 45 minutes break deducted
• Net hours capped at 10.0 hours maximum

API Endpoints

• GET /api/entries?from=YYYY-MM-DD&to=YYYY-MM-DD - Get all entries in date range
• POST /api/entries - Create a new entry
• PUT /api/entries/:id - Update an existing entry
• DELETE /api/entries/:id - Delete an entry
• GET /api/export?from=YYYY-MM-DD&to=YYYY-MM-DD - Export entries as CSV

Running Locally

Prerequisites

• Node.js 18+ installed

Installation

1. Install dependencies:

npm install

2. Start the server:

npm start

3. Open your browser and navigate to:

http://localhost:3000

Running with Docker

Build the Docker image:

docker build -t zeiterfassung .

Run the container:

docker run -p 3000:3000 -v $(pwd)/db:/app/db zeiterfassung

The -v flag mounts the database directory to persist data between container restarts.

Access the application:

http://localhost:3000

CSV Export Format

The exported CSV file includes the following columns:

• Datum: Date in DD.MM.YYYY format
• Startzeit: Start time in HH:MM format
• Endzeit: End time in HH:MM format
• Pause in Minuten: Break time in minutes
• Gesamtstunden: Net hours with comma as decimal separator (e.g., 8,50)

Development

The application uses:

• Flatpickr for date and time selection with mobile-friendly interfaces
• Tailwind CSS for styling (loaded via CDN)
• SQLite for lightweight, file-based data persistence
• All calculations are performed server-side for data integrity

License

MIT