Generated by Spark: 1. Purpose and Scope

The system is a cloud-based pay, bill, and workforce back-office platform designed to improve operational efficiency, accuracy, compliance, and visibility across recruitment, contracting, and staffing organisations.
It supports end-to-end workflows covering timesheets, expenses, billing, payroll, compliance, reporting, and integrations.

2. Core Functional Capabilities
2.1 Timesheet Management

Objective: Enable fast, accurate capture, approval, and processing of time data.

Timesheet Capture Methods

Online web portal (worker, client, agency)

Mobile submission

Batch import from third-party systems (configurable formats)

QR-coded paper timesheets

Automated ingestion of scanned/emailed paper timesheets

Bulk entry by agency administrators

Agency-initiated timesheet creation

Timesheet Approval

Client approval via web portal

Client approval via mobile

Email-based approval workflows

QR-coded paper approval forms

Configurable multi-step approval routing

Adjustments & Corrections

Time and rate adjustment wizard

Automated credit generation

Re-invoicing workflows

Full audit trail of changes

2.2 Expense Management

Objective: Capture and control reimbursable and billable expenses.

Worker expense submission (web/mobile)

Agency-created expense entries

Approval workflows aligned with timesheets

Integration with billing and payroll calculations

2.3 Billing & Invoicing

Objective: Automate accurate, compliant, and flexible billing.

Billing Types

Sales invoices

Permanent placement invoices

Contractor self-billing

Advice notes

Supplier invoice matching (agency and contractor)

Billing Features

Automatic invoice generation from approved timesheets

Matching invoices to supporting documentation

Electronic invoice delivery

Payment and charge term configuration

Purchase order enforcement and tracking

On-cost handling and automated adjustments

Credit control visibility

Advanced Billing

Bespoke invoice templates

Client self-billing support

Withholding tax handling

International sales tax support (via third-party integration)

Overseas billing support

2.4 Payroll Processing

Objective: Support multiple employment and engagement models.

One-click payroll processing

Limited company contractor payments

PAYE payroll (employees, deemed contractors)

CIS processing

Agency staff payroll

Holiday pay calculation and processing

2.5 Contract, Rate & Rule Enforcement

Objective: Reduce errors and enforce commercial and legal rules.

Rate templates by role, client, or placement

Automatic shift, overtime, and premium rate calculation

Time pattern validation rules

Contract enforcement logic at submission and approval

AWR monitoring (where applicable)

3. Platform Architecture
3.1 Multi-Tenancy

Single platform supporting multiple organisational entities

Logical ring-fencing between divisions

Centralised administration with delegated control

Suitable for agency groups and franchises

3.2 Global & Multi-Currency Support

Multi-currency billing and payroll

Local tax handling (sales tax, withholding tax)

Import of overseas employment costs

True margin calculation across geographies

3.3 Self-Service Portals

Objective: Reduce operational queries and improve transparency.

Branded portals for:

Workers

Clients

Internal agency users

Real-time visibility of:

Timesheets

Expenses

Invoices

Payments

Paperless document handling

3.4 Onboarding & Compliance Automation

Objective: Minimise administrative burden and compliance risk.

Digital onboarding workflows

Automated contract pack generation and distribution

Document tracking and expiry monitoring

Compliance enforcement when documentation is missing

Statutory reporting support (e.g. tax and regulatory submissions)

Auto-enrolment assessment support

4. Reporting & Analytics
4.1 Real-Time Reporting

Missing timesheets

Gross margin and profitability

Forecasting

User and audit activity

4.2 Dashboards

Agency-level summaries

Client-level summaries

Placement-level views

Worker-level views

Drill-down into underlying transactions

4.3 Custom Reporting

Configurable report builder

Bespoke management reports

Exportable datasets

Role-based access to reporting outputs

5. Notifications & Workflow Automation

In-system alerts

Email notifications

Event-driven processing updates

Reduction of manual follow-ups

Configurable notification templates

6. Integrations & Extensibility
6.1 System Integrations

API-based integration with:

Applicant Tracking Systems (ATS)

CRM platforms

Accounting and finance systems

Automated data flow:

Placements from front-office systems

Financial outputs to accounting software

6.2 Configuration & Customisation

Custom system labels

Agency-defined security roles

Editable email templates

Advanced system configuration options

Branded login URLs and pages (SSL supported)

7. Deployment & Operations
7.1 Delivery Model

Cloud-hosted SaaS

Secure, scalable architecture

High-volume processing support

7.2 Support & Lifecycle

Phone and online support

Dedicated test/demo environments

Managed development request process

8. Functional Modularity

The system is structured into core and advanced modules, enabling phased adoption and enterprise scaling:

Core pay & bill

Advanced billing

Payroll extensions

Compliance tooling

Reporting and analytics

Accounting integrations

9. Non-Functional Requirements

High availability

Data security and access control

Full auditability

Performance at scale

Regulatory adaptability
This commit is contained in:
2026-01-18 20:40:14 +00:00
committed by GitHub
parent d90c917e45
commit 7505b640e1
7 changed files with 1487 additions and 25 deletions

1
.spark-initial-sha Normal file
View File

@@ -0,0 +1 @@
HEAD

192
PRD.md Normal file
View File

@@ -0,0 +1,192 @@
# Planning Guide
A cloud-based workforce back-office platform that centralizes timesheet management, billing, payroll, compliance, and analytics for recruitment and staffing organizations, enabling efficient end-to-end workflow automation with real-time visibility and control.
**Experience Qualities**:
1. **Professional** - Enterprise-grade interface that conveys reliability, security, and operational sophistication appropriate for financial and HR workflows
2. **Efficient** - Dense information architecture with quick-access navigation, bulk actions, and keyboard shortcuts that minimize clicks for high-frequency tasks
3. **Transparent** - Clear visibility into workflow status, approval chains, and data lineage with comprehensive audit trails and real-time updates
**Complexity Level**: Complex Application (advanced functionality, likely with multiple views)
This is a multi-module enterprise platform requiring navigation between distinct functional areas (timesheets, billing, payroll, compliance), role-based access control, real-time dashboards, complex form workflows, and extensive data visualization capabilities.
## Essential Features
**Dashboard Overview**
- Functionality: Displays real-time KPIs, alerts, and quick actions across all modules
- Purpose: Provides at-a-glance operational health and reduces time to critical actions
- Trigger: User login or navigation to home
- Progression: Login → Dashboard loads with widgets → User scans metrics → Clicks widget to drill down → Navigates to relevant module
- Success criteria: All KPIs update in real-time, widgets are interactive, no data older than 5 minutes
**Timesheet Management**
- Functionality: Multi-channel timesheet capture, approval routing, and adjustment workflows
- Purpose: Centralizes time data from multiple sources with automated validation and approval
- Trigger: Worker submission, admin creation, or batch import
- Progression: Timesheet entry → Validation against contract rules → Routing to approver → Approval/rejection → Integration to billing/payroll
- Success criteria: All submission methods work, approval routing follows configured rules, adjustments create audit trail
**Billing & Invoicing**
- Functionality: Automated invoice generation, matching, delivery, and payment tracking
- Purpose: Eliminates manual invoice creation and ensures billing accuracy from approved timesheets
- Trigger: Timesheet approval or manual invoice creation
- Progression: Approved timesheet → Invoice generation → Client review → Delivery → Payment tracking → Reconciliation
- Success criteria: Invoices auto-generate within 1 hour, support multiple currencies, track payment status
**Payroll Processing**
- Functionality: One-click payroll runs supporting multiple employment models
- Purpose: Automates complex payroll calculations across PAYE, CIS, and contractor payments
- Trigger: Pay period close or manual initiation
- Progression: Select pay period → Review timesheets → Calculate deductions → Generate payment files → Submit to bank → Issue payslips
- Success criteria: Supports all employment types, calculates correctly, generates compliant reports
**Compliance Monitoring**
- Functionality: Document tracking, expiry alerts, and automated compliance enforcement
- Purpose: Reduces risk by ensuring all workers maintain required documentation
- Trigger: Document upload, expiry date reached, or onboarding initiation
- Progression: Document request → Worker upload → Verification → Expiry monitoring → Alert before expiry → Block engagement if expired
- Success criteria: All documents tracked, alerts sent 30 days before expiry, workers blocked if non-compliant
**Reporting & Analytics**
- Functionality: Pre-built and custom reports with drill-down capabilities
- Purpose: Provides visibility into margins, forecasts, and operational metrics
- Trigger: User navigates to reports or scheduled report generation
- Progression: Select report type → Apply filters → Generate → Review visualizations → Drill down → Export data
- Success criteria: Reports load under 5 seconds, support export to Excel/PDF, reflect real-time data
**Multi-Tenant Navigation**
- Functionality: Switch between organizational entities and divisions
- Purpose: Enables agency groups to manage multiple brands/divisions in single platform
- Trigger: User selects entity switcher
- Progression: Click entity selector → Choose entity → Context switches → Data filters to selected entity
- Success criteria: Clear indication of active entity, data properly segregated, no cross-contamination
## Edge Case Handling
- **Missing Timesheet Data**: Display clear empty states with guided actions to submit or import timesheets
- **Approval Conflicts**: Show resolution wizard when multiple approvers provide conflicting inputs
- **Currency Conversion Failures**: Fall back to manual rate entry with prominent warning indicator
- **Offline Submission**: Queue submissions for sync when connectivity restored with visual feedback
- **Duplicate Detection**: Flag potential duplicates with side-by-side comparison and merge option
- **Expired Documents**: Block critical actions with modal explaining requirement and upload path
- **Payment Failures**: Retry logic with exponential backoff and admin notification after 3 attempts
- **Rate Calculation Errors**: Highlight affected rows and provide inline correction interface
## Design Direction
The design should evoke trust, precision, and control—essential for handling sensitive financial and HR data. It should feel like a sophisticated financial platform: organized, systematic, and information-rich without overwhelming users. The interface should prioritize data density and scanning efficiency while maintaining clear visual hierarchy for critical alerts and actions.
## Color Selection
An enterprise financial platform with professional authority and clear status communication.
- **Primary Color**: Deep Navy Blue (oklch(0.28 0.05 250)) - Conveys trust, stability, and corporate professionalism appropriate for financial applications
- **Secondary Colors**:
- Light Slate (oklch(0.95 0.01 250)) - Subtle backgrounds for cards and panels maintaining visual separation
- Medium Gray (oklch(0.55 0.01 250)) - Secondary text and borders for information hierarchy
- **Accent Color**: Vibrant Cyan (oklch(0.65 0.15 210)) - Energetic highlight for CTAs, active states, and interactive elements
- **Status Colors**:
- Success Green (oklch(0.65 0.15 145)) - Approved timesheets, successful payments
- Warning Amber (oklch(0.75 0.15 85)) - Pending approvals, approaching deadlines
- Error Red (oklch(0.58 0.20 25)) - Rejections, overdue items, compliance failures
- Info Blue (oklch(0.60 0.12 230)) - Informational alerts, help tooltips
- **Foreground/Background Pairings**:
- Primary Navy (oklch(0.28 0.05 250)): White text (oklch(1 0 0)) - Ratio 11.2:1 ✓
- Accent Cyan (oklch(0.65 0.15 210)): White text (oklch(1 0 0)) - Ratio 4.6:1 ✓
- Light Slate (oklch(0.95 0.01 250)): Dark Navy text (oklch(0.25 0.04 250)) - Ratio 13.8:1 ✓
- Success Green (oklch(0.65 0.15 145)): White text (oklch(1 0 0)) - Ratio 4.8:1 ✓
- Warning Amber (oklch(0.75 0.15 85)): Dark text (oklch(0.25 0.02 85)) - Ratio 10.5:1 ✓
## Font Selection
Typography should project precision and clarity appropriate for data-heavy financial interfaces, with excellent readability at small sizes for dense tables and forms while maintaining personality beyond standard corporate defaults.
- **Primary Font**: IBM Plex Sans - Technical precision with warmth, excellent at small sizes for tables and forms
- **Monospace Font**: IBM Plex Mono - For monetary values, IDs, and reference numbers requiring alignment
- **Typographic Hierarchy**:
- H1 (Page Titles): IBM Plex Sans SemiBold / 32px / -0.5px letter-spacing / 1.2 line-height
- H2 (Section Headers): IBM Plex Sans SemiBold / 24px / -0.3px letter-spacing / 1.3 line-height
- H3 (Card Headers): IBM Plex Sans Medium / 18px / 0 letter-spacing / 1.4 line-height
- Body (Primary): IBM Plex Sans Regular / 14px / 0 letter-spacing / 1.5 line-height
- Body Small (Tables): IBM Plex Sans Regular / 13px / 0 letter-spacing / 1.4 line-height
- Labels: IBM Plex Sans Medium / 12px / 0.3px letter-spacing / 1.3 line-height
- Data Values: IBM Plex Mono Regular / 13px / 0 letter-spacing / 1.4 line-height
## Animations
Animations should reinforce the feeling of a responsive, well-engineered system while never impeding workflow speed for power users performing high-frequency operations.
- **Micro-interactions**: Subtle scale (0.98) and opacity (0.9) on button press (100ms) to provide tactile feedback
- **Panel Transitions**: Smooth slide-in from right for detail panels (300ms ease-out) maintaining spatial model
- **Status Changes**: Color transition with gentle pulse (200ms) when timesheet moves from pending to approved
- **Data Loading**: Skeleton screens with shimmer effect rather than spinners to maintain layout stability
- **Notifications**: Toast slides in from top-right with bounce (400ms spring physics)
- **Navigation**: Fade-swap between major views (250ms) with stagger on list items (50ms per item)
- **Hover States**: Instant background color change (0ms) with border accent fade-in (150ms)
## Component Selection
- **Components**:
- **Sidebar**: Persistent left navigation with collapsible module groups and entity switcher
- **Card**: Primary container for dashboard widgets and detail sections with subtle shadow
- **Table**: Dense data tables for timesheets, invoices, workers with sticky headers and row actions
- **Dialog**: Modal forms for creating/editing records with multi-step support
- **Sheet**: Slide-in detail panels from right for viewing full records without navigation
- **Tabs**: Switch between related views (e.g., pending/approved/rejected timesheets)
- **Badge**: Status indicators with color coding (approved/pending/rejected)
- **Button**: Primary actions (solid), secondary (outline), destructive (red), icon-only (ghost)
- **Input/Textarea/Select**: Form fields with labels-inside for space efficiency
- **Calendar**: Date range pickers for filtering reports and selecting pay periods
- **Popover**: Contextual actions menu on table rows
- **Alert**: Banner notifications for system-wide messages
- **Progress**: Visual representation of onboarding completion or document collection
- **Switch**: Toggle settings and feature flags
- **Separator**: Visual dividers between content sections
- **Customizations**:
- Custom data table component with virtual scrolling for 1000+ rows
- Custom status timeline component showing approval chain progress
- Custom metric card with sparkline trend visualization
- Custom currency input with automatic formatting and symbol
- Custom entity switcher dropdown with search and favorites
- **States**:
- Buttons: Default → Hover (accent background) → Active (scale 0.98) → Disabled (opacity 0.5)
- Inputs: Default (border-input) → Focus (ring-2 ring-accent) → Error (border-destructive) → Success (border-success)
- Rows: Default → Hover (bg-muted/50) → Selected (bg-accent/10 border-l-4 border-accent)
- Cards: Default (border subtle) → Hover (shadow-md) → Active (border-accent)
- **Icon Selection**:
- Clock: Timesheets module
- Receipt: Billing/invoicing
- CurrencyDollar: Payroll
- ShieldCheck: Compliance
- ChartBar: Reports/analytics
- Buildings: Entity switcher
- CheckCircle: Approved status
- Clock: Pending status
- XCircle: Rejected status
- Plus: Create new record
- MagnifyingGlass: Search
- Funnel: Filter
- Download: Export
- **Spacing**:
- Page padding: 6 (24px)
- Card padding: 4 (16px) mobile / 6 (24px) desktop
- Section gaps: 6 (24px)
- Component gaps: 4 (16px)
- Tight spacing (tables): 2 (8px)
- Loose spacing (forms): 8 (32px)
- **Mobile**:
- Sidebar collapses to bottom navigation bar with 5 primary modules
- Tables scroll horizontally with sticky first column
- Cards stack vertically with full width
- Multi-column layouts collapse to single column
- Sheet panels become full-screen modals
- Reduce font sizes by 1px (e.g., 14px → 13px for body)
- Dashboard widgets become swipeable carousel
- Bulk actions hidden behind menu on mobile

View File

@@ -4,9 +4,10 @@
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title></title>
<title>WorkForce Pro - Back Office Platform</title>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
<link href="/src/main.css" rel="stylesheet" />
</head>

File diff suppressed because it is too large Load Diff

View File

@@ -1,22 +1,24 @@
import { ComponentProps } from "react"
import { Slot } from "@radix-ui/react-slot"
import * as React from "react"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "@/lib/utils"
const badgeVariants = cva(
"inline-flex items-center justify-center rounded-md border px-2 py-0.5 text-xs font-medium w-fit whitespace-nowrap shrink-0 [&>svg]:size-3 gap-1 [&>svg]:pointer-events-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive transition-[color,box-shadow] overflow-hidden",
"inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold transition-colors focus:outline-hidden focus:ring-2 focus:ring-ring focus:ring-offset-2",
{
variants: {
variant: {
default:
"border-transparent bg-primary text-primary-foreground [a&]:hover:bg-primary/90",
"border-transparent bg-primary text-primary-foreground hover:bg-primary/80",
secondary:
"border-transparent bg-secondary text-secondary-foreground [a&]:hover:bg-secondary/90",
"border-transparent bg-secondary text-secondary-foreground hover:bg-secondary/80",
destructive:
"border-transparent bg-destructive text-white [a&]:hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",
outline:
"text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground",
"border-transparent bg-destructive text-destructive-foreground hover:bg-destructive/80",
outline: "text-foreground",
success:
"border-transparent bg-success text-success-foreground hover:bg-success/80",
warning:
"border-transparent bg-warning text-warning-foreground hover:bg-warning/80",
},
},
defaultVariants: {
@@ -25,21 +27,13 @@ const badgeVariants = cva(
}
)
function Badge({
className,
variant,
asChild = false,
...props
}: ComponentProps<"span"> &
VariantProps<typeof badgeVariants> & { asChild?: boolean }) {
const Comp = asChild ? Slot : "span"
export interface BadgeProps
extends React.HTMLAttributes<HTMLDivElement>,
VariantProps<typeof badgeVariants> {}
function Badge({ className, variant, ...props }: BadgeProps) {
return (
<Comp
data-slot="badge"
className={cn(badgeVariants({ variant }), className)}
{...props}
/>
<div className={cn(badgeVariants({ variant }), className)} {...props} />
)
}

View File

@@ -1 +1,93 @@
/* This is where custom CSS goes */
@import 'tailwindcss';
@import "tw-animate-css";
@layer base {
* {
@apply border-border outline-ring/50;
}
body {
@apply bg-background text-foreground;
font-family: 'IBM Plex Sans', system-ui, sans-serif;
}
.font-mono {
font-family: 'IBM Plex Mono', monospace;
}
}
:root {
--background: oklch(0.98 0.005 250);
--foreground: oklch(0.25 0.04 250);
--card: oklch(1 0 0);
--card-foreground: oklch(0.25 0.04 250);
--popover: oklch(1 0 0);
--popover-foreground: oklch(0.25 0.04 250);
--primary: oklch(0.28 0.05 250);
--primary-foreground: oklch(1 0 0);
--secondary: oklch(0.95 0.01 250);
--secondary-foreground: oklch(0.28 0.05 250);
--muted: oklch(0.95 0.01 250);
--muted-foreground: oklch(0.55 0.01 250);
--accent: oklch(0.65 0.15 210);
--accent-foreground: oklch(1 0 0);
--success: oklch(0.65 0.15 145);
--success-foreground: oklch(1 0 0);
--warning: oklch(0.75 0.15 85);
--warning-foreground: oklch(0.25 0.02 85);
--destructive: oklch(0.58 0.20 25);
--destructive-foreground: oklch(1 0 0);
--info: oklch(0.60 0.12 230);
--info-foreground: oklch(1 0 0);
--border: oklch(0.90 0.005 250);
--input: oklch(0.90 0.005 250);
--ring: oklch(0.65 0.15 210);
--radius: 0.5rem;
}
@theme {
--color-background: var(--background);
--color-foreground: var(--foreground);
--color-card: var(--card);
--color-card-foreground: var(--card-foreground);
--color-popover: var(--popover);
--color-popover-foreground: var(--popover-foreground);
--color-primary: var(--primary);
--color-primary-foreground: var(--primary-foreground);
--color-secondary: var(--secondary);
--color-secondary-foreground: var(--secondary-foreground);
--color-muted: var(--muted);
--color-muted-foreground: var(--muted-foreground);
--color-accent: var(--accent);
--color-accent-foreground: var(--accent-foreground);
--color-success: var(--success);
--color-success-foreground: var(--success-foreground);
--color-warning: var(--warning);
--color-warning-foreground: var(--warning-foreground);
--color-destructive: var(--destructive);
--color-destructive-foreground: var(--destructive-foreground);
--color-info: var(--info);
--color-info-foreground: var(--info-foreground);
--color-border: var(--border);
--color-input: var(--input);
--color-ring: var(--ring);
--radius-sm: calc(var(--radius) * 0.5);
--radius-md: var(--radius);
--radius-lg: calc(var(--radius) * 1.5);
--radius-xl: calc(var(--radius) * 2);
--radius-2xl: calc(var(--radius) * 3);
--radius-full: 9999px;
}

67
src/lib/types.ts Normal file
View File

@@ -0,0 +1,67 @@
export type TimesheetStatus = 'pending' | 'approved' | 'rejected' | 'processing'
export type InvoiceStatus = 'draft' | 'sent' | 'paid' | 'overdue'
export type PayrollStatus = 'scheduled' | 'processing' | 'completed' | 'failed'
export type ComplianceStatus = 'valid' | 'expiring' | 'expired'
export interface Timesheet {
id: string
workerId: string
workerName: string
clientName: string
weekEnding: string
hours: number
status: TimesheetStatus
submittedDate: string
approvedDate?: string
amount: number
}
export interface Invoice {
id: string
invoiceNumber: string
clientName: string
issueDate: string
dueDate: string
amount: number
status: InvoiceStatus
currency: string
}
export interface PayrollRun {
id: string
periodEnding: string
workersCount: number
totalAmount: number
status: PayrollStatus
processedDate?: string
}
export interface Worker {
id: string
name: string
email: string
type: 'employee' | 'contractor' | 'limited-company'
status: 'active' | 'inactive'
complianceStatus: ComplianceStatus
}
export interface DashboardMetrics {
pendingTimesheets: number
pendingApprovals: number
overdueInvoices: number
complianceAlerts: number
monthlyRevenue: number
monthlyPayroll: number
grossMargin: number
activeWorkers: number
}
export interface ComplianceDocument {
id: string
workerId: string
workerName: string
documentType: string
expiryDate: string
status: ComplianceStatus
daysUntilExpiry: number
}