Library Utilities

126 utility modules in backend/src/lib/, providing foundational building blocks used across services and routes. These are not services themselves — they are stateless helpers, clients, and infrastructure components.

By Category

Authentication & Encryption

File	Purpose
auth.ts	Password hashing (argon2id via Bun.password.hash()), JWT creation
tokens.ts	Token generation (portal, magic link, 2FA)
encryption.ts	AES-256-GCM encryption (encryptToken/decryptToken)

Key: ENCRYPTION_MASTER_KEY — see Authentication, HubSpot Integration for encrypted token storage.

Validation & Sanitization

File	Purpose
validation.ts	Shared Zod schemas
sanitization-helpers.ts	strictTextField(), sanitizedLocalizedText(), optionalSanitizedLocalizedText()
schema-validator.ts	Runtime schema validation

See Validation Pattern for usage rules.

File Handling

File	Purpose
file-operations.ts	File read/write operations
file-validation.ts	File type/size validation
mime-validation.ts	MIME type allowlist
storage.ts	S3/Tigris object storage client

See Files for the file management domain.

Business Logic

File	Purpose
funding-calculator.ts	Funding amount calculations
u-value-calculator.ts	Thermal transmittance (U-value) calculations

See Financial Calculations, Energy Calculations.

Access Control

File	Purpose
permissions.ts	Permission definitions and checks
ownership-guards.ts	verifyProjectAccess(), verifyBuildingAccess(), verifyScenarioAccess()
department-access.ts	Department-scoped data access

Always use RBAC-aware functions from ownership-guards.ts. See RBAC Authorization.

External API Clients

File	Purpose	Integration
hubspot.ts	HubSpot API client	HubSpot Integration
dataverse-client.ts	Microsoft Dataverse client	Dataverse
docusign-client.ts	DocuSign eSignature client	DocuSign

Communication

Directory/File	Purpose
email/	Email sending via Resend
email-templates/	Email template definitions
sms/	SMS via MessageBird

See Resend Email, MessageBird SMS, Notifications.

Infrastructure

File	Purpose
logger.ts	Structured logging
sentry.ts	Sentry error tracking setup
cache.ts	In-memory caching
redis/	Redis client and utilities
distributed-lock.ts	Distributed locking via Redis

Background Jobs

Directory	Purpose
jobs/	Job factory, config, schedulers, processors

See Background Jobs for the job processing architecture.

Utilities

File	Purpose
pagination.ts	Cursor/offset pagination helpers
sort.ts	Multi-column sort builder
search-utils.ts	Full-text search helpers
number-utils.ts	Number formatting
pdf-generator.ts	PDF document creation

Related

• Backend Architecture — How lib/ fits in the layered architecture
• Background Jobs — Job processing system
• Validation Pattern — Sanitization helper usage
• External Integrations — Third-party API clients
• Services Overview — Services that consume these utilities