Time Tracking System

Professional time tracking application for manufacturing and operations management. Track employee hours across machines and work orders with real-time timer, administrative controls, and comprehensive audit trails.

Quick Start

Prerequisites

• Node.js 16+ (npm 8+)
• Modern web browser (Chrome, Firefox, Safari, Edge)

Installation & Running

# Install dependencies
npm install

# Start development server
npm run dev
# Open http://localhost:5173 in your browser

# Build for production
npm run build

# Preview production build
npm run preview

# Run linter
npm run lint

# Run tests
npm test

# Generate test coverage report
npm run coverage

Features

Core Features (Phase 1-3: MVP)

• ✅ Real-time Timer: Accurate time tracking with ±2 second precision
• ✅ Multi-Work Order Support: Switch between work orders mid-timer without data loss
• ✅ Machine Selection: Track which resource is used for each time entry
• ✅ Comprehensive Audit Trail: Full time entry history with employee, machine, work order, and operation details
• ✅ Persistent Storage: IndexedDB with localStorage fallback for offline capability

Administrative Features (Phase 4-5)

• ✅ Machine Management: Create, edit, and manage machine inventory
• ✅ Employee Management: Employee CRUD with badge number tracking and soft-delete for historical data retention
• ✅ Work Order Management: Create and manage work orders with status transitions (active → paused → completed)
• ✅ Operation Management: Break down work orders into specific operations with sequence numbering
• ✅ Multi-Page Navigation: Seamless navigation between operator and admin interfaces

Documentation

• User Guide — How to use the time tracking system (operators and admins)
• Developer Guide — Technical architecture and code patterns
• Database Schema — Entity relationships and database structure
• Deployment Guide — Production deployment and monitoring
• Quick Start (Specification) — Integration scenarios from requirements

Technical Stack

Component	Technology
Frontend	Vanilla HTML5, CSS3, ES2020+ JavaScript
Build Tool	Vite 5.4.21
Database	SQLite (via sql.js WebAssembly)
Storage	IndexedDB + localStorage
Testing	Vitest 1.0.0 + jsdom
Linting	ESLint 8.54.0 (complexity ≤5, lines ≤50)

Project Structure

src/
├── index.html                      # Application entry point
├── index.css                       # Global styles (800+ lines)
├── index.js                        # App initialization
├── db/
│   ├── database.js                 # SQLite wrapper
│   ├── storage-adapter.js          # IndexedDB + localStorage
│   └── schema.sql                  # Database schema
├── services/
│   ├── employee-service.js         # Employee CRUD + lifecycle
│   ├── machine-service.js          # Machine CRUD
│   ├── workorder-service.js        # Work order CRUD + status
│   ├── operation-service.js        # Operation CRUD within WO
│   ├── timer-service.js            # Timer state machine
│   ├── timeentry-service.js        # Time entry creation + audit
│   ├── validation-service.js       # Input validation
│   └── event-system.js             # CustomEvent emitter
├── components/
│   ├── dropdown-selector.js        # Reusable dropdown
│   ├── timer-display.js            # Timer UI (MM:SS/HH:MM:SS)
│   ├── action-button.js            # Play/Pause/Stop buttons
│   ├── error-display.js            # Error messages
│   └── navigation.js               # Multi-page navigation
├── pages/
│   ├── operator-page.js            # Main operator UI
│   ├── admin-machines-page.js      # Machine admin UI
│   ├── admin-employees-page.js     # Employee admin UI
│   ├── admin-workorders-page.js    # Work order admin UI
│   └── admin-operations-page.js    # Operation admin UI
└── utils/
    ├── id-generator.js             # UUID generation
    ├── date-utils.js               # Date/time utilities
    └── error-handlers.js           # Error formatting

Key Metrics

Metric	Target	Status
ESLint Compliance	0 errors	✅ PASS
Build Size	<30 kB (gzip)	✅ 26.84 kB
Timer Accuracy	±2 seconds	✅ PASS
Database Query Speed	<100ms	✅ PASS
Code Complexity	Max 5 per function	✅ PASS
Function Length	Max 50 lines	✅ PASS

Development

Code Quality Standards

• ESLint: Enforces complexity ≤5 per function, lines ≤50 per function
• Style Guide: ES2020+ conventions, semantic HTML5, CSS3 Grid/Flexbox
• Testing: Contract tests for all service APIs, integration tests for workflows
• Accessibility: ARIA labels, semantic HTML, keyboard navigation (Tab, Enter, Esc)

Common Commands

# Development
npm run dev          # Start dev server with hot reload
npm run lint         # Check code quality
npm run build        # Production build
npm run preview      # Preview production build locally

# Testing
npm test            # Run all tests
npm run coverage    # Generate coverage report
npm test:ui         # Run tests with browser UI

# Maintenance
npm run lint -- --fix  # Auto-fix lint violations

Adding New Features

1. Define in specification (specs/001-time-tracking/spec.md)
2. Plan tasks (specs/001-time-tracking/tasks.md)
3. Create service if new entity (follow src/services/ patterns)
4. Implement page/component (follow decomposition patterns in existing code)
5. Add contract tests (validate service API matches spec)
6. Add integration tests (validate end-to-end workflow)
7. Verify ESLint: npm run lint
8. Build and verify: npm run build

Performance

• Database Queries: All queries optimized with indexes; <100ms typical execution
• Timer Accuracy: Uses Date.now() for millisecond precision; maintains ±2 second accuracy over 5+ minute durations
• Build Artifacts:
  • JavaScript: 102.75 kB uncompressed, 26.84 kB gzip
  • CSS: 12.33 kB uncompressed, 2.80 kB gzip
  • HTML: 0.43 kB
• Storage: Entire application fits in browser cache; no network requests after initial load

Browser Support

Browser	Min Version	Status
Chrome	90+	✅ Full
Firefox	88+	✅ Full
Safari	14+	✅ Full
Edge	90+	✅ Full

Deployment

Local Testing

npm run preview  # Serves dist/ on http://localhost:4173

Production Hosting

• Static file hosting only (no backend required)
• Serve dist/ directory
• Enable gzip compression on web server
• Set cache headers for assets (1 year for versioned files)
• See Deployment Guide for detailed setup

Offline Capability

• Application works offline using IndexedDB
• Automatic sync when connectivity restored
• No data loss during disconnection

Testing

Unit Tests

npm test               # Run all tests
npm run coverage       # Generate coverage report

Manual QA Checklist

Operator Flow:

• Can start/pause/stop timer without lag
• Timer persists across browser tab switches
• Changing work order mid-timer doesn't stop timer
• Time entry saves with all correct fields
• Changing machine/work order doesn't lose elapsed time

Admin Flow:

• Can create/edit/delete all admin entities
• Unique constraints enforced (name, badge, sequence)
• Changes reflect immediately in operator dropdowns
• Soft-delete hides employees from operator but preserves history

Troubleshooting

Timer Not Counting

• Check browser DevTools Console for errors
• Verify JavaScript enabled
• Try refreshing page
• Clear localStorage: localStorage.clear() in DevTools Console

Data Not Saving

• Check IndexedDB quota not exceeded
• Verify browser storage not full
• Check DevTools Application → IndexedDB for data presence
• Try fallback to localStorage (automatic on quota exceeded)

Build Errors

# Clear build cache
rm -r dist/ node_modules/

# Reinstall and rebuild
npm install
npm run build

Contributing

Code Review Checklist

• Follows ESLint rules (0 errors, 0 warnings)
• Functions complexity ≤5, length ≤50 lines
• Includes contract/integration tests
• No console.log in production (use error-handlers.js)
• Semantic HTML with ARIA labels
• Keyboard accessible (Tab, Enter, Esc)

License

See LICENSE file for terms.

Support

For issues, feature requests, or questions:

1. Check the User Guide
2. Review Troubleshooting section
3. Check Developer Guide for implementation questions
4. Review existing GitHub Issues

---

Last Updated: November 12, 2025
Version: 1.0.0
Status: Production Ready ✅