Open Arsenal

See the stars

NodeHR Specification

Home / NodeHR / NodeHR Specification

NodeHR

Built for Organizations That Own Their Stack

Vision

NodeHR is an open-source, self-hosted AI HR concierge and workflow automation platform designed to give organizations complete control over their people operations infrastructure.

NodeHR combines conversational AI, organizational knowledge, HR workflows, employee self-service, secure document handling, integrations, and governance into a modular platform that can operate entirely within an organization’s own infrastructure.

The system is designed to reduce repetitive HR work while preserving human oversight, organizational policy control, employee privacy, and operational transparency.

NodeHR should enable an organization to:

  • Answer routine employee HR questions through an AI-powered concierge.
  • Provide policy-aware answers grounded in approved organizational information.
  • Automate repetitive HR workflows and approvals.
  • Give employees secure self-service access to HR information and processes.
  • Manage PTO, leave, benefits, payroll-related processes, forms, and documents.
  • Connect existing HR systems through modular integrations.
  • Maintain complete control over sensitive workforce data.
  • Operate in self-hosted, private cloud, or isolated environments.
  • Extend the platform through optional plugins without modifying the core system.

Design Principles

NodeHR should follow these principles:

  • Self-hosted by design: Organizations should be able to operate the platform within infrastructure they control.
  • Open source: The platform should remain transparent, inspectable, modifiable, and extensible.
  • Modular architecture: Core capabilities should be implemented as independent modules with clearly defined interfaces.
  • Human oversight: Sensitive HR decisions and actions should support configurable human approval.
  • Policy grounding: AI responses should be based on organizational policies and approved knowledge.
  • Data ownership: Organizations should retain control over employee and HR data.
  • Security first: Sensitive employee information should be protected throughout storage, processing, transmission, and access.
  • Vendor independence: Organizations should not be forced into a specific AI provider, HR platform, or infrastructure provider.
  • Auditability: Administrative actions, workflow events, AI interactions, and policy changes should be traceable.
  • Extensibility: Organizations should be able to add functionality through optional plugins.
  • Least privilege: Users, administrators, AI agents, integrations, and plugins should receive only the permissions required for their functions.
  • Accessibility: Employee-facing functionality should support accessible and inclusive interfaces.
  • Interoperability: The platform should support standards-based communication with external systems.

Core Modules

AI HR Concierge Module

The AI HR Concierge Module provides the primary conversational interface between employees, managers, HR personnel, and the NodeHR platform.

Features should include:

  • Natural language HR questions and requests.
  • Multi-turn conversations.
  • Conversation context management.
  • Employee intent recognition.
  • HR request classification.
  • Request routing.
  • Policy-aware responses.
  • Workflow initiation from conversational requests.
  • Employee-specific responses based on authorized information.
  • Role-sensitive responses.
  • Multilingual interaction support.
  • Guided HR processes.
  • Automated escalation to HR personnel.
  • Human handoff when the AI cannot safely or accurately complete a request.
  • Configurable response boundaries.
  • AI confidence scoring.
  • Source and policy references for applicable responses.
  • Conversation history controls.
  • Administrative controls for AI usage.

The AI concierge should distinguish between informational requests and actions that modify employee or organizational records.

Actions affecting employee records, compensation, benefits, leave, access, employment status, or other sensitive information should support configurable approval requirements.

HR Knowledge and Policy Module

The HR Knowledge and Policy Module provides the authoritative organizational knowledge used by NodeHR.

Features should include:

  • Employee handbook management.
  • HR policy ingestion.
  • Policy document indexing.
  • Policy versioning.
  • Policy effective dates.
  • Document metadata.
  • Semantic search.
  • Retrieval-augmented generation.
  • Policy clause retrieval.
  • Citation-backed AI responses.
  • Structured policy relationships.
  • Policy hierarchy.
  • Policy conflict detection.
  • Regional policy variations.
  • Department-specific policies.
  • Employee-group-specific policies.
  • Archived policy management.
  • Policy approval workflows.
  • Knowledge access controls.
  • Source document tracking.
  • Knowledge freshness monitoring.

The system should distinguish between current, future, expired, archived, and superseded policies.

AI responses should prioritize authoritative and currently applicable organizational policies.

AI Safety and Governance Module

The AI Safety and Governance Module controls how artificial intelligence interacts with sensitive HR information and organizational workflows.

Features should include:

  • PII detection.
  • PII redaction.
  • Sensitive data classification.
  • Prompt injection protection.
  • AI input filtering.
  • AI output validation.
  • Hallucination mitigation.
  • Confidence thresholds.
  • Restricted request categories.
  • Human approval checkpoints.
  • Escalation rules.
  • AI action permissions.
  • Model access controls.
  • AI usage policies.
  • AI interaction auditing.
  • Privacy controls.
  • Retention controls.
  • Configurable AI provider restrictions.
  • Local-only AI operation.
  • Administrative review of AI activity.

The module should prevent the AI system from independently performing actions outside its authorized scope.

Employee Self-Service Module

The Employee Self-Service Module provides employees with a centralized interface for accessing HR information and completing HR processes.

Features should include:

  • Employee dashboard.
  • Personal profile access.
  • HR information access.
  • PTO balances.
  • Leave information.
  • Benefits information.
  • Payroll resources.
  • HR documents.
  • Forms.
  • Tasks.
  • Approvals.
  • Notifications.
  • Announcements.
  • Workflow status.
  • Policy search.
  • AI HR concierge access.
  • Employee requests.
  • Secure document access.
  • Mobile-friendly interfaces.
  • Accessibility support.

Employees should only be able to access information and functionality authorized for their role and employment relationship.

PTO and Leave Module

The PTO and Leave Module manages employee time-off and leave processes.

Features should include:

  • PTO balance tracking.
  • Leave balance tracking.
  • PTO requests.
  • Leave requests.
  • Manager approvals.
  • HR approvals.
  • Multi-level approval workflows.
  • Accrual calculations.
  • Carry-over rules.
  • Expiration rules.
  • Holiday calendars.
  • Regional leave rules.
  • Employee leave history.
  • Calendar integration.
  • Scheduling conflict detection.
  • Leave documentation.
  • Automated notifications.
  • Escalation rules.
  • Configurable organization policies.

The module should support organization-specific and region-specific leave rules through configuration or optional plugins.

Benefits Module

The Benefits Module provides employee access to benefits information and automates benefits-related workflows.

Features should include:

  • Benefits eligibility.
  • Benefits plan information.
  • Enrollment guidance.
  • Open enrollment workflows.
  • Dependent management.
  • Life-event workflows.
  • Benefits documentation.
  • Insurance information.
  • Retirement plan information.
  • Benefits questions.
  • Enrollment reminders.
  • Employee acknowledgments.
  • Benefits provider communication.
  • Benefits workflow tracking.
  • Access-controlled benefits records.

The module should provide guidance based on approved organizational benefits information and should clearly distinguish informational guidance from actions requiring an authorized benefits administrator.

Payroll and Compensation Module

The Payroll and Compensation Module provides controlled access to payroll-related information and compensation workflows.

Features should include:

  • Pay stub access.
  • Payroll document access.
  • Tax document access.
  • Direct deposit workflows.
  • Payroll issue routing.
  • Reimbursement workflows.
  • Compensation adjustment requests.
  • Bonus approval workflows.
  • Compensation band controls.
  • Compensation history.
  • Payroll-related notifications.
  • Payroll system integrations.
  • Access-controlled compensation data.

Sensitive compensation information should receive enhanced authorization and audit controls.

Workflow Automation Module

The Workflow Automation Module provides the execution framework for HR processes.

Features should include:

  • Visual workflow creation.
  • Multi-step workflows.
  • Conditional routing.
  • Approval chains.
  • Task assignment.
  • Employee tasks.
  • Manager tasks.
  • HR tasks.
  • Automated actions.
  • Scheduled actions.
  • Parallel workflow branches.
  • Workflow dependencies.
  • Escalation rules.
  • Service-level targets.
  • Retry handling.
  • Failure handling.
  • Workflow versioning.
  • Workflow history.
  • Workflow auditing.
  • Workflow templates.
  • Organization-specific workflows.

Workflows should be capable of combining AI interactions, forms, approvals, notifications, external integrations, and human actions.

Forms and Documents Module

The Forms and Documents Module manages HR forms, employee submissions, and sensitive documentation.

Features should include:

  • Dynamic forms.
  • Form templates.
  • Conditional fields.
  • AI-assisted form completion.
  • Validation.
  • Secure document uploads.
  • Document classification.
  • Document versioning.
  • Digital signatures.
  • Approval workflows.
  • Form status tracking.
  • Document expiration tracking.
  • Employee document access.
  • Administrative document access.
  • Secure document retention.
  • Document audit history.

AI-assisted form completion should require appropriate access controls and should never expose information beyond the employee’s authorization.

Security and Privacy Module

The Security and Privacy Module provides centralized protection for NodeHR data and operations.

Features should include:

  • Encryption at rest.
  • Encryption in transit.
  • Field-level encryption for sensitive information.
  • Secure key management.
  • Secrets management.
  • Single sign-on.
  • Multi-factor authentication.
  • Role-based access control.
  • Attribute-based access controls where appropriate.
  • Fine-grained permissions.
  • Session management.
  • Access logging.
  • Tamper-evident audit logs.
  • PII protection.
  • Data retention controls.
  • Secure deletion.
  • Consent tracking.
  • Administrative security controls.
  • Security event monitoring.
  • Isolated deployment support.
  • Air-gapped deployment support.

Security controls should be applied consistently across the core platform, AI services, integrations, workflows, and plugins.

Integration Module

The Integration Module provides standardized interfaces between NodeHR and external organizational systems.

Features should include:

  • HRIS integrations.
  • Payroll integrations.
  • Identity provider integrations.
  • Calendar integrations.
  • Email integrations.
  • Messaging integrations.
  • Webhooks.
  • REST APIs.
  • Event-based integrations.
  • Import and export functionality.
  • Synchronization controls.
  • Integration authentication.
  • Integration permission management.
  • Integration health monitoring.
  • Retry handling.
  • Failure reporting.
  • Integration audit records.

Supported integrations may include HR systems, identity platforms, productivity platforms, calendars, communication systems, and organizational applications.

Communication Module

The Communication Module provides employee and administrator notifications across supported communication channels.

Features should include:

  • Email notifications.
  • In-app notifications.
  • Messaging notifications.
  • Slack integration.
  • Microsoft Teams integration.
  • Workflow notifications.
  • Approval notifications.
  • Reminder notifications.
  • Escalation notifications.
  • Policy announcements.
  • HR announcements.
  • Notification preferences.
  • Delivery tracking.

Organizations should be able to control which communication channels are enabled.

Analytics and Reporting Module

The Analytics and Reporting Module provides operational visibility into HR processes and NodeHR usage.

Features should include:

  • HR request volume.
  • Request categories.
  • AI usage metrics.
  • Workflow completion metrics.
  • Workflow failure metrics.
  • Approval times.
  • Escalation rates.
  • Employee self-service usage.
  • Policy search activity.
  • Common HR questions.
  • Department-level insights.
  • Process efficiency metrics.
  • Custom reports.
  • Administrative dashboards.
  • Compliance reporting.
  • Audit exports.

Analytics should respect employee privacy, access controls, and organizational data governance policies.

Audit and Compliance Module

The Audit and Compliance Module provides traceability for sensitive HR activity.

Features should include:

  • Administrative activity logging.
  • Employee activity logging where appropriate.
  • Workflow audit trails.
  • Approval records.
  • Policy changes.
  • Document access records.
  • AI interaction records.
  • Integration activity.
  • Authentication events.
  • Permission changes.
  • Security events.
  • Data export records.
  • Retention policies.
  • Compliance reporting.
  • Audit exports.
  • Tamper-evident records.

Audit records should be protected against unauthorized modification and deletion.

Organization Management Module

The Organization Management Module provides controls for configuring NodeHR for individual organizations.

Features should include:

  • Organization configuration.
  • Department management.
  • Employee groups.
  • Regional configuration.
  • Role management.
  • Permission management.
  • Policy assignment.
  • Workflow configuration.
  • Branding.
  • Notification configuration.
  • AI configuration.
  • Integration configuration.
  • Retention configuration.
  • Administrative delegation.
  • Organization lifecycle management.

The architecture should support isolated organizational environments and multi-organization deployments where required.

Deployment and Operations Module

The Deployment and Operations Module provides the infrastructure controls required to operate NodeHR reliably.

Features should include:

  • Self-hosted deployment.
  • Private cloud deployment.
  • Containerized deployment.
  • Isolated deployment.
  • Air-gapped deployment.
  • Horizontal scaling.
  • High availability.
  • Backup management.
  • Disaster recovery.
  • Health monitoring.
  • System metrics.
  • Operational alerts.
  • Application logging.
  • Error tracking.
  • Service monitoring.
  • AI inference monitoring.
  • Configuration management.
  • Upgrade management.

Operational controls should allow organizations to maintain NodeHR without requiring access to a third-party hosted service.

Optional Plugin Modules

NodeHR should support an optional plugin architecture that allows organizations to extend the platform without modifying core functionality.

Plugins should use documented interfaces and should operate within explicit permissions.

HRIS Connector Plugins

Optional plugins may provide connections to specific HR information systems.

Capabilities may include:

  • Employee synchronization.
  • Department synchronization.
  • Job and position synchronization.
  • Employment status synchronization.
  • PTO synchronization.
  • Benefits synchronization.
  • Payroll synchronization.
  • Organizational hierarchy synchronization.

Payroll Provider Plugins

Payroll-specific plugins may provide:

  • Payroll data synchronization.
  • Pay statement retrieval.
  • Tax document retrieval.
  • Direct deposit workflows.
  • Payroll issue submission.
  • Payroll status information.

Benefits Provider Plugins

Benefits plugins may provide:

  • Benefits plan synchronization.
  • Eligibility verification.
  • Enrollment workflows.
  • Dependent synchronization.
  • Provider communication.
  • Benefits document retrieval.

Regional Compliance Plugins

Regional compliance plugins may provide configurable rules for:

  • Regional leave requirements.
  • Employment documentation.
  • Required notices.
  • Benefits requirements.
  • Payroll requirements.
  • Retention requirements.
  • Employee rights workflows.
  • Organization-specific compliance processes.

Compliance plugins should provide configurable rules rather than embedding jurisdiction-specific assumptions into the core platform.

Workforce Rules Plugins

Workforce-specific plugins may support:

  • Union rules.
  • Collective bargaining requirements.
  • Shift rules.
  • Scheduling rules.
  • Overtime rules.
  • Workforce classifications.
  • Custom employee groups.
  • Industry-specific HR policies.

Onboarding Plugins

Optional onboarding functionality may provide:

  • New-hire workflows.
  • Document collection.
  • Account provisioning.
  • Equipment requests.
  • Training assignments.
  • Policy acknowledgments.
  • Department onboarding.
  • Manager onboarding tasks.
  • Automated onboarding schedules.

Offboarding Plugins

Optional offboarding functionality may provide:

  • Separation workflows.
  • Exit documentation.
  • Equipment recovery.
  • Account deprovisioning.
  • Benefits termination workflows.
  • Final payroll coordination.
  • Exit interviews.
  • Compliance documentation.

Recruitment Plugins

Optional recruitment functionality may provide:

  • Applicant workflows.
  • Interview scheduling.
  • Candidate communications.
  • Hiring approvals.
  • Offer workflows.
  • Recruiting document management.
  • Candidate-to-employee transitions.

Performance Management Plugins

Optional performance functionality may provide:

  • Review cycles.
  • Performance goals.
  • Manager feedback.
  • Employee self-assessments.
  • Review workflows.
  • Development plans.
  • Performance documentation.

Learning and Development Plugins

Optional learning functionality may provide:

  • Training assignments.
  • Course tracking.
  • Certification tracking.
  • Compliance training.
  • Employee development plans.
  • Training reminders.

Employee Relations Plugins

Optional employee relations functionality may provide:

  • Case management.
  • HR investigations.
  • Employee relations workflows.
  • Confidential case records.
  • Escalation workflows.
  • Documentation controls.
  • Restricted-access case management.

Workforce Analytics Plugins

Optional analytics plugins may provide:

  • Workforce forecasting.
  • Workforce planning.
  • Turnover analysis.
  • Staffing analysis.
  • Organizational trends.
  • Workforce capacity analysis.

Predictive analytics should remain subject to organizational governance and appropriate human review.

AI Model Plugins

AI model plugins may allow organizations to connect approved AI models or inference systems.

Capabilities may include:

  • Local models.
  • Private inference services.
  • Organization-approved external models.
  • Model routing.
  • Model-specific policies.
  • Model capability declarations.
  • Model usage limits.
  • Model monitoring.

AI model plugins should operate through standardized interfaces so the core platform remains independent of any specific model provider.

Communication Channel Plugins

Optional communication plugins may add:

  • Additional messaging platforms.
  • Internal chat systems.
  • SMS gateways.
  • Voice interfaces.
  • Notification systems.
  • Organization-specific communication platforms.

Custom Workflow Plugins

Custom workflow plugins may introduce specialized organizational processes without changing the core workflow engine.

Plugins should be able to expose:

  • New workflow actions.
  • New triggers.
  • New approval types.
  • New data sources.
  • New notification actions.
  • New validation rules.
  • New external service actions.

Custom Policy Plugins

Organizations may create plugins for specialized policy logic.

Examples include:

  • Industry-specific policies.
  • Organization-specific eligibility rules.
  • Department-specific rules.
  • Regional policies.
  • Employee-group policies.
  • Custom approval requirements.

Voice HR Plugin

An optional voice interface may allow employees to interact with the HR concierge through speech.

Capabilities may include:

  • Voice questions.
  • Voice-guided workflows.
  • Speech recognition.
  • Spoken responses.
  • Voice authentication where supported.
  • Accessibility-focused interaction.

Voice functionality should follow the same security, authorization, privacy, and audit requirements as other interfaces.

Plugin Architecture Requirements

The plugin system should provide:

  • Plugin discovery.
  • Plugin installation.
  • Plugin activation and deactivation.
  • Plugin configuration.
  • Plugin permissions.
  • Plugin sandboxing where appropriate.
  • Plugin versioning.
  • Dependency management.
  • Compatibility checks.
  • Plugin health monitoring.
  • Plugin audit logging.
  • Plugin lifecycle management.
  • Plugin API versioning.
  • Administrative approval of plugins.
  • Organization-specific plugin policies.

Plugins should not automatically receive unrestricted access to employee data.

Every plugin should declare the resources, permissions, events, and interfaces it requires.

AI Agent Architecture

NodeHR may support specialized AI agents operating within the platform.

Possible agents include:

  • HR Concierge Agent.
  • Policy Research Agent.
  • PTO Agent.
  • Benefits Agent.
  • Onboarding Agent.
  • Offboarding Agent.
  • Payroll Support Agent.
  • Document Agent.
  • Workflow Agent.
  • Compliance Agent.
  • Analytics Agent.

Agents should operate under explicit permissions and should use shared governance, audit, security, and authorization controls.

No AI agent should be permitted to bypass platform-level security controls.

Data Governance

NodeHR should provide organizational controls for the lifecycle of employee and HR information.

Features should include:

  • Data classification.
  • Data ownership.
  • Data retention.
  • Data deletion.
  • Data export.
  • Data access requests.
  • Data access auditing.
  • Sensitive-data controls.
  • Regional data controls.
  • Organizational data isolation.
  • Backup policies.
  • Recovery policies.

Organizations should be able to define different retention and access requirements for different categories of HR information.

Privacy Controls

NodeHR should provide privacy controls throughout the system.

Privacy features should include:

  • Minimum necessary data access.
  • PII minimization.
  • PII redaction.
  • Role-based visibility.
  • Field-level permissions.
  • Restricted employee records.
  • Confidential workflow handling.
  • Configurable AI data access.
  • Conversation retention controls.
  • Audit controls.
  • Secure deletion.

Human-in-the-Loop Controls

NodeHR should allow organizations to define when human review is required.

Human approval may be required for:

  • Compensation changes.
  • Employment status changes.
  • Sensitive employee relations actions.
  • Benefits changes.
  • Payroll changes.
  • High-risk leave decisions.
  • Policy exceptions.
  • Security-sensitive actions.
  • AI-generated recommendations.
  • Actions exceeding configured confidence thresholds.

Organizations should be able to define approval requirements according to their own policies.

API and Interoperability

NodeHR should expose documented interfaces for external systems and plugins.

Interfaces should support:

  • Authentication.
  • Authorization.
  • Employee records.
  • Organizations.
  • Policies.
  • Documents.
  • Forms.
  • Workflows.
  • Tasks.
  • Approvals.
  • Notifications.
  • AI interactions.
  • Audit events.
  • Integrations.
  • Plugin operations.

API access should use the same security and authorization model as the primary application.

Configuration

NodeHR should provide centralized configuration for:

  • Organization settings.
  • Employee roles.
  • Permissions.
  • Policies.
  • AI behavior.
  • AI models.
  • Workflow rules.
  • Approval requirements.
  • Notifications.
  • Integrations.
  • Data retention.
  • Security requirements.
  • Plugin permissions.
  • Regional rules.
  • Branding.

Configuration changes affecting security, permissions, AI behavior, policies, or sensitive workflows should be auditable.

Reliability and Failure Handling

NodeHR should be designed to fail safely.

The platform should provide:

  • Workflow retry handling.
  • Integration retry handling.
  • Failure queues.
  • Error reporting.
  • Transaction recovery.
  • Duplicate-action prevention.
  • Idempotent workflow actions where appropriate.
  • Service health checks.
  • Graceful degradation.
  • Human escalation.
  • Administrative recovery controls.

An AI failure should not result in an unauthorized HR action.

Specification Branding License (SBL)

Standard

Optional

  • Specification Branding License (SBL)

License & Notice Requirements

NodeHR is released under the GNU Affero General Public License v3.0 or later (AGPL-3.0+).

By contributing to any Open Arsenal project, you agree that your contributions will also be released under this license.

Please note the following:

  • All contributions must comply with the AGPL-3.0+ terms.
  • Under Section 7 of the license, all redistributions, forks, and derivative works must preserve attribution to: Roxanne Ardary and roxanneardary.com.
  • NodeHR specifications are free to use with attribution. A Specification Branding License can be negotiated upon request.
  • The project’s notice.md file tracks attribution requirements and contributor acknowledgments. Any update that adds new contributors or modifies attribution should also update notice.md.
  • When submitting a pull request, ensure that any new files maintain the attribution headers where applicable.
  • Network-deployed versions of this software must also remain fully AGPL-3.0+ compliant, including exposure of source code modifications when applicable under the license.

For full legal details, please refer to the AGPL-3.0+ license and the project’s notice.md file.

Notice – NodeHR

Attribution Requirement: Under Section 7 of the AGPL 3.0+ license, all redistributions, forks, and derivative works, including network-deployed versions of this project, must provide attribution to Roxanne Ardary and roxanneardary.com.

Contributors

This file tracks contributors and their specific contributions to the project.

  • Roxanne Ardary, roxanneardary.com – May 25, 2026
    Created the repository for NodeHR. Designed the initial architecture for an open-source, AI-powered HR concierge and workflow automation system focused on secure, self-hosted people operations infrastructure.
  • [Add other contributors here] – [Date]
    [Describe contribution in one sentence]

License – NodeHR

This repository is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0+).

Key Points:

  • You are free to use, modify, and distribute the code.
  • All redistributions, forks, and derivative works or network-deployed versions must also be licensed under AGPL-3.0+ and provide attribution to Roxanne Ardary and roxanneardary.com as required under Section 7 of the license.
  • The software is provided “as is,” without warranty of any kind.

For the full license text, see GNU AGPL-3.0 License: https://www.gnu.org/licenses/agpl-3.0.html

Related posts:

OpenCareerForecast

IteraMind Specification

RoadCraft