--- name: bamboohr-reference-architecture-4cd589b05be3 description: >- Design a multi-tenant BambooHR connector with explicit auth, ingestion, webhook, queue, storage, destination, reconciliation, and audit boundaries. Use when creating or reviewing production HR integration architecture. Trigger with "BambooHR architecture", "BambooHR system design", or "multi-tenant BambooHR connector". allowed-tools: Read,Glob,Grep,Write,Edit argument-hint: " " version: 1.5.0 license: MIT author: Jeremy Longshore tags: [saas, hr, bamboohr, architecture, multi-tenant] model: inherit effort: high compatibility: Designed for Claude Code --- # BambooHR Reference Architecture ## Overview Produce an architecture that keeps control-plane actions, HR data-plane reads, mutations, webhook reception, and downstream delivery independently governable. The connector is not the authority for HR policy; BambooHR and the approved destination each retain explicit ownership. ## Prerequisites - The target repository or integration path and the requested operator outcome. - The tenant, identity, and data scope only when approved live work is in scope. - The current evidence register plus customer-specific permissions and agreements. ## Current Contract Use tenant-local BambooHR hosts and current official OpenAPI operations. Prefer dataset v2 for new bulk reads. Support OAuth token refresh with external persistence, typed request IDs/errors, bounded retries, and webhook one-time key custody. Treat deprecated report/dataset v1 paths as migration boundaries. ## Authentication The control plane stores encrypted, tenant-scoped credential metadata and exact redirect/permission configuration. Workers receive short-lived access to one tenant credential; they cannot choose arbitrary hosts or read another tenant's tokens. API-key mode uses a dedicated BambooHR identity and explicit rotation. ## Instructions 1. Define actors, tenants, business outcomes, systems of record, fields, workflows, freshness, scale, residency, retention, and recovery objectives. 2. Draw trust boundaries among consent/callback, token store, scheduler, sync worker, webhook ingress, queue, schema validator, destination adapter, checkpoint store, audit log, monitoring, and support tooling. 3. Separate read and mutation workers and permissions. Route jobs with an immutable tenant ID resolved to trusted credential and destination metadata. 4. For scheduled sync, use minimized dataset v2 reads, deterministic pagination, transactional checkpoints, idempotent destination upsert, and periodic full reconciliation. 5. For webhooks, terminate TLS, retain raw bytes only in memory for verified HMAC, reject replay, enqueue idempotently, acknowledge promptly, and use the event only as a trigger for an authorized source read when appropriate. 6. Enforce field allowlists and schema versions before queues/storage. Encrypt approved HR data and keep bodies out of general logs, traces, and dead letters. 7. Add per-tenant concurrency, finite retries, circuit breaker, dead-letter review, request-ID correlation, and backpressure. 8. Design credential revocation, tenant offboarding, data deletion, webhook replacement, schema migration, regional failure, and rollback before launch. ## Tool Discipline Use Read, Glob, and Grep to ground the design in the existing system. Use Write/Edit only for approved architecture records, diagrams-as-code, and interface contracts. This skill does not provision or mutate infrastructure. ## Approval Boundaries Require approval for field and workflow scope, auth model, tenant routing, regions, retention, destination authority, webhook events, mutation path, and recovery objectives. Record unresolved decisions rather than guessing. ## Output Return context/container/component views, data flows and trust boundaries, identity/permission matrix, field contract, queue/checkpoint/idempotency model, failure paths, SLOs, retention/deletion, decisions, risks, and validation plan. ## Error Handling - Unknown system of record: stop write-path design until ownership is resolved. - Shared tenant credential/destination namespace: classify as a blocking isolation risk. - No reconciliation or rollback model: architecture is not production-ready. ## Examples - "Design employee sync" yields both scheduled reconciliation and webhook trigger paths. - "Use one admin key for all customers" is rejected at the tenant trust boundary. ## Resources Read [official evidence](references/official-docs.md) before finalizing interfaces. --- Source attribution: jeremylongshore Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/saas-packs/bamboohr-pack/skills/bamboohr-reference-architecture/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2025 Jeremy Longshore Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: jeremylongshore Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/saas-packs/bamboohr-pack/skills/bamboohr-reference-architecture/SKILL.md Attribution basis: Source repository record Fields of work: Human Resources, Operations Roles: Business Process Analyst, HR Analyst, HR Generalist Specialties: API, Backend Tools: Bamboohr Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: d39aa9b92d11cfed52af92b522b2ab365a63962d66fa6ff17dfe229afcc57dd6