Library Utilities

163 modules in backend/src/lib/ (as of 2026-06, excluding co-located tests), providing foundational building blocks used across services and routes. Most are stateless helpers, clients, and infrastructure components — but lib/ now also hosts the first domain modules (billing/, file-operations/), which under the persistence topology (I#2013) are the sole owners of Drizzle access for their domain. See Persistence Topology.

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_KEY env var — 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/	Domain module — fulfillment/user/template file operations, collection synthesis, canonical chain (PR#1752)
file-operations.ts	Legacy file operation helpers
file-validation.ts	File type/size validation
mime-validation.ts	MIME type allowlist
storage.ts	S3/Tigris object storage client — the buffer-shaped uploadFile/downloadFile helpers are deprecated; new code streams via FileService
temp-file.ts	Temporary file handling

Every file goes through CAS (files table is the single source of truth; entities reference via fileId FK). See Files.

Business Logic & Domain Modules

File	Purpose
billing/	Domain module — invoice service, dunning/overdue/retry workers, interest calculator, line-item builder, accounting
funding-calculator.ts	Funding amount calculations
u-value-calculator.ts	Thermal transmittance (U-value) calculations
contractor-commission.ts	Contractor commission calculation
workflow/	Workflow helpers

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 Bird (formerly MessageBird)
notifications/	Notification service + portal notifications

See Resend Email, MessageBird SMS, Notifications.

Infrastructure

File	Purpose
logger.ts, logger-factory.ts	Structured logging
cache.ts	In-memory caching
redis/	Redis client (Upstash REST in cloud, ioredis locally)
distributed-lock.ts	Distributed locking via Redis
db-errors.ts	SQLSTATE helpers (isUniqueViolation) — drizzle ≥0.44 wraps errors, so check error.cause, never error.code (PR#2005)
transactions.ts	Transaction helpers
env.ts	APP_ENV / environment detection
errors/	Typed error classes (Sentry-aware base error)
retry.ts	Retry helpers

Background Jobs

Directory	Purpose
jobs/	BullMQ job factory, config, schedulers, queues, processors/ (notifications, entra-sync, hubspot sync/webhooks/association-recon, billing, pdf-conversion, reminders, …)

All recurring/background work goes through BullMQ + Redis here — bare setInterval/in-process loops are forbidden (caught by quick-lint.sh). See Background Jobs.

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
• Persistence Topology — Domain modules as sole Drizzle owners
• Background Jobs — Job processing system
• Validation Pattern — Sanitization helper usage
• External Integrations — Third-party API clients
• Services Overview — Services that consume these utilities