Athenian HR Suite for WooCommerce

Developer starting point

This baseline documents HR Suite code and operational seams. It does not claim that an employee record, time entry, schedule, timesheet, or payroll-related outcome has been exercised.

4. Administrative Workflow

Athenian HR Dashboard

The main dashboard provides quick links to the core HR modules:

• Employees
• Scheduling
• Time Clock
• Timesheets
• Onboarding
• Settings

It also displays the available shortcodes and recommends creating an Employee Portal page using [ath_hr_portal].

Employees Screen

The Employees screen allows an HR manager to:

1. Select an existing WordPress user.
2. Enter or update the employee job title.
3. Set the employee status.
4. Save the employee profile into the HR employee table.
5. Review recent employee records in a directory table.

This workflow intentionally keeps the first version simple while preserving a database structure that can later support supervisor assignment, location assignment, hire date, termination date, phone number, and richer metadata.

Scheduling Screen

The Scheduling screen allows authorized managers to:

1. Select an employee or leave the shift unassigned.
2. Enter a start date/time.
3. Enter an end date/time.
4. Add optional notes.
5. Create a scheduled shift.
6. Review recent shifts.

The plugin validates that the end time is after the start time and stores timestamps using the site timezone.

Time Clock Screen

The admin Time Clock page gives authorized users a simple clock status card and clock-in/clock-out buttons. It reuses the same REST-powered time clock behavior used by the frontend application.

Timesheets Screen

The Timesheets screen currently focuses on exporting raw time entries. It defaults to the current Monday-Sunday week and lets managers choose a custom start and end date before downloading CSV output.

Onboarding Screen

The Onboarding screen documents the intended MVP expansion path. The required tables are already installed, but the CRUD interface and employee task list are marked as the next implementation step.

Settings Screen

The Settings screen summarizes current MVP assumptions:

• Weekly pay period is Monday-Sunday.
• Employee portal uses WordPress REST nonces.
• Data is stored in custom tables for reporting performance.
• Roles created on activation are ath_hr_employee, ath_hr_supervisor, and ath_hr_manager.

---

5. Frontend Employee Workflow

Employee Portal

The [ath_hr_portal] shortcode renders a tabbed employee portal with three primary tabs:

• Time Clock
• Schedule
• Timesheet

The active tab is controlled through the ath_hr_tab query parameter.

Time Clock

Employees can view their current clock status and use buttons to clock in or clock out. The frontend JavaScript calls the plugin’s REST API and refreshes the displayed status after each action.

Clock status displays either:

• Clocked In with the clock-in timestamp, or
• Clocked Out with a note that the employee is not currently clocked in.

Schedule

The schedule shortcode displays up to 100 shifts assigned to the logged-in user. The current table includes:

• Start
• End
• Status

If no shifts are assigned, the employee sees a clean empty-state message.

Timesheet

The timesheet shortcode loads the current weekly timesheet summary through REST. It displays:

• Pay period start date
• Pay period end date
• Timesheet status
• Total hours
• Number of included entries

---

6. Technical Architecture

Core Bootstrap

The plugin is bootstrapped through athenian-hr-suite.php, which defines version/path constants, registers the autoloader, registers activation/deactivation hooks, and initializes the plugin on plugins_loaded.

Important constants:

ATH_HR_SUITE_VERSION
ATH_HR_SUITE_FILE
ATH_HR_SUITE_DIR
ATH_HR_SUITE_URL

Namespacing & Autoloading

The plugin uses the namespace:

Athenian\HRSuite

The custom autoloader maps namespaced classes under Athenian\HRSuite\ to files inside the includes/ directory.

Main Plugin Class

The main class is:

Athenian\HRSuite\Plugin

It is responsible for:

• Registering shortcodes.
• Loading admin menus.
• Enqueuing admin assets.
• Enqueuing frontend assets.
• Registering REST routes.
• Installing capabilities and roles on activation.
• Installing database schema on activation.

Admin Layer

Admin functionality is organized under:

includes/Admin/Menu.php
includes/Admin/Pages/

Admin pages include:

• Dashboard.php
• Employees.php
• Scheduling.php
• TimeClock.php
• Timesheets.php
• Onboarding.php
• Settings.php

Domain Layer

Business logic is organized under:

includes/Domain/

Current domain services:

• TimeEntries.php
• Timesheets.php

The domain layer handles clock-in/clock-out records, open-entry lookups, period-based time entry lists, total duration calculations, weekly timesheet generation, and CSV export.

REST Layer

REST routes are registered under the namespace:

ath-hr/v1

The route class is:

Athenian\HRSuite\Rest\Routes

Frontend Layer

Frontend functionality is rendered through shortcode classes under:

includes/Shortcodes/

Frontend styles and scripts are loaded from:

assets/app/app.css
assets/app/app.js

Admin styles and scripts are loaded from:

assets/admin/admin.css
assets/admin/admin.js

---

7. Database Schema

The plugin creates custom tables using dbDelta() on activation. Table names are prefixed with the site’s WordPress table prefix and ath_hr_.

Installed Tables

| Table | Purpose | |---|---| | ath_hr_employees | HR employee profiles linked to WordPress users. | | ath_hr_locations | Work locations with timezone and address fields. | | ath_hr_roles | HR/work roles, including display color and metadata. | | ath_hr_shifts | Scheduled employee shifts. | | ath_hr_time_entries | Clock-in/clock-out records and source metadata. | | ath_hr_timesheets | Weekly timesheet records by user and period. | | ath_hr_onboarding_templates | Reusable onboarding template definitions. | | ath_hr_onboarding_tasks | Tasks belonging to onboarding templates. | | ath_hr_onboarding_assignments | Task assignments for individual users. | | ath_hr_acknowledgements | Policy acknowledgement records by user and policy key. |

Default Seed Data

On first activation, the schema installer seeds:

• A default location named Default Location using the current WordPress timezone.
• A default HR role named General with color #4f46e5.

Employee Table Fields

The employee table supports:

• WordPress user linkage
• Employment status
• Job title
• Location assignment
• Supervisor assignment
• Hire date
• Termination date
• Phone number
• Extensible metadata
• Created/updated timestamps

Shift Table Fields

The shift table supports:

• Assigned user
• Role assignment
• Location assignment
• Start/end date-times
• Shift status
• Notes
• Creator user ID
• Created/updated timestamps

Time Entry Table Fields

The time entry table supports:

• User ID
• Shift ID
• Location ID
• Role ID
• Clock-in timestamp
• Clock-out timestamp
• Break metadata placeholder
• Source
• IP address
• User agent
• Created/updated timestamps

Timesheet Table Fields

The timesheet table supports:

• User ID
• Period start
• Period end
• Status
• Submitted timestamp
• Approved timestamp
• Approving user
• Totals metadata
• Created/updated timestamps

---

8. Roles & Capabilities

Athenian HR Suite creates dedicated HR capabilities and assigns them to purpose-built roles.

Capabilities

| Capability | Purpose | |---|---| | ath_hr_view_self | Allows employees to view/use their own portal tools. | | ath_hr_manage_employees | Allows management of HR employee records. | | ath_hr_manage_schedules | Allows schedule creation and management. | | ath_hr_manage_time | Allows time clock management and exports. | | ath_hr_manage_onboarding | Allows onboarding management. | | ath_hr_manage_settings | Allows HR settings access. | | ath_hr_approve_timesheets | Allows timesheet approval/export access. |

Created Roles

| Role | Purpose | Included Capabilities | |---|---|---| | ath_hr_employee | Baseline employee role. | read, ath_hr_view_self | | ath_hr_supervisor | Supervisor role for schedules and approvals. | read, ath_hr_view_self, ath_hr_manage_schedules, ath_hr_approve_timesheets | | ath_hr_manager | HR manager role. | All HR capabilities plus read |

The plugin also grants all HR capabilities to the WordPress administrator role on activation.

---

9. Shortcodes

[ath_hr_portal]

Renders the full employee portal with tabbed access to time clock, schedule, and timesheet views.

[ath_hr_clock]

Renders the standalone time clock interface.

[ath_hr_schedule]

Renders the logged-in employee’s assigned shifts.

[ath_hr_timesheets]

Renders the logged-in employee’s current weekly timesheet summary.

---

10. REST API Endpoints

GET /wp-json/ath-hr/v1/me/clock

Returns the logged-in user’s current clock status.

Response includes:

• user_id
• open entry data, if currently clocked in
• Current server/site time

POST /wp-json/ath-hr/v1/me/clock-in

Creates a new open time entry for the logged-in user unless one already exists.

Optional parameters:

• shift_id
• location_id
• role_id

Stored metadata includes source, IP, and user agent.

POST /wp-json/ath-hr/v1/me/clock-out

Closes the logged-in user’s current open time entry by setting clock_out.

GET /wp-json/ath-hr/v1/me/timesheet

Ensures a current weekly timesheet exists and returns current period totals.

Response includes:

• Timesheet ID
• Period start
• Period end
• Status
• Total seconds
• Total hours
• Entry count

GET /wp-json/ath-hr/v1/admin/export/time-entries

Exports raw time entries as CSV for a date range.

Required parameters:

• start in YYYY-MM-DD format
• end in YYYY-MM-DD format

Requires time-management permission or administrator access.

---

11. Security & Permissions

The plugin includes a practical security foundation for the MVP:

• Admin pages check HR-specific capabilities and fall back to manage_options for administrators.
• REST endpoints require logged-in users and capability checks.
• REST requests use WordPress REST nonces through localized frontend/admin scripts.
• Admin forms use WordPress nonces.
• User-submitted fields are sanitized using WordPress functions such as sanitize_key(), sanitize_text_field(), and esc_*() output escaping.
• The CSV export validates date input format before querying.
• Time clock endpoints only act on the current logged-in user for employee-facing routes.

---

15. Implementation Notes

Activation Behavior

On activation, the plugin:

1. Installs custom HR database tables.
2. Seeds a default location and role if none exist.
3. Installs HR capabilities.
4. Creates or updates HR-specific roles.
5. Flushes rewrite rules.

Deactivation Behavior

On deactivation, the plugin flushes rewrite rules. It does not remove data tables or role capabilities, which is appropriate for preserving HR records unless a dedicated uninstall routine is later added.

Time Handling

The plugin uses WordPress site time through current_time() and wp_timezone(). Weekly periods are currently fixed to Monday-Sunday.

Duplicate Clock-In Protection

When a user clocks in, the domain service first checks for an existing open entry. If one exists, the plugin returns that entry ID instead of creating a duplicate.

Timesheet Calculation

Current timesheet totals are computed from completed entries where both clock-in and clock-out values are present and the clock-out time is later than or equal to the clock-in time.

---

18. Technical File Map

athenian-hr-suite.php
includes/
  Autoloader.php
  Plugin.php
  Admin/
    Menu.php
    Pages/
      Dashboard.php
      Employees.php
      Scheduling.php
      TimeClock.php
      Timesheets.php
      Onboarding.php
      Settings.php
  DB/
    Schema.php
  Domain/
    TimeEntries.php
    Timesheets.php
  Rest/
    Routes.php
  Shortcodes/
    Portal.php
    Clock.php
    Schedule.php
    Timesheets.php
  Util/
    Time.php
assets/
  admin/
    admin.css
    admin.js
  app/
    app.css
    app.js

---