OpenClockwork is a mobile-first, self-hostable time-and-attendance system for small and mid-sized organisations. Its domain model focuses on German working-time workflows while keeping deployment and integration under the operator's control.
Project status: Stable. Published versions follow semantic versioning and include release notes and documented upgrade steps. The capabilities below are implemented and covered by automated tests.
The responsive web application can be installed as a Progressive Web App and provides role-aware navigation for employees, managers, and HR administrators.
| Capability | What it provides |
|---|---|
| Personal dashboard | Vacation balance, overtime account, and detected core-time violations at a glance |
| Clock in and out | PWA-based time booking with optional GPS coordinates and recent-booking history |
| Direct daily-block booking | With per-employee HR permission, book the contractual daily target as one completed, directly approved block |
| Core-time violation details | Booking-page list with violation date, affected core-time window, violation type, boundary, and uncovered minutes |
| Project and service-order booking | Book time to assigned active projects; active service orders become the required booking level |
| Activity per booking | Record a customer-facing description of the work performed |
| Retroactive booking changes | Change a booking target or activity after the fact, including approved entries |
| Entry splitting | Split a closed entry at a chosen time, for example when switching projects mid-day |
| Retroactive range booking | Assign a past interval to a project; the API validates complete clocked-time coverage and splits existing entries as needed |
| Automatic break accounting | Statutory break deduction after six and nine hours |
| Time accounts | Calculated target hours, actual hours, overtime, and opening balances |
| Annual calendar | Year overview for vacation, home office, special leave, sickness, training, and flextime days |
| Requests | Vacation, home-office, special-leave, and time-adjustment requests |
| Half-day vacation | First-day and last-day half-day selection with calculated leave usage |
| Vacation balance preview | Available, approved, and submitted leave shown while creating a request |
| Request lifecycle | View requests, workflow state, decisions, and cancellation state |
| Substitute inbox | Accept or decline requests when named as a substitute |
| Absence records | Record sickness, training, and flextime days |
| Multilingual interface | German and English UI with a persistent language switcher on the login screen and in the application header |
| Role-aware mobile navigation | Bottom navigation plus an overflow menu that keeps manager and HR areas, including approval inboxes, reachable on phones |
| Theme preference | Light, dark, or operating-system theme |
OpenClockwork ships with a German and English user interface across the core employee, manager, and HR workflows. The selected language is stored in the browser.
- Central translation catalogue shared by navigation, pages, dialogs, actions, validation hints, and empty states
- Localised workflow states, request and absence types, roles, time models, and core-time violation labels
- Locale-aware date and date-time formatting
- Correct German labels for technical workflow values such as
Approved,Pending,PendingManager, andTimeApproval - Extensible catalogue architecture so another language can be added and maintained in one central location
OpenClockwork models approvals as explicit workflow states instead of a single approved/rejected flag.
Employee submits
-> optional substitute confirmation
-> manager approval
-> optional HR confirmation
-> approved
- Manager and HR approval inboxes, reachable from desktop and mobile navigation
- Substitute acceptance and rejection
- Manager approval, rejection, and return-for-correction
- HR confirmation and rejection
- Bulk approval and rejection
- Request cancellation
- Audit trail of workflow events
- Special approval flag for bookings and time adjustments outside configured working frames
- Direct daily blocks bypass the request workflow only when HR has enabled the option for that employee; conflicting or out-of-policy blocks are rejected
- Request attachments with local-filesystem or Azure Blob storage adapters
| Capability | What it provides |
|---|---|
| Employee management | Create, edit, deactivate, reactivate, and reset employee passwords |
| Daily-block permission | Enable or disable direct daily-target block booking for each employee |
| Roles | Employee, Manager, and HRAdmin access levels |
| Time models | Full-time, part-time, trust-based working time, and flextime |
| Work schedules | Configurable working days, permitted booking frames, and multiple core-time windows |
| Schedule assignment | Assign schedules to individual employees or bulk-assign by time model |
| Project management | Projects structured by service orders, with active/inactive lifecycles and deletion protection once time is booked |
| Project assignment matrix | Employee-by-project matrix controlling who may book time to each project |
| Plan-versus-actual tracking | Plan hours per project and service order, with progress indicators and overbooking warnings |
| Customer activity reports | Per-project report of dates, employees, service orders, hours, and activities, including period filters and CSV export |
| Working-time reports | HR-only, project-independent overview of start, end, break, gross, and net time with CSV export |
| Leave allowances | Base leave, carry-over, adjustments, expiry dates, and adjustment reasons |
| German public holidays | Configurable German-state holiday calendars used in vacation calculations |
| Absence administration | Record and review sickness, training, and flextime entries for employees |
| Approval operations | Role-aware manager and HR inboxes with bulk actions and workflow history |
Projects combine employee assignments, service orders, planned hours, actual bookings, and customer-facing activity reports in one administrative workflow.
- Create and maintain projects with project numbers, titles, and descriptions
- Assign employees and control which projects they may book time to
- Structure projects into service orders with separate active/inactive states
- Maintain PLAN hours and compare them with booked IST hours at project and service-order level
- Review progress indicators and identify approaching or exceeded budgets
- Edit, deactivate, or delete service orders, with protection for referenced bookings
- Open detailed project evaluations and export customer activity reports
Project-independent working-time reporting is always available to HR administrators alongside project evaluations. It includes closed, non-rejected bookings regardless of whether the project feature is used. Its CSV exports contain employee names and working-time data and must therefore be handled as personal data under the organisation's retention and access policies.
OpenClockwork makes working-time rules visible in code and testable as domain logic. It is not a substitute for legal advice or organisation-specific policy configuration.
- Statutory break calculation
- Target-versus-actual hour accounting, including daily targets derived from weekly hours and the configured number of working days
- Configurable working days and core-time windows
- Direct daily blocks validated against public holidays, absences, active requests, existing time entries, and permitted working-time frames
- Detection of core-time violations
- Special approval handling for out-of-frame bookings
- Vacation calculation using working days and public holidays
- Carry-over expiry processing
- Multi-stage approval workflows
- JWT access and refresh authentication for interactive users
- Role-based endpoint protection for employee, manager, and HR operations
- Dedicated API-key protection for machine-to-machine ERP exports
- Authenticated Socket.IO connections
- Password hashing and refresh-token rotation
- Request workflow history for approval decisions
- Pluggable attachment storage using the local filesystem or Azure Blob Storage
OpenClockwork provides technical controls, but operators remain responsible for their deployment security, retention rules, access policies, and legal compliance.
The NestJS REST API is documented through the generated OpenAPI specification
committed at apps/api/openapi.json.
- Paginated ERP time-entry export with project, service-order, and activity references
- Authenticated endpoints for reading the current employee's daily-block option and creating a directly approved daily block
- Socket.IO events for real-time client refreshes
- Health endpoint for deployment checks
- Generated TypeScript client types for the web application
- Language-neutral API values translated centrally by the web application
- Dockerfiles for API and web applications
- Docker Compose configurations for local development and self-hosting
- PostgreSQL with versioned Prisma migrations
- Seed data for local evaluation
- Azure Container Apps reference infrastructure using Bicep
- Azure Key Vault and managed-identity integration
- Azure Blob Storage support for attachments
- Nx workspace with lint, type-check, build, unit, integration, and browser test targets
- Stable releases are published through GitHub Releases with versioned API and web container images.
- Database changes are delivered as forward-only Prisma migrations and tested against an existing database before merge.
- Production deployments must be backed up and upgraded according to
UPGRADING.md; destructive reset commands are never part of an upgrade. - Operators remain responsible for validating organisation-specific labour agreements, payroll integrations, security requirements, backups, monitoring, and operating procedures.