Skip to content

Sub-Domain Blueprint: Operations Personnel

Domain: Operations (maintenance, security, personnel, services) Logical Sub-Domain: Personnel (Staff & Shifts) Physical Packages: @sd/mod-operations/personnel Related Documents: Data Definition Context: This document defines the Employment Structure, Shift Scheduling, and Time Tracking for the workforce. Status: Stable (v2.5)

1. Mandate

The Personnel Sub-Domain is the HR Engine for Operations. It distinguishes between Direct Employees (HOA Payroll) and Contracted Staff (Vendor Payroll) while providing a unified interface for Scheduling and Access Control. It enforces the "Three-Tier" employment model: Employee, Contractor, Concessionaire.

2. Capabilities

Capability Description Component
Onboarding Creating Staff Profiles linked to Registry Identities and Employers. onboardPersonnel
Shift Management Defining duty rosters by Role and Location. Shift
Time & Attendance Real-time Clock In/Out with Geolocation. TimecardEntry
Hierarchy Defining Reporting Lines (supervisorId). PersonnelProfile

3. Process Models

A. Staff Onboarding (Contractor)

Happy Path: Security Guard from "SafeGuard Inc".

sequenceDiagram
    participant Admin
    participant Service as PersonnelService
    participant Registry as Directory
    participant DB as Firestore

    Admin->>Service: onboard(identity="user123", employer="SafeGuard", role="Guard")
    Service->>Registry: validate(identityId)
    Service->>DB: createProfile({ type: "contractor", employer: "SafeGuard" })
    Service-->>Admin: Success

B. Time Attendance

Happy Path: Guard starts shift.

sequenceDiagram
    participant App
    participant Service as PersonnelService
    participant DB as Firestore

    App->>Service: clockIn(id="guard1", loc="Main Gate")
    Service->>DB: checkActiveTimecard()
    Service->>DB: create({ start: NOW, status: "active" })
    Service-->>App: Clocked In

4. State Machines

Employment Status

stateDiagram-v2
    [*] --> Active: Onboarded
    Active --> OnLeave: Sick/Vacation
    Active --> Suspended: Disciplinary
    Active --> Terminated: Offboarded
    Terminated --> [*]

5. Interface Definitions

PersonnelService

  • onboardPersonnel(data): Promise<Profile>
  • scheduleShift(shift): Promise<Shift>
  • clockIn(id, loc): Promise<Timecard>
  • clockOut(id, loc): Promise<Timecard>

6. Changelog

Date Author Description Reference
2026-01-24 Antigravity Initial creation Implementation Plan