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.
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.
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.
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.
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.
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.
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:
Fetching organization details and all relevant policies.
Preparing policy PDFs in parallel (fetching from S3 or rendering from content).
Merging individual policy PDFs into a single PDFDocument sequentially.
Adding organizational headers, policy titles, and page numbers to the merged PDF.
