Executive Summary
Cross-platform workforce management for SMEs without directory services. Local-only authentication, single codebase deployment, self-hosted infrastructure.
System Overview
WorkForce Pro is a cross-platform workforce management solution for SMEs that operate without directory services. Authentication is handled entirely in-app via email, phone number, or trusted-device token — no dependency on Active Directory, Azure AD, or domain-joined machines.
Five core capabilities: employee scheduling, time tracking, task management, organisation chart, and integrated leave & roster handling. A single React Native codebase compiles to iOS, Android, and web.
Technology Decisions
Single codebase to iOS, Android, Web. Reduces maintenance overhead.
RESTful API with compile-time type safety. Runs on Node 20+.
Relational integrity for hierarchical employee data. No licensing cost.
Password hashing (cost 12), stateless JWT sessions, optional device binding.
Admin, Manager, Employee — plain-English permission model.
Technology Stack
Deliverables
System Architecture
Three-tier architecture with a shared API backend, single-codebase frontend, and self-hosted database. No external identity providers.
Architecture Diagram
Client layer, API layer, data layer
Windows 10+
iOS 15+
Android 8+
TLS Termination
bcrypt + Device Tokens
REST / WebSocket
Background Jobs
Relational Integrity
Small Deployments
Job Queue
Avatars, Documents
API Design
RESTful endpoints with versioning
# Authentication
POST /api/v1/auth/register # Sign up (email/phone)
POST /api/v1/auth/login # Sign in
POST /api/v1/auth/refresh # Refresh JWT
POST /api/v1/auth/device # Register trusted device
# Employees
GET /api/v1/employees # List (paginated)
POST /api/v1/employees # Create (admin)
PUT /api/v1/employees/:id # Update
# Shifts & Roster
GET /api/v1/shifts # By week/month
POST /api/v1/shifts # Assign shift
POST /api/v1/shifts/publish # Publish roster
# Time Tracking
POST /api/v1/timesheet/clock-in
POST /api/v1/timesheet/clock-out
# Tasks
GET /api/v1/tasks # By assignee/status
PUT /api/v1/tasks/:id # Update status
# Leave
POST /api/v1/leave # Submit request
PUT /api/v1/leave/:id/approve # Approve
# Org Chart
GET /api/v1/org/tree # Full hierarchyArchitectural Principles
1. Single Codebase, Three Targets
React Native with Expo compiles to native iOS, native Android, and web. One team, one codebase, one set of features.
2. Stateful Auth, Stateless API
JWT access tokens (15-min TTL) + refresh tokens (7-day TTL, stored in Redis). Device tokens allow trusted-device login.
3. Offline-First Mobile
SQLite local cache on mobile devices. Clock-in/out works offline; data syncs when connectivity returns.
4. Horizontal Scalability
Stateless API containers behind Nginx. Redis for shared session state. Docker Compose for single-server deployment.
5. Self-Hosted, No Vendor Lock-in
Entire stack runs on a single Windows or Linux server. No cloud subscription required. All data stays on-premises.
Request Flow — Clock In/Out Example
# 1. Employee taps "Clock In" on mobile app
POST /api/v1/timesheet/clock-in
Headers: { Authorization: "Bearer eyJhbG..." }
Body: { employeeId: 4, timestamp: "2026-08-20T06:00:12Z", device: "iPhone-AB12" }
# 2. Auth middleware verifies JWT
-> JWT verified, userId=4, role="employee"
# 3. Permission check
-> Yes (self-service) or Admin/Manager override
# 4. Core API writes to PostgreSQL via Prisma
INSERT INTO time_entries (employee_id, clock_in, device_id)
VALUES (4, '2026-08-20T06:00:12Z', 'iPhone-AB12')
# 5. WebSocket push to admin dashboard
WS -> { event: "clock_in", employeeId: 4, name: "David Kim" }
# 6. Response to client
200 OK { success: true, message: "Clocked in at 06:00" }Authentication & Security
Application-native authentication — email, phone, or trusted-device. No Active Directory, no Azure AD, no SSO required.
Sign-up & Sign-in Flow
Complete authentication journey — from first sign-up to authenticated session
Email-Based Authentication
The primary sign-up method. User enters their email address and a password. The system sends a 6-digit verification code to confirm ownership.
Password Security
Passwords are hashed with bcrypt (cost factor 12) — never stored in plain text. Minimum 8 characters, enforced by the API.
Phone-Based Authentication
For staff without email access (e.g., warehouse workers). Phone number + SMS OTP verification. Integrates with any SMS gateway (Twilio, Vonage, or local provider).
Works Offline Too
Trusted devices can be pre-registered by an admin, allowing clock-in/out without re-authentication each shift.
Device-Based Authentication
For shared or dedicated devices (e.g., wall-mounted kiosks, tablets). Admin registers a device with a unique token. The device authenticates automatically on launch.
Security Safeguard
Device tokens are revocable by admin at any time. Lost device = instant revoke, no data exposure.
Security Measures
Role & Permission Matrix
Three roles — plain English, no technical jargon. Administrators can customise permissions per role.
| Capability | Admin | Manager | Employee |
|---|---|---|---|
| View own schedule | |||
| Clock in / out | |||
| View own timesheet | |||
| Submit leave request | |||
| View team schedule | Team | × | |
| Assign shifts | Team | × | |
| Approve / reject leave | Team | × | |
| Create / assign tasks | Team | × | |
| View org chart | |||
| Add / edit employees | × | × | |
| Manage roles & permissions | × | × | |
| Configure system settings | × | × | |
| View reports & analytics | Team | Self | |
| Export data (CSV/PDF) | Team | × |
Prototype: Login / Sign-up
Application-native authentication screen — choose email, phone, or device-based sign-in.
WorkForce Pro
Sign in to your workspace
Admin Approval Required
New accounts must be approved by an administrator before activation.
Prototype: Admin Dashboard
Real-time overview — staff on duty, shift coverage, pending approvals, and task progress.
Weekly Attendance Rate
Percentage of scheduled staff who clocked in on time
Task Distribution
Tasks by status
Recent Activity
Pending Approvals
Prototype: Scheduling & Roster
Weekly roster grid — click any shift badge to cycle through Morning, Evening, Night, and Off.
Interactive Prototype
Click any shift badge in the roster grid above to cycle through shift types. This demonstrates the drag-and-drop roster editing capability.
Prototype: Time Tracking
Digital clock-in/out with live timer, timesheet view, and exportable reports.
Live Clock
Tap to clock in or out
Today's Clock-ins
Live staff activity
Weekly Timesheet
All employees · Aug 18-24, 2026
| Employee | Mon | Tue | Wed | Thu | Fri | Sat | Sun | Total |
|---|---|---|---|---|---|---|---|---|
| Sarah Chen | 8h 00m | 8h 05m | 7h 55m | 8h 00m | 8h 10m | -- | -- | 40h 10m |
| James Okafor | 8h 02m | 8h 00m | 7h 58m | 8h 01m | 8h 00m | -- | -- | 40h 01m |
| David Kim | 8h 00m | 7h 45m | 8h 15m | 7h 50m | 8h 05m | -- | -- | 39h 55m |
| Priya Sharma | 8h 00m | -- | 8h 00m | 8h 00m | 8h 00m | -- | -- | 32h 00m |
| Emma Rodriguez | 8h 00m | 8h 00m | -- | 8h 00m | 8h 00m | -- | -- | 32h 00m |
Prototype: Task Management
Kanban board — drag cards between columns to update status. Filter by assignee, priority, or tag.
Interactive Prototype
Drag any task card between the To Do, In Progress, In Review, and Done columns. The column counts update automatically.
Prototype: Organisation Chart
Visual hierarchy tree — click any node to view employee details. Auto-generated from manager_id relationships.
Departments
Hierarchy Stats
How It Works
The org chart is dynamically generated from the manager_id field on each employee record.
When an admin changes someone's manager, the tree redraws instantly — no manual chart editing needed.
Click any node in the chart above to see a quick employee summary.
Prototype: Leave Management
Calendar view with leave overlays, plus a sortable approval queue. Integrated with the roster for conflict detection.
Leave Calendar — August 2026
Colour-coded by status
Leave Balances
Leave Requests
Approve or reject pending requests — roster conflicts are flagged automatically
| Employee | Type | Dates | Days | Reason | Status |
|---|
Prototype: Employee Directory
Full employee list with contact details, department, status, and role assignment.
Data Model (ERD)
Relational schema covering employees, shifts, tasks, leave, time entries, and organisational hierarchy.
Entity Relationship Diagram
8 core tables with foreign key relationships
Key Relationships
Feature Backlog
Prioritised milestones — development can start immediately after approval. Each milestone is independently deployable.
Milestone Summary
| Milestone | Timeline | Features | Effort | Status |
|---|---|---|---|---|
| M1: Foundation | Weeks 1-2 | 6 items | 13 days | Complete (Prototype) |
| M2: Core Features | Weeks 3-4 | 7 items | 17 days | Ready to start |
| M3: Roster & Leave | Weeks 5-6 | 9 items | 20 days | Blocked by M2 |
| M4: Polish & Mobile | Weeks 7-8 | 9 items | 18 days | Blocked by M3 |
Total Estimated Effort
68 person-days (~14 weeks at 1 developer, or 7 weeks with 2 developers). Each milestone is independently deployable — the system is usable after M1.
Deployment Guide
Step-by-step instructions to deploy WorkForce Pro on a single Windows or Linux server.
Prerequisites
What Gets Deployed
Step-by-Step Deployment
Install Docker
Download and install Docker Desktop for Windows or Docker Engine for Linux.
# Linux (Ubuntu):
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USERClone the Repository
Get the project source code onto your server.
git clone https://github.com/your-org/workforce-pro.git
cd workforce-proConfigure Environment Variables
Copy the example env file and set your secrets.
cp .env.example .env
# .env
DATABASE_URL=postgresql://wfp:wfp_password@db:5432/workforce_pro
REDIS_URL=redis://redis:6379
JWT_SECRET=your-256-bit-secret-here
JWT_REFRESH_SECRET=your-different-256-bit-secret
APP_URL=https://wfp.yourcompany.comRun Database Migrations
Initialise the PostgreSQL schema using Prisma.
docker compose run --rm api npx prisma migrate deploy
docker compose run --rm api npx prisma db seed # Creates admin userStart All Services
Launch the entire stack with a single command.
docker compose up -d
# Services running:
# - api (Node.js Express, port 3000)
# - db (PostgreSQL 16, port 5432)
# - redis (Redis 7, port 6379)
# - web (Nginx, port 80/443)
docker compose ps # Verify all containers are healthyConfigure TLS (HTTPS)
Secure your deployment with a free Let's Encrypt certificate.
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d wfp.yourcompany.comBuild Mobile Apps (Optional)
Build iOS and Android apps using Expo EAS Build.
npm install -g eas-cli
eas login
eas build --platform all --profile productionFirst Admin Login
The database seed creates a default admin account. Change the password immediately.
# Default admin credentials (CHANGE IMMEDIATELY):
Email: admin@company.local
Password: ChangeMe123!Docker Compose File
version: '3.8'
services:
api:
build: ./server
ports: ["3000:3000"]
env_file: .env
depends_on: [db, redis]
restart: unless-stopped
web:
build: ./client-web
ports: ["80:80", "443:443"]
depends_on: [api]
restart: unless-stopped
db:
image: postgres:16-alpine
volumes: [pgdata:/var/lib/postgresql/data]
env_file: .env
restart: unless-stopped
redis:
image: redis:7-alpine
restart: unless-stopped
volumes:
pgdata: