Skip to main content Inicio Creadores jeremylongshore tons-of-skills-marketplace bamboohr-reference-architecture
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".
Ir a la instalación Skills Marketplace Descubre y explora habilidades de IA creadas por la comunidad.
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Mostrar detalles del prompt Un comando directo omite el prompt de revisión. Revisa el origen antes de ejecutarlo.
npx skills add https://github.com/jeremylongshore/tons-of-skills-marketplace --skill bamboohr-reference-architectureEl comando permanece en una sola línea. Desplázate horizontalmente para revisarlo antes de copiarlo.
¿Prefieres una copia local? Descarga los archivos que SkillsMP tiene disponibles ahora.
Descargar Zip Descargando... Más de este repositorio langchain-deploy-integration Deploy a LangChain 1.0 / LangGraph 1.0 app to Cloud Run, Vercel, or LangServe correctly — with timeouts sized for chain length, cold-start mitigation, SSE anti-buffering headers, and Secret Manager over .env. Use when prepping a first production deploy, debugging a stream that hangs behind a proxy, or diagnosing p99 latency spikes. Trigger with "langchain deploy", "langchain cloud run", "langchain vercel python", "langchain langserve", or "langchain docker".
langchain-langgraph-agents Build a correct LangGraph 1.0 ReAct agent with create_react_agent — typed tools, error propagation, recursion caps, and stop conditions that actually stop. Use when writing a first tool-calling agent, migrating from AgentExecutor or initialize_agent, or diagnosing an agent that loops on vague prompts. Trigger with "langgraph agent", "create_react_agent", "langgraph tool calling", "AgentExecutor migration", or "agent loop cost".
langchain-langgraph-human-in-loop Build LangGraph 1.0 human-in-the-loop approval flows with interrupt_before /
interrupt_after and Command(resume=...) — JSON-serializable state, clean
resume semantics, and UI wiring for approval decisions. Use when adding an
approval gate before an expensive tool call, wiring a Slack/web UI for agent
approvals, or debugging a graph that crashes on interrupt.
Trigger with "langgraph human in loop", "langgraph interrupt_before",
"langgraph approval flow", "Command resume", "langgraph HITL".
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.
