Simon Franken
7ec76e3e8e
The balance now accounts for any active timer whose project belongs to the tracked client. computeBalance() fetches the user's OngoingTimer, computes its elapsed seconds, and adds them to the matching period's tracked seconds before running the balance formula — so both currentPeriodTrackedSeconds and totalBalanceSeconds reflect the live timer without requiring a schema change. On the frontend, useClientTargets polls every 30 s while a timer is running, and a pulsing green dot is shown next to the balance figure on the Dashboard and Clients pages to signal the live contribution.
TimeTracker
A multi-user web application for tracking time spent working on projects. Users authenticate via an external OIDC provider and manage their own clients, projects, and time entries.
Features
- OIDC Authentication - Secure login via external OpenID Connect provider with PKCE flow
- Client Management - Create and manage clients/customers
- Project Management - Organize work into projects with color coding
- Time Tracking - Start/stop timer with live elapsed time display
- Manual Entry - Add time entries manually for past work
- Validation - Overlap prevention and end-time validation
- Responsive UI - Works on desktop and mobile
Architecture
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ React │────▶│ Express │────▶│ PostgreSQL │
│ Frontend │ │ Backend │ │ Database │
└─────────────┘ └─────────────┘ └─────────────┘
│
▼
┌─────────────┐
│ OIDC │
│ Provider │
└─────────────┘
Quick Start
Prerequisites
- Node.js 18+
- PostgreSQL 14+
- An OIDC provider (e.g., Keycloak, Auth0, Okta)
1. Database Setup
# Create PostgreSQL database
createdb timetracker
2. Backend Setup
cd backend
npm install
# Copy and configure environment
cp ../.env.example .env
# Edit .env with your database and OIDC settings
# Run migrations
npx prisma migrate dev
# Start server
npm run dev
3. Frontend Setup
cd frontend
npm install
npm run dev
4. Environment Variables
Create .env in the backend directory:
# Database
DATABASE_URL="postgresql://user:password@localhost:5432/timetracker"
# OIDC Configuration
OIDC_ISSUER_URL="https://your-oidc-provider.com"
OIDC_CLIENT_ID="your-client-id"
OIDC_REDIRECT_URI="http://localhost:3001/auth/callback"
# Session
SESSION_SECRET="your-secure-session-secret-min-32-chars"
# Server
PORT=3001
NODE_ENV=development
APP_URL="http://localhost:5173"
API Endpoints
Authentication
GET /auth/login- Initiate OIDC loginGET /auth/callback- OIDC callbackPOST /auth/logout- End sessionGET /auth/me- Get current user
Clients
GET /api/clients- List clientsPOST /api/clients- Create clientPUT /api/clients/:id- Update clientDELETE /api/clients/:id- Delete client
Projects
GET /api/projects- List projectsPOST /api/projects- Create projectPUT /api/projects/:id- Update projectDELETE /api/projects/:id- Delete project
Time Entries
GET /api/time-entries- List entries (with filters/pagination)POST /api/time-entries- Create entryPUT /api/time-entries/:id- Update entryDELETE /api/time-entries/:id- Delete entry
Timer
GET /api/timer- Get ongoing timerPOST /api/timer/start- Start timerPUT /api/timer- Update timer (set project)POST /api/timer/stop- Stop timer (creates entry)
Data Model
User (oidc sub)
├── Client[]
│ └── Project[]
│ └── TimeEntry[]
└── OngoingTimer (optional)
Technology Stack
Backend:
- Node.js + Express
- TypeScript
- Prisma ORM
- PostgreSQL
- OpenID Client
Frontend:
- React 18
- TypeScript
- TanStack Query
- React Router
- Tailwind CSS
- date-fns
License
MIT