Documentation
Comprehensive guides and references for the Staffora HRIS platform. The codebase includes ~200 markdown documentation files covering architecture, security, compliance, and development.
Quick Links
Jump directly to the section you need.
In-Repository Documentation
The Staffora repository includes extensive documentation in the Docs/ directory.
Architecture Documentation
Architecture Decision Records (ADRs)
Records of key architectural decisions and their rationale.
Database Guide
PostgreSQL schema design, RLS policies, migration strategy.
Permissions System
RBAC design, field-level permissions, role hierarchy.
Security & Compliance
Security Audit
Comprehensive security review findings.
UK Compliance Audit
Employment law compliance status.
Technical Debt Report
Known issues and remediation plans.
Developer Guides
Getting Started Guide
Local development setup.
Deployment Guide
Production deployment instructions.
Frontend Guide
React patterns, component library, state management.
Design Patterns
Security Patterns
Auth, CSRF, rate limiting, encryption patterns.
State Machine Patterns
How state machines govern business workflows.
Effective Dating Patterns
Temporal data management for HR records.
Key Concepts
Core architectural principles that underpin the Staffora platform.
Multi-Tenancy
Staffora is built as a multi-tenant platform from the ground up. Every table uses PostgreSQL Row-Level Security (RLS) to enforce complete data isolation between tenants. The runtime database user (hris_app) has NOBYPASSRLS, making it impossible for application bugs to leak data across tenants.
Effective Dating
Employee records in Staffora are effective-dated, meaning every change is tracked with effective_from and effective_to dates. This preserves complete history -- personal information, contracts, positions, compensation, and manager assignments are never overwritten, only superseded by new records. This enables point-in-time queries (e.g., "who was this employee's manager on January 15th?") and provides a complete audit trail.
State Machines
Critical business processes are governed by explicit state machines defined in packages/shared/src/state-machines/. These enforce valid transitions (e.g., a leave request can only be approved from "pending" state) and prevent invalid operations at the type level. State machines exist for: employee lifecycle, leave requests, case management, workflows, performance reviews, recruitment pipeline, flexible working requests, and data breach handling.
Repository Pattern (No ORM)
Staffora deliberately avoids ORMs in favor of raw SQL using PostgreSQL's tagged template literals (via postgres.js). This gives full control over query performance, enables complex joins and CTEs, and makes it easy to leverage PostgreSQL-specific features like RLS, effective dating, and jsonb. Every module follows a consistent repository/service/routes layering.
Idempotency
Every mutating API endpoint accepts an Idempotency-Key header. This prevents duplicate operations on network retries -- if the same key is submitted twice, the second request returns the original response without re-executing the operation. Keys are scoped per tenant and stored in both Redis (fast check) and PostgreSQL (durable).
Technology Reference
Complete breakdown of the technologies powering Staffora.
Backend
| Technology | Purpose | Version |
|---|---|---|
| Bun | Runtime & package manager | 1.1.38 |
| Elysia.js | HTTP framework | ^1.1.26 |
| TypeScript | Language | ^5.7.2 |
| PostgreSQL | Database | 16 |
| Redis | Cache & queues | 7 |
| postgres.js | SQL driver | ^3.4.5 |
| Better Auth | Authentication | ^1.5.4 |
| TypeBox | Schema validation | ^0.34.11 |
| Pino | Structured logging | ^9.14.0 |
| pdf-lib | PDF generation | ^1.17.1 |
| exceljs | Excel export | ^4.4.0 |
| nodemailer | ^6.9.16 | |
| AWS S3 SDK | File storage | ^3.700.0 |
| web-push | Browser push | ^3.6.7 |
| firebase-admin | Mobile push | ^13.0.2 |
| OpenTelemetry | Tracing | ^1.9.0 |
Frontend
| Technology | Purpose | Version |
|---|---|---|
| React | UI framework | ^18.3.1 |
| React Router v7 | Routing (SSR) | ^7.1.1 |
| TanStack Query | Data fetching | ^5.62.7 |
| Tailwind CSS | Styling | ^3.4.17 |
| react-hook-form | Form handling | ^7.54.2 |
| zod | Validation | ^3.24.1 |
| recharts | Charts | ^3.8.0 |
| @dnd-kit | Drag and drop | ^6.3.1 |
| lucide-react | Icons | ^0.469.0 |
| Storybook | Component dev | ^8.5.0 |
| Vitest | Testing | ^2.1.8 |
Infrastructure
| Technology | Purpose |
|---|---|
| Docker Compose | Container orchestration |
| PgBouncer | Connection pooling |
| Nginx | Load balancer |
| Prometheus | Metrics collection |
| Grafana | Metrics dashboards |
| Loki + Promtail | Log aggregation |
| ClamAV | Virus scanning |
| GitHub Actions | CI/CD (8 workflows) |