Skip to main content
doc0blade47/compdocumentation home
Sign in

Policy Management

Last updated Oct 11, 2026
Relevant source files

The following files were used as context for generating this wiki page:

Policy Management provides a robust system for organizations to create, manage, version, and publish their internal policies. It encompasses features for policy lifecycle management, including drafting, reviewing, publishing, and archiving policies, along with advanced functionalities like AI-powered content suggestions and PDF generation.

The system is designed to handle various policy states and ensures proper authorization and data integrity throughout the policy lifecycle. It integrates with authentication mechanisms and attachment services for secure storage and retrieval of policy-related documents.

Architecture and Components

The Policy Management module is built using NestJS and follows a modular architecture, separating concerns into controllers, services, and DTOs (Data Transfer Objects).

Module Structure

The PoliciesModule orchestrates the Policy Management features, importing necessary modules and registering its components.

// apps/api/src/policies/policies.module.ts
@Module({
  imports: [AuthModule, AttachmentsModule],
  controllers: [PoliciesController],
  providers: [PoliciesService, PolicyPdfRendererService],
  exports: [PoliciesService],
})
export class PoliciesModule {}

Sources: apps/api/src/policies/policies.module.ts:1-11

Policies Controller

The PoliciesController handles incoming HTTP requests related to policies and policy versions. It defines the API endpoints, applies authentication guards, and delegates business logic to the PoliciesService. All endpoints are secured using HybridAuthGuard and require an X-Organization-Id header for session authentication or an X-API-Key for API key authentication.

Authentication

All policy management API endpoints require authentication, either via session cookies with an X-Organization-Id header or via an API key.

Sources: apps/api/src/policies/policies.controller.ts:1-25

Policies Service

The PoliciesService encapsulates the core business logic for policy operations. It interacts with the database (via Prisma), the AttachmentsService for S3 operations (e.g., storing/retrieving policy PDFs), and the PolicyPdfRendererService for generating PDF documents. It also contains logic for managing policy versions, handling status transitions, and ensuring data consistency.

Key responsibilities include:

  • CRUD operations for policies.
  • Managing policy versions (creation, update, deletion, publishing, activation, approval workflows).
  • Generating and managing PDF representations of policies.
  • Handling concurrent updates and unique constraint errors during versioning.
  • Converting policy content (TipTap JSON) to plain text for AI processing. Sources: apps/api/src/policies/policies.service.ts:1-30

Policy Data Model

Policies and their versions are stored with various attributes to manage their lifecycle and content.

Policy Attributes

The Policy entity in the database includes the following key fields:

Field NameTypeDescription
idstringUnique identifier for the policy.
namestringName of the policy.
descriptionstringOptional description of the policy.
statusPolicyStatusCurrent status of the policy (draft, published, needs_review).
contentunknown[] (JSON)Main content of the policy (TipTap JSON format).
draftContentunknown[] (JSON)Draft content, potentially different from content if changes are pending.
frequencyFrequencyHow often the policy should be reviewed.
departmentDepartmentsDepartment the policy applies to.
isRequiredToSignbooleanIndicates if the policy requires employee acknowledgment.
signedBystring[]List of user IDs who have signed the policy.
reviewDateDateNext scheduled review date.
isArchivedbooleanFlag indicating if the policy is archived.
createdAtDateTimestamp of creation.
updatedAtDateTimestamp of last update.
lastArchivedAtDateTimestamp of last archival.
lastPublishedAtDateTimestamp of last publication.
organizationIdstringID of the organization this policy belongs to.
assigneeIdstringID of the member assigned to manage the policy.
approverIdstringID of the member designated to approve the policy.
policyTemplateIdstringID of the template used to create the policy.
currentVersionIdstringID of the currently active/published policy version.
pendingVersionIdstringID of the version currently awaiting approval.
displayFormatstringFormat for displaying the policy.
pdfUrlstringURL to the policy's PDF in S3.
Sources: apps/api/src/policies/policies.service.ts:33-72, apps/api/src/policies/dto/create-policy.dto.ts:20-107

Policy Version Attributes

Each policy can have multiple versions, tracked by the PolicyVersion entity:

Field NameTypeDescription
idstringUnique identifier for the version.
policyIdstringID of the parent policy.
versionnumberSequential version number (e.g., 1, 2, 3).
contentunknown[] (JSON)Content of this specific version.
pdfUrlstringURL to this version's PDF in S3.
publishedByIdstringID of the member who published this version.
changelogstringDescription of changes in this version.
Sources: apps/api/src/policies/policies.service.ts:394-400

Enums

Several enums define the possible values for policy attributes:

// apps/api/src/policies/dto/create-policy.dto.ts
export enum PolicyStatus {
  DRAFT = 'draft',
  PUBLISHED = 'published',
  NEEDS_REVIEW = 'needs_review',
}
 
export enum Frequency {
  MONTHLY = 'monthly',
  QUARTERLY = 'quarterly',
  YEARLY = 'yearly',
}
 
export enum Departments {
  NONE = 'none',
  ADMIN = 'admin',
  GOV = 'gov',
  HR = 'hr',
  IT = 'it',
  ITSM = 'itsm',
  QMS = 'qms',
}

Sources: apps/api/src/policies/dto/create-policy.dto.ts:10-18, apps/api/src/policies/dto/create-policy.dto.ts:20-25, apps/api/src/policies/dto/create-policy.dto.ts:27-35

DTOs

Data Transfer Objects (DTOs) are used for request and response bodies, ensuring data validation and clear API contracts.

Sources: apps/api/src/policies/dto/create-policy.dto.ts, apps/api/src/policies/dto/update-policy.dto.ts, apps/api/src/policies/dto/version.dto.ts, apps/api/src/policies/dto/ai-suggest-policy.dto.ts

Key Functionality

Policy CRUD Operations

The system supports standard Create, Read, Update, and Delete (CRUD) operations for policies.

  • Create Policy: Initializes a new policy with its first draft version.
  • Get All Policies: Retrieves a list of all policies for an organization.
  • Get Policy by ID: Fetches details of a specific policy.
  • Update Policy: Modifies policy metadata. Content updates are restricted if the policy is not in draft status, requiring a new version to be created.
  • Delete Policy: Permanently removes a policy and all its associated versions and PDFs from S3.
Important Note on Content Updates

Policy content cannot be directly updated if the policy is in published or needs_review status. To modify content, a new version must be created and then updated. This ensures an auditable history of changes.

Sources: apps/api/src/policies/policies.service.ts:107-169, apps/api/src/policies/policies.service.ts:171-236, apps/api/src/policies/policies.service.ts:238-297

Policy Versioning

A core feature is the ability to manage multiple versions of a policy, providing a complete audit trail and control over policy evolution.

  • Get Policy Versions: Retrieves all versions for a given policy, ordered by version number.
  • Get Policy Version by ID: Fetches a specific version's content and metadata.
  • Create Policy Version: Creates a new draft version, typically based on the current active version or a specified source version. This process includes copying associated PDFs in S3.
  • Update Version Content: Allows modification of the content for non-published, non-pending versions.
  • Delete Policy Version: Removes a specific version, provided it is not the currently active or pending version.
  • Publish Policy Version: Promotes draft content to a new published version, updating the policy's lastPublishedAt and status. It can optionally set the new version as active.
  • Set Active Policy Version: Designates an existing version as the current active (published) version, updating the policy's main content and status. This also clears any pending approval states.
  • Submit Version for Approval: Marks a specific version as pending_review and assigns an approver. This prevents direct editing or publishing until the approval process is complete.
Version Immutability

Published and pending policy versions are immutable. Their content cannot be directly updated or deleted. To make changes, a new version must be created.

Sources: apps/api/src/policies/policies.service.ts:300-330, apps/api/src/policies/policies.service.ts:332-361, apps/api/src/policies/policies.service.ts:363-447, apps/api/src/policies/policies.service.ts:449-485, apps/api/src/policies/policies.service.ts:487-529, apps/api/src/policies/policies.service.ts:531-597, apps/api/src/policies/policies.service.ts:599-633, apps/api/src/policies/policies.service.ts:635-689

AI Policy Suggestion

The system includes an AI chat feature to assist users in editing and improving policies. Users can provide instructions, and the AI (powered by OpenAI's gpt-5.1 model) will suggest changes, explain them, and provide the complete updated policy content in Markdown format.

Sources: apps/api/src/policies/policies.controller.ts:316-407, apps/api/src/policies/dto/ai-suggest-policy.dto.ts:1-30

PDF Generation and Download

Policies can be rendered into PDF format, either individually or as a bundle of all published policies for an organization.

  • Download All Policies PDF: Generates a single PDF document containing all currently published and unarchived policies for an organization. This PDF includes organization branding (name, primary color) and page numbering. It fetches existing PDFs from S3 or renders them on-the-fly if not available.
  • The process involves:
    1. Fetching organization details and all relevant policies.
    2. Preparing policy PDFs in parallel (fetching from S3 or rendering from content).
    3. Merging individual policy PDFs into a single PDFDocument sequentially.
    4. Adding organizational headers, policy titles, and page numbers to the merged PDF.
    5. Uploading the final PDF bundle to S3 and returning a presigned download URL. Sources: apps/api/src/policies/policies.service.ts:720-888, apps/api/src/policies/policies.service.ts:691-700, apps/api/src/policies/policies.service.ts:702-718

API Endpoints

The following table summarizes the API endpoints exposed by the PoliciesController.

MethodPathDescriptionService Method Called
GET/policiesGet all policiespoliciesService.findAll
GET/policies/download-allDownload all published policies as PDFpoliciesService.downloadAllPoliciesPdf
GET/policies/:idGet policy by IDpoliciesService.findById
POST/policiesCreate a new policypoliciesService.create
PATCH/policies/:idUpdate policypoliciesService.updateById
DELETE/policies/:idDelete policypoliciesService.deleteById
GET/policies/:id/versionsGet policy versionspoliciesService.getVersions
GET/policies/:id/versions/:versionIdGet policy version by IDpoliciesService.getVersionById
POST/policies/:id/versionsCreate policy versionpoliciesService.createVersion
PATCH/policies/:id/versions/:versionIdUpdate version contentpoliciesService.updateVersionContent
DELETE/policies/:id/versions/:versionIdDelete policy versionpoliciesService.deleteVersion
POST/policies/:id/versions/publishPublish new policy versionpoliciesService.publishVersion
POST/policies/:id/versions/:versionId/activateSet active policy versionpoliciesService.setActiveVersion
POST/policies/:id/versions/:versionId/submit-for-approvalSubmit version for approvalpoliciesService.submitForApproval
POST/policies/:id/ai-chatChat with AI about a policypoliciesService.findById
Sources: apps/api/src/policies/policies.controller.ts:27-360
Was this page helpful?