Time Clock Manager

Time Clock Manager is a small desktop support utility that wraps a SwipeClock-hosted clock-in and clock-out workflow in a deliberately simple GUI.

The project began with a practical support problem: the official workflow was unreliable enough that users could not always tell whether an action had been accepted, and support staff had very little local evidence when something went wrong. The goal was not to automate attendance on a schedule. The goal was to make a manual user action easier to complete, safer to repeat, and easier to diagnose.

What it demonstrates

• Manual-confirmation desktop workflow built with Tkinter
• Authentication and punch requests separated from the GUI
• Credentials stored through the operating system's keyring instead of a plaintext file
• Deployment-specific values configured outside the source code
• HTTP timeouts, status validation, and explicit failure handling
• Local audit history that distinguishes accepted requests from failed attempts
• Duplicate-action warnings based on the last successful action
• A refactor from a working single-file prototype into testable components

How it works

1. The user stores their username and password through the application.
2. The password is delegated to the operating system's credential manager through keyring.
3. A manual Clock In or Clock Out action requests a short-lived JWT from the configured service.
4. The selected punch request is submitted only after user confirmation.
5. The application records success only after the HTTP request is accepted.
6. A local CSV history provides an audit trail without storing the password or JWT.

Project structure

src/time_clock_manager/
|-- app.py          # Tkinter interface and user workflow
|-- client.py       # Authentication, connectivity, and punch requests
|-- config.py       # Deployment-specific runtime configuration
|-- credentials.py  # Operating-system keyring integration
|-- history.py      # Local audit history and state restoration
`-- __main__.py     # Command-line entry point

tests/
|-- test_client.py
`-- test_history.py

Installation

py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .

Tkinter ships with normal Windows Python installations. The two external dependencies are requests and keyring.

Configuration

Deployment-specific identifiers are intentionally not committed.

Set the white-label host in PowerShell:

$env:TCM_WHITE_LABEL_HOST = "your-deployment.payrollservers.us"
time-clock-manager

Other supported environment variables:

TCM_BASE_URL
TCM_WHITE_LABEL_HOST
TCM_SITE
TCM_TIMEOUT_SECONDS

The same values can be passed at launch:

time-clock-manager `
    --white-label-host "your-deployment.payrollservers.us" `
    --timeout 10

Running tests

python -m unittest discover -s tests -v

The tests mock network traffic. They do not contact a payroll service or submit a punch.

What is intentionally not planned

• Scheduled or unattended clock-in and clock-out actions
• Background automation based on preset times
• Support for unrelated time-clock products
• Claiming this unofficial web workflow is a stable public API

Status and limitations

This is an independent portfolio project and is not affiliated with SwipeClock, TimeWorksPlus, or any payroll provider. It uses a web workflow that may change without notice. Use it only with an account and deployment you are authorized to access, and confirm that its use is permitted by the relevant employer and service terms.

No software license is applied yet. Ownership and redistribution rights should be confirmed before selecting one.