Skip to main content
bamboohr-reference-architecture Implement BambooHR reference architecture for production HR data pipelines.
Use when designing new BambooHR integrations, building employee sync systems,
or establishing architecture standards for BambooHR-powered applications.
Trigger with phrases like "bamboohr architecture", "bamboohr design",
"bamboohr project structure", "bamboohr system design", "bamboohr pipeline".
Zur Installation springen Skills Marktplatz Entdecken und erkunden Sie KI-Skills, die von der Community erstellt wurden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fรผgen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prรผfen und installieren.
Prompt-Details anzeigen Ein direkter Befehl รผberspringt den Prรผf-Prompt. Prรผfen Sie die Quelle, bevor Sie ihn ausfรผhren.
npx skills add https://github.com/jeremylongshore/claude-code-plugins-plus-skills --skill bamboohr-reference-architectureDer Befehl bleibt in einer Zeile. Scrollen Sie horizontal, um ihn vor dem Kopieren vollstรคndig zu prรผfen.
Sie bevorzugen eine lokale Kopie? Laden Sie die Dateien herunter, die SkillsMP derzeit vorliegen.
ZIP herunterladen Herunterladen... Verwandte Berufe SOC
Basierend auf der SOC-Berufsklassifikation
Mehr aus diesem Repository Implement user sign-up and sign-in flows with Clerk.
Use when building authentication UI, customizing sign-in experience,
or implementing OAuth social login.
Trigger with phrases like "clerk sign-in", "clerk sign-up",
"clerk login flow", "clerk OAuth", "clerk social login".
Implement session management and middleware with Clerk.
Use when managing user sessions, configuring route protection,
or implementing token refresh and custom JWT templates.
Trigger with phrases like "clerk session", "clerk middleware",
"clerk route protection", "clerk token", "clerk JWT".
Configure enterprise SSO, role-based access control, and organization management.
Use when implementing SSO integration, configuring role-based permissions,
or setting up organization-level controls.
Trigger with phrases like "clerk SSO", "clerk RBAC",
"clerk enterprise", "clerk roles", "clerk permissions", "clerk organizations".
name bamboohr-reference-architecture description Implement BambooHR reference architecture for production HR data pipelines.
Use when designing new BambooHR integrations, building employee sync systems,
or establishing architecture standards for BambooHR-powered applications.
Trigger with phrases like "bamboohr architecture", "bamboohr design",
"bamboohr project structure", "bamboohr system design", "bamboohr pipeline".
allowed-tools Read, Grep version 1.4.0 license MIT author Jeremy Longshore <jeremy@intentsolutions.io> tags ["saas","hr","bamboohr","architecture"] compatibility Designed for Claude Code
BambooHR Reference Architecture
Overview
Production-ready architecture for BambooHR integrations covering the three most common patterns: real-time employee sync, HR data pipeline, and employee lifecycle automation.
Prerequisites
Understanding of layered architecture and event-driven design
BambooHR API knowledge from earlier skills in this pack
TypeScript project setup with Node.js 18+
Instructions
Architecture Overview
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Your Application โ
โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ API Layer โ Sync Engine โ Webhook Handler โ
โ /api/* โ (Cron/Queue) โ /webhooks/bamboohr โ
โโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Service Layer โ
โ EmployeeService โ TimeOffService โ ReportService โ
โโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโค
โ BambooHR Client Layer โ
โ BambooHRClient โ Cache โ RetryHandler โ Metrics โ
โโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโดโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโค
โ Data Layer โ
โ PostgreSQL (employees) โ Redis (cache) โ S3 (files) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโ
โ BambooHR REST API โ
โ api.bamboohr.com/api/ โ
โ gateway.php/{co}/v1 โ
โโโโโโโโโโโโโโโโโโโโโโโโโโ
Project Structure
bamboohr-integration/
โโโ src/
โ โโโ bamboohr/
โ โ โโโ client.ts # HTTP client (from sdk-patterns)
โ โ โโโ types.ts # BambooHR API response types
โ โ โโโ retry.ts # Retry with Retry-After support
โ โ โโโ cache.ts # LRU + Redis cache layer
โ โ โโโ metrics.ts # Request counting and latency
โ โโโ services/
โ โ โโโ employee-sync.ts # Incremental directory sync
โ โ โโโ time-off.ts # PTO balance and request management
โ โ โโโ reports.ts # Custom report generation
โ โ โโโ lifecycle.ts # Onboarding/offboarding automation
โ โโโ handlers/
โ โ โโโ webhook.ts # Webhook signature verification + routing
โ โ โโโ events.ts # Employee change event processors
โ โโโ api/
โ โ โโโ health.ts # Health check endpoint
โ โ โโโ employees.ts # REST API for local employee data
โ โ โโโ reports.ts # Report generation endpoints
โ โโโ jobs/
โ โ โโโ full-sync.ts # Scheduled full directory sync
โ โ โโโ incremental-sync.ts # Frequent delta sync
โ โ โโโ report-export.ts # Scheduled report export
โ โโโ db/
โ โโโ schema.sql # PostgreSQL schema
โ โโโ queries.ts # Database queries
โโโ tests/
โ โโโ unit/
โ โ โโโ client.test.ts
โ โ โโโ employee-sync.test.ts
โ โ โโโ webhook.test.ts
โ โโโ integration/
โ โ โโโ bamboohr-live.test.ts
โ โโโ mocks/
โ โโโ bamboohr-handlers.ts # MSW handlers
โโโ config/
โ โโโ default.json
โ โโโ production.json
โ โโโ test.json
โโโ docker-compose.yml # PostgreSQL + Redis for local dev
Step 1: Data Model
CREATE TABLE bamboohr_employees (
id INTEGER PRIMARY KEY ,
first_name TEXT NOT NULL ,
last_name TEXT NOT NULL ,
display_name TEXT,
work_email TEXT,
job_title TEXT,
department TEXT,
division TEXT,
location TEXT,
supervisor_id INTEGER REFERENCES bamboohr_employees(id),
status TEXT DEFAULT 'Active' ,
hire_date DATE ,
termination_date DATE ,
employee_number TEXT,
raw_data JSONB,
synced_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_employees_status ON bamboohr_employees(status);
CREATE INDEX idx_employees_department ON bamboohr_employees(department);
CREATE INDEX idx_employees_synced ON bamboohr_employees(synced_at);
CREATE TABLE bamboohr_sync_log (
id SERIAL PRIMARY KEY ,
sync_type TEXT NOT NULL ,
started_at TIMESTAMPTZ NOT NULL ,
completed_at TIMESTAMPTZ,
employees_created INTEGER DEFAULT 0 ,
employees_updated INTEGER DEFAULT 0 ,
employees_deleted INTEGER DEFAULT 0 ,
errors JSONB DEFAULT '[]' ,
status TEXT DEFAULT 'running'
);
Step 2: Employee Sync Service
import { BambooHRClient } from '../bamboohr/client' ;
import { db } from '../db/queries' ;
const SYNC_FIELDS = [
'firstName' , 'lastName' , 'displayName' , 'workEmail' ,
'jobTitle' , 'department' , 'division' , 'location' ,
'supervisor' , 'status' , 'hireDate' , 'terminationDate' ,
'employeeNumber' ,
];
export class EmployeeSyncService {
constructor (private client : BambooHRClient async fullSync (): Promise <SyncResult > {
const log = await db.createSyncLog ('full' );
try {
const report = await this .client .customReport (SYNC_FIELDS );
const result = { created : 0 , updated : 0 , deleted : 0 , errors : [] as string [] };
for (const emp of report.employees ) {
try {
const existing = await db.getEmployee (parseInt (emp.id ));
if (existing) {
await db.updateEmployee (parseInt (emp.id ), emp);
result.updated ++;
} else {
await db.createEmployee (parseInt (emp.id ), emp);
result.created ++;
}
} catch (err) {
result.errors .push (`Employee ${emp.id} : ${(err as Error ).message} ` );
}
}
const activeIds = new Set (report.employees .map (e =>parseInt (e.id )));
const localEmployees = await db.getActiveEmployeeIds ();
for (const localId of localEmployees) {
if (!activeIds.has (localId)) {
await db.deactivateEmployee (localId);
result.deleted ++;
}
}
await db.completeSyncLog (log.id , result);
return result;
} catch (err) {
await db.failSyncLog (log.id , (err as Error ).message );
throw err;
}
}
async incrementalSync (): Promise <SyncResult > {
const lastSync = await db.getLastSyncTimestamp ();
const changed = await this .client .request <any >(
'GET' , `/employees/changed/?since=${lastSync} ` ,
);
const changedIds = Object .keys (changed.employees || {});
if (changedIds.length === 0 ) return { created : 0 , updated : 0 , deleted : 0 , errors : [] };
const result = { created : 0 , updated : 0 , deleted : 0 , errors : [] as string [] };
for (const id of changedIds) {
const emp = await this .client .getEmployee (id, SYNC_FIELDS );
}
return result;
}
async handleWebhookEvent (employeeId : string , action : string , fields : Record <string , string >switch (action) {
case 'Created' :
await db.createEmployee (parseInt (employeeId), fields);
break ;
case 'Updated' :
await db.updateEmployee (parseInt (employeeId), fields);
break ;
case 'Deleted' :
await db.deactivateEmployee (parseInt (employeeId));
break ;
}
}
}
Step 3: Employee Lifecycle Automation
export class EmployeeLifecycleService {
constructor (
private bamboohr : BambooHRClient ,
private slackClient : any ,
private googleAdmin : any ,
) {}
async onNewEmployee (employeeId : string , fields : Record <string , string >const { firstName, lastName, workEmail, department, jobTitle, supervisor } = fields;
await this .googleAdmin .createUser ({
primaryEmail : workEmail,
name : { givenName : firstName, familyName : lastName },
orgUnitPath : `/departments/${department} ` ,
});
await this .slackClient .inviteUser (workEmail);
await this .slackClient .addToChannel (workEmail, `#${department.toLowerCase()} ` );
await this .slackClient .sendDM (supervisor, {
text : `Your new report ${firstName} ${lastName} (${jobTitle} ) starts soon. ` +
`BambooHR profile: https://${process.env.BAMBOOHR_COMPANY_DOMAIN} .bamboohr.com/employees/employee.php?id=${employeeId} ` ,
});
console .log (`Onboarding complete for ${firstName} ${lastName} ` );
}
async onEmployeeTerminated (employeeId : string , fields : Record <string , string >const { workEmail, firstName, lastName } = fields;
await this .googleAdmin .suspendUser (workEmail);
await this .slackClient .deactivateUser (workEmail);
console .log (`Offboarding complete for ${firstName} ${lastName} ` );
}
async onDepartmentChanged (employeeId : string , fields : Record <string , string >const { workEmail, department } = fields;
await this .googleAdmin .moveUser (workEmail, `/departments/${department} ` );
await this .slackClient .addToChannel (workEmail, `#${department.toLowerCase()} ` );
}
}
Step 4: Sync Scheduling
import cron from 'node-cron' ;
cron.schedule ('0 2 * * *' , async () => {
console .log ('Starting full BambooHR sync...' );
const result = await syncService.fullSync ();
console .log (`Full sync: ${result.created} created, ${result.updated} updated, ${result.deleted} deleted` );
});
cron.schedule ('*/15 * * * *' , async () => {
const result = await syncService.incrementalSync ();
if (result.created + result.updated + result.deleted > 0 ) {
console .log (`Incremental sync: ${JSON .stringify(result)} ` );
}
});
Step 5: Configuration Management
export interface BambooHRIntegrationConfig {
api : {
companyDomain : string ;
apiKey : string ;
timeoutMs : number ;
maxRetries : number ;
};
sync : {
fullSyncCron : string ;
incrementalSyncCron : string ;
batchSize : number ;
};
cache : {
directoryTtlMs : number ;
employeeTtlMs : number ;
redisUrl ?: string ;
};
webhook : {
secret : string ;
path : string ;
replayWindowMs : number ;
};
}
export function loadConfig (BambooHRIntegrationConfig {
return {
api : {
companyDomain : process.env .BAMBOOHR_COMPANY_DOMAIN !,
apiKey : process.env .BAMBOOHR_API_KEY !,
timeoutMs : 30_000 ,
maxRetries : 3 ,
},
sync : {
fullSyncCron : '0 2 * * *' ,
incrementalSyncCron : '*/15 * * * *' ,
batchSize : 100 ,
},
cache : {
directoryTtlMs : 5 * 60 * 1000 ,
employeeTtlMs : 60 * 1000 ,
redisUrl : process.env .REDIS_URL ,
},
webhook : {
secret : process.env .BAMBOOHR_WEBHOOK_SECRET !,
path : '/webhooks/bamboohr' ,
replayWindowMs : 300_000 ,
},
};
}
Output
Layered architecture separating API, service, client, and data concerns
Employee sync with full, incremental, and webhook-driven modes
PostgreSQL schema for local employee data with audit trail
Lifecycle automation (onboarding, offboarding, department changes)
Scheduled sync jobs with cron
Environment-specific configuration
Error Handling Issue Cause Solution Sync data gaps Missed webhooks + long incremental interval Full sync as daily safety net Duplicate processing Webhook retry + no idempotency Idempotency keys in sync log Stale local data Cache TTL too long Webhook-based cache invalidation Circular dependencies Poor layer separation Strict dependency direction (API > Service > Client > DB)
Enterprise Considerations
Multi-company : Deploy separate instances per BambooHR company domain, or use tenant-aware client factoryData residency : Store employee data in the same region as your BambooHR instanceCompliance : Implement data retention policies; BambooHR data includes PIIHigh availability : Run sync workers as separate pods/containers from API serversMonitoring : Alert on sync failures, webhook delivery gaps, and API error spikes
Resources
Flagship Skills For the complete BambooHR skill pack, start with bamboohr-install-auth.
