PRIAM User Guide

Welcome to PRIAM, a platform for small businesses to develop and organize policies, assess risks, report incidnes, and to manage organiztion's assets. This guide walks you through the key features of the platform. Each section explains what a feature does, when to use it, and the steps to follow.

Company Registration

When your organisation registers for PRIAM, the Owner completes the sign-up process. You can register either with an email address and password, or with a Google account (recommended if your team uses Google Workspace).

Registering with Google (recommended)

On the Register page (/register), click Continue with Google.
Google will ask you to sign in and grant PRIAM permission to read your name and email address.
After Google redirects you back, a short Company Setup form appears with your email pre-filled and locked. Your display name is copied from your Google account but can be edited.
Fill in your company name, industry, state, and operational flags, then click Create Organisation.
You are taken directly to your dashboard — no email verification step is required, because Google has already verified your address.

Already have an email/password account? If you sign in with Google using the same email address, your accounts are automatically linked. You can use either method to sign in going forward.

Were you invited to join an existing organisation? Use the invitation link in your email to join your team. Do not use the Google Sign-in shortcut — that path creates a new, separate organisation instead of joining the one you were invited to.

Registering with Email

When your organisation registers for PRIAM, the Owner completes a two-step process:

Step 1 — Organisation Details

Company Name — Your organisation's legal name.
Industry (NAICS Code) — Your primary NAICS sector code. This drives the Risk Assessment question set, and is used by the platform to recommend relevant compliance policies.
State / Jurisdiction — The US state in which your organisation primarily operates (e.g. California, Texas). This is used to surface state-specific policy templates (for example, CCPA notices for California tenants).
Operational Flags — A set of checkboxes describing your organisation's operations. Tick any that apply:

Flag	When to tick
Has warehouse / storage	You operate a physical warehouse or inventory space
Remote workforce	A significant portion of staff work remotely
Processes health data	You store, transmit, or process protected health information (PHI)
Handles payments	You collect or process card payments or financial transactions
Operates vehicles	You own or manage a fleet of vehicles
Regulated industry	You operate in a federally or state-regulated sector (banking, utilities, etc.)

These fields are stored on your tenant profile and used to match the most relevant policy templates to your organisation. They can be updated later by an Owner in Company Settings.

Step 2 — Verify Email & Set Password

After completing Step 1, you receive a verification email. Click the link, then set your password to complete registration and access your dashboard.

Note for existing organisations: If you registered before these fields were added, jurisdiction and operational flags may be blank. Ask your Owner to update them in Company Settings to enable Smart Template Discovery.

Signing In

Navigate to /login to sign in to your account.

Enter the email address and password you set during registration, then click Sign In.

If you have forgotten your password, click Forgot password? and follow the email instructions to reset it.

Click Continue with Google on the login page. Google will authenticate you and redirect you back to your dashboard. No password is required.

If this is the first time you have signed in with Google and an email/password account already exists for that address, the accounts are linked automatically — you will land on your dashboard as usual.
If you registered your company via the Google path, you will always sign in via Google (there is no separate password unless you set one through Forgot Password).

Google Workspace users: Any Google account can be used — personal Gmail addresses as well as Google Workspace (company) accounts.

Risk Assessment

The Risk Assessment helps you understand where your organization may be vulnerable. It asks you a series of questions about your day-to-day operations, cybersecurity practices, financial controls, and more. Based on your answers, it produces a risk score, highlights your strongest and weakest areas, and gives you a list of practical steps to reduce risk.

Questions are tailored to your industry. When your organization registers, it is assigned a NAICS industry code (for example, Healthcare, Manufacturing, or Finance). The assessment uses this code to select the risk categories that matter most to your sector and only shows questions relevant to those categories.

OVI — Organizational Vulnerability Index

Before running a Risk Assessment, PRIAMtiv asks you to complete a short Organizational Vulnerability Index (OVI) profile. The OVI is a 13-question self-assessment that captures how your organization is structured and managed across three dimensions:

Step	Dimension	Questions	What It Measures
1	Objectives	5	How clearly your organization defines goals, plans for risks, and aligns strategy
2	Operational Opportunities	4	The maturity of your processes, tools, and operational practices
3	People	4	Security awareness, training, and human-factor controls across your workforce

Each question uses a 1–5 scale (1 = not in place, 5 = fully implemented).

Why the OVI matters: The OVI score acts as a contextual multiplier on your final risk score. Organizations with strong objective-setting and people controls receive a slightly lower effective risk score because their structural resilience partially offsets identified vulnerabilities. Organizations with weak controls receive a slightly higher effective score — the assessment "sees through" surface answers to reflect the real exposure.

Without a completed OVI, the risk score is calculated from your question answers alone. With it, the score is adjusted to reflect your organization's structural context.

When to complete it: The OVI profile is prompted automatically when you open the Risk Assessment page if it has not yet been filled in for your organization. It only needs to be completed once per organization, and can be updated at any time by an Admin or Owner.

Tip: Complete the OVI honestly, not aspirationally. Overestimating your maturity produces an artificially lower risk score and reduces the usefulness of the recommendations.

Accessing Risk Assessment

Clicking Risk Assessment in the sidebar routes you based on your subscription tier and existing assessments:

Situation	What happens
Starter tier	You are redirected to Settings → Module Management where you can upgrade to Growth to unlock this feature.
Growth tier — no prior assessments	You are taken directly to the new assessment start page.
Growth tier — exactly one completed assessment	You are taken directly to the results page for that assessment.
Growth tier — multiple or mixed assessments	A picker dialog opens listing all In Progress and Completed assessments. Click any row to view or resume it, or click Start New Assessment to begin a fresh one.

Before You Begin

Time needed: About 10 to 15 minutes for the Risk Assessment (plus ~3 minutes for the OVI if not yet completed).
Who can run it: Owners, Administrators, and Managers can start and submit assessments (Owners can revoke Manager or Admin access individually via Module Management). Employees and Viewers cannot run assessments. Once an Admin or Owner publishes a result, all roles can view it.
How often: You can run a new assessment at any time. Completed assessments are kept for six months, so we recommend running one at least twice a year to track your progress.
Industry required: Your organization must have an industry set in its company profile. If you see a message asking you to set your industry first, ask your administrator to update the Company Profile before proceeding.
Starter vs. Growth: The Risk Assessment questionnaire is available on both tiers. Starter tier tenants are redirected to Module Management when clicking the sidebar item (see above).

When you open the Risk Assessment page, you will see a card with a slider labeled Social Impact Level.

This setting reflects how much your organization affects the wider community. For example, a hospital or a utility company that serves the public would set this higher than a small consulting firm. The scale runs from 1 (minimal impact) to 10 (maximum impact).

Drag the slider to the value that best describes your organization.
If you are unsure, leave it at the default (5, which means "average").
This value is saved to your organization's profile. If someone already set it, you will see that value pre-filled.

Note: Only administrators can change this setting. If you are not an administrator and need it changed, ask your admin.

Step 2 — Resume or Begin

If you have a previous in-progress assessment, a dialog will appear asking whether you would like to Resume where you left off or Start Fresh. Choose whichever option suits your situation.

If there is no previous assessment, click the Begin Assessment button. The system will load questions tailored to your organization based on your industry and company profile.

Step 3 — Navigate by Category

Questions are organized into risk categories (for example, Cyber, Operational, Regulatory, Financial). At the top of the assessment screen you will see a row of category tabs — one for each category.

The currently selected category tab is highlighted.
Each tab shows a completion count (for example, "3/8") or a checkmark when all questions in that category are answered.
Click any tab to jump directly to that category.
An overall progress bar below the tabs shows how many total questions you have answered out of the total.

Step 4 — Answer Each Question

You will see one question at a time within the selected category. Each question card shows:

The category name as a heading.
A question subheading describing the topic (for example, "Govern: Asset Inventory").
The question text and answer options.

Questions come in several formats:

Yes / No — Choose one.
Choose one option — Pick the answer that best matches your situation from a list of options.
Choose multiple options — Select all options that apply.
Rating scale (1 to 5) — Rate from 1 (lowest) to 5 (highest).
Open text — Type a short answer in your own words. These do not affect your score but may be reviewed later.

After answering, click Next to move to the next question. You can also go back to a previous question using the Previous button. At the end of a category, clicking Next moves you to the first question of the next category.

Tip: Answer every question honestly. The more accurate your answers, the more useful your results will be.

Step 5 — Save and Resume

Your progress is saved automatically:

Auto-save: Answers are saved periodically in the background (every 30 seconds after your last answer).
On category switch: Answers are saved whenever you switch between category tabs.
On page leave: Answers are saved if you close the browser tab or navigate away.

If you leave and come back later, you will be prompted to resume your in-progress assessment. Your previous answers will be restored and you can pick up exactly where you left off.

Step 6 — Submit the Assessment

Once you have answered all questions across all categories, a Submit Assessment button appears. Click it to finalize. The system will:

Save all remaining answers.
Calculate your overall risk score (0 to 100).
Break down your score by category.
Determine your risk level: Low, Medium, High, or Critical.
Generate a personalized list of recommendations.

Note: The Submit button only appears when every question has been answered. If you cannot see it, check the category tabs for any incomplete categories.

Step 7 — Review Your Results

The results screen has several sections:

Overall Score

A circular gauge shows your score out of 100, along with a maturity level badge and a risk level badge. Additional metadata shows the date completed, number of categories assessed, and total questions answered.

Risk Level	Score Range	What It Means
Low	0 -- 25	Your organization has strong controls in place. Keep it up.
Medium	26 -- 50	Some areas need attention. Review the recommendations.
High	51 -- 75	Significant gaps exist. Prioritize the recommended actions.
Critical	76 -- 100	Immediate action is needed across multiple areas.

Spider Chart (Category Breakdown)

A radar chart shows how you scored in each risk category at a glance. Below the chart, a legend lists each category with its numeric score. Categories are color-coded by severity:

Green: Score below 40 (strong controls).
Yellow: Score 40-59 (some gaps).
Orange: Score 60-79 (significant gaps).
Red: Score 80 or above (critical gaps).

Risk Matrix Heatmap

A 5x5 heatmap grid plots your risks by Likelihood (vertical axis, 1-5) and Impact (horizontal axis, 1-5). Each cell is colored from green (low risk) through yellow and orange to red (high risk).

Risk categories appear as colored dots placed in the cell that matches their likelihood and impact values. Hover over a dot to see the category name and score. A legend below the grid identifies each dot color.

Recommendations

A table of prioritized actions to reduce risk. Each recommendation shows:

A severity badge (High, Medium, or Low).
The category it addresses.
A title and description explaining what to do.
An optional Learn more link for additional guidance.

You can filter recommendations by severity or category using the buttons above the table.

After the Assessment

Your results are saved automatically. You can revisit them from the dashboard at any time within the six-month retention window.
To start a fresh assessment, click Start New Assessment at the bottom of the results page.
Share your results with your team to discuss which recommendations to act on first.

Frequently Asked Questions

What is the OVI and do I have to complete it? The OVI (Organizational Vulnerability Index) is a 13-question profile of how your organization is structured and managed. It is optional but strongly recommended — a completed OVI allows the platform to adjust your risk score based on your organization's structural resilience, producing a more accurate result. If you skip it, the score is calculated from your question answers alone with no contextual adjustment.

Can I pause and come back later? Yes. The assessment automatically saves your answers as you go. If you close the browser or navigate away, your progress is preserved. When you return, a dialog will ask if you want to resume your previous assessment or start a new one.

Will my answers change which questions I see? Yes. The system selects questions based on your industry (NAICS code) and may adapt based on your answers. For example, if your organization does not handle customer payment data, you will not be asked detailed questions about payment security.

Why do I see different categories than someone in a different industry? Each industry has a different set of risk categories. A healthcare organization might see categories like Regulatory, Cyber, and Safety, while a technology company might see Resilience, Operational, and Strategic. The system uses your organization's NAICS industry code to determine which categories apply.

Who can see my results? Your results are private to your organization. Only members of your company with access to PRIAMtiv can view them. An Admin or Owner can choose to publish a completed assessment — once published, the summary (score, risk level, and a link to the full results) is visible to all roles on the Company Documents page.

What happens when an assessment expires? Completed assessments are automatically removed after six months. Run a new assessment before that time to maintain a current risk profile.

Policy Management

Process overview: Policy Management Swimlane diagram — shows the full role-by-role flow from Platform Admin publishing a template through to employees acknowledging the policy.

The Policy Management module lets your organisation create, review, approve, and publish formal policy documents — from IT security policies to HR guidelines and compliance requirements. Policies follow a structured approval lifecycle and require annual acknowledgment from staff.

The system also includes Smart Template Discovery: the platform automatically recommends pre-built master templates based on your organisation's industry, state jurisdiction, and operational profile (set during registration). Managers can create a new policy directly from a recommended template, pre-filling all sections.

Note: Master templates are published by the Platform Admin and appear in the TemplatePicker when you create a new policy. A published template does not automatically create a policy for your organisation — each team must create their own policy through the workflow below.

Policy Categories

Category	Use for
HR Policies	Employment, leave, conduct
IT Security	Acceptable use, access control, data handling
Privacy	CCPA, HIPAA, GDPR-aligned privacy notices
Health & Safety	Workplace safety, incident prevention
Finance	Expense, procurement, audit
Operations	Process and operational controls
Custom	Any policy that doesn't fit the above

Policy Lifecycle

Every policy moves through these statuses in order:

Status	Meaning
Draft	Being written. Only the creator (or an Admin) can edit it.
Pending Approval	Submitted for review. An Admin or Owner must approve or reject it.
Approved	Approved but not yet live. An Admin or Owner must publish it.
Published	Live and visible to all users in scope. Requires annual staff acknowledgment.
Expiring Soon	Published but expiring within 30 days.
Expired	Past its expiration date. Can be renewed.

Rejected policies return to Draft with a reason visible to the author.

Who Can Do What

Action	Viewer	Employee	Manager	Admin	Owner
View published policies	✓	✓	✓	✓	✓
Acknowledge a policy	✓	✓	✓	✓	✓
Comment on approval thread	✓	✓	✓	✓	✓
Create / edit drafts			✓	✓	✓
Submit for approval			✓ (own)	✓	✓
Accept / dismiss template updates			✓	✓	✓
Approve / reject				✓	✓
Publish				✓	✓
Delete draft			✓ (own)	✓	✓

Self-approval guard: An Admin cannot approve a policy they authored when there is more than one Admin or Owner in the tenant. Ask another Admin to review it instead.

Creating a Policy (Manager / Admin / Owner)

Navigate to Policy Management in the sidebar.
Click New Policy.
The Template Picker always appears first. It shows one of two views:
Recommended templates — If the platform has rules matching your organisation's industry, jurisdiction, or operational flags, you will see a ranked list. Templates with a red Required badge are legally mandated for your profile. Select one to pre-fill the title, category, and structured sections.
Browse all templates — If your profile matches no specific rules, all published templates are listed with a General indicator so you can still choose a starting point.
Click Skip — create from scratch to bypass the picker entirely and open a blank form.
After selecting a template, a banner at the top of the form confirms which template you are building from. Click Change in the banner to return to the picker.
Fill in (or confirm the pre-filled) form fields:
Title — A short, descriptive name (e.g. "Acceptable Use Policy"). Pre-filled from the template title when a template is selected.
Category — Choose from HR Policies, IT Security, Privacy, Health & Safety, Finance, Operations, or Custom. Pre-filled from the template category.
Owning Department — Which department owns this policy.
Purpose — Use the rich text editor to explain why this policy exists.
Policy Statement — The full policy content, written in the rich text editor.
Effective Date — When the policy takes effect (expiration is set to one year from this date automatically).
Scope — Whether the policy applies to all employees or specific departments.
Keywords / Tags — Comma-separated terms to help staff find this policy by search.
Click Save as Draft. The policy is assigned a policy number (e.g. POL-2026-001) automatically. If created from a template, sourceTemplateId and sections[] are stored on the draft for future template-update tracking.

Template Update Notifications

When the platform team publishes a new version of a master template, all tenants with a linked policy are notified. A blue banner appears at the top of the policy detail page:

"Template updated to v4 — review the changes and decide whether to accept them."

From the banner you can:

Review Changes — Opens a section-by-section diff showing what was added, removed, or changed in the template.
Accept — Merges the new template sections into your policy (custom sections you added are preserved). Updates sourceVersion to match.
Dismiss (×) — Closes the banner without changing the policy content.

Submitting for Approval

Once the draft is ready:

Open the policy from the Policy Management list.
Click Submit for Approval. The status changes to Pending Approval and Admins are notified.
Optionally, add an opening message to the Review Thread (visible in the sidebar while the policy is under review).

Only the policy creator, Admins, or Owners can submit a draft.

Review Thread (Pending Approval)

While a policy is in Pending Approval, a Review Thread panel appears in the sidebar. All roles can post comments visible to the author and reviewers. Use this for questions, clarifications, or revision notes without having to email separately.

Press ⌘ + Enter (Mac) or Ctrl + Enter (Windows) to send a comment quickly.
Each new comment notifies all previous participants in the thread.

Approving or Rejecting a Policy (Admin / Owner)

Open the policy. You will see Approve and Reject buttons.
To approve: click Approve. The status changes to Approved.
To reject: click Reject, provide a written reason, and confirm. The policy returns to Draft with your rejection reason displayed to the author.

Publishing a Policy (Admin / Owner)

After approval, the policy must be published to make it visible to all users:

Open the approved policy.
Click Publish. The status changes to Published.
All users within the policy's scope will see it on the Policy Management page with an "I Have Read This" button.

Acknowledging a Policy (All Roles)

When a policy is published, staff are required to acknowledge they have read it annually:

On the Policy Management page, policies needing acknowledgment show an "I Have Read This" button.
A yellow banner at the top of the page shows how many policies require your acknowledgment.
Click the button to record your acknowledgment. The button changes to a green Acknowledged label.
Acknowledgment is valid for one year. After a year, you will be prompted again.

Editing a Draft

Policies can only be edited while in Draft status. Open the draft and click Edit to modify the content. Once submitted for approval, the policy is locked for editing unless rejected back to Draft.

Renewing an Expiring or Expired Policy (Admin / Owner)

When a policy nears its expiration or has expired, it can be renewed:

Open the expiring or expired policy.
Click Renew. This re-publishes the policy and resets the expiration date to one year from today.

Company Statements & Settings-Level Policies

In addition to the full lifecycle Policy Management module, Admins and Owners can also manage short policy statements (Mission Statement, Cybersecurity Policy, etc.) directly in Company Settings. These are simpler, text-based statements visible on the Company Documents page to all users.

For the Product Team — Master Templates & Rules

The master templates and recommendation rules that tenants see are managed through the Platform Admin portal (/platform-admin), which is separate from the tenant application. See the Platform Admin Operations Guide for setup, access, and operational procedures.

The Social Works Edition is a focused deployment of PRIAMtiv for organizations in the Public Health and Social Work sector (NAICS 624). When your organization is provisioned in this mode, the platform shows only the Dashboard and Incidents modules. All other modules are hidden and unavailable.

This edition is designed to meet the specific compliance needs of social work agencies — primarily HIPAA breach notification tracking and data privacy incident management.

Who Can Access This Edition

Any Social Works organization can sign up independently. Your account team will provision your organization and send you a batch import file template to onboard your staff.

Roles in This Edition

Role	What They Can Do
Admin	Full access: create, view, update, close, and export all incidents. Receive deadline alerts. Manage users.
Reporter	Submit incident reports. View the summary of all incidents (no HIPAA metadata details). Export incident PDFs.
Viewer	View incident summaries only. No submit or update access. Export incident PDFs.

Note: These roles map to the platform's underlying admin, employee, and viewer roles respectively. If your organization later expands to other modules, these roles carry over.

Getting Started

Your admin receives login credentials from the account team.
Your admin logs in and uses Import Users to onboard your team (see the Batch User Import section in the Admin Guide).
Imported users receive an email with a password setup link. They must set their own password on first login.
Once logged in, users navigate to Incidents to begin reporting.

Incident Management

The Incident Management module lets you report, track, and resolve incidents across your organization. Every incident follows a structured workflow with 9 possible states, department-based team assignment, a full audit trail, and automated lifecycle management. Notifications keep relevant people informed as incidents progress.

Incident Statuses

Incidents move through a 9-state workflow. The main happy path is:

Status	Meaning
Draft	A saved but not yet submitted report (auto-deleted after 12 hours).
Submitted	The incident has been reported and is awaiting triage (viewer-created incidents).
Unassigned	The incident needs to be assigned to a team or person.
Assigned	A team has been assigned but work hasn't started.
Active	The team is actively working on the incident.
On Hold	The incident is paused, waiting for additional information.
Resolved	The incident has been resolved.
Closed	The incident is finalized (auto-closes after 5 business days or manually).
Unresolved	The incident was reopened by the reporter (returns to Active).

On Hold is bidirectional — when resumed, the incident returns to Active (if an assignee exists) or Assigned (if not).

Reopening: Only the original reporter can reopen a resolved incident, and only within 5 business days. A reason is required. The incident moves to "Unresolved" and then back to "Active".

Closed incidents cannot be updated or reopened.

Priorities

Critical — Immediate action required; major impact on operations or safety.
High — Urgent; significant impact that needs prompt attention.
Medium — Important but not urgent; should be addressed within a reasonable timeframe.
Low — Minor issue; can be scheduled for later resolution.

Reporting an Incident

Click Report Incident from the sidebar or the incidents list page.
Fill in the form:
Title — A short, descriptive summary (at least 5 characters).
Description — A detailed account of what happened (at least 20 characters).
Category — Select the most appropriate category.
Priority — Choose the severity level.
Team (optional) — Assign to a department team (HR, Finance, IT, Legal, etc.).
Assigned To (optional) — Assign to a specific team member. The dropdown filters by the selected team.
Mark as Private (optional) — Only visible to you and administrators/managers.
If you selected HIPAA Breach, fill in the additional fields that appear:
Breach Type — How the breach occurred (unauthorized access, theft, loss, improper disposal, hacking, or other).
PHI Categories — Which types of protected health information were involved.
Individuals Affected — An estimate of how many individuals are affected (or leave blank if unknown at time of report).
Discovery Date — The date your organization first became aware of the breach. This starts the 45-day notification clock.
If you selected Data Privacy, fill in the data types involved and any affected systems.
Click Submit Report.

After submission, the reporter receives an email confirmation (no incident details — link only). All admins also receive a notification with a login link.

Initial status depends on your role and assignment: - Viewers — The incident starts as "Submitted" and all managers are notified. - Reporters/Employees/Managers/Admins — If you assign a team and a member, the incident starts as "Active". If you assign only a team, it starts as "Assigned". If you assign neither, it starts as "Unassigned".

Viewing Incidents

Navigate to Incidents in the sidebar. The list shows each incident's title, status, priority, category, team, reporter, and assignee.

Filtering: Use the filter bar to narrow results by status, priority, category, or search keywords.

Privacy: Private incidents are only visible to the reporter and administrators/managers/owners.

Viewing Incident Details

Click the eye icon to view an incident's full details:

Status Stepper — A visual progress bar showing the happy-path stages. If the incident is On Hold, a yellow pause indicator appears. If reopened (Unresolved), a red reopen indicator appears.
Description — The full incident report.
Details Sidebar — Priority, status, category, team, reporter (with department), assignee (with department), reopen info (if applicable), and timestamps.
History & Comments — A reverse-chronological audit trail of every change: status updates, team changes, assignment changes, reopens, and comments.

Updating an Incident

Click the pencil icon to open the update dialog:

Change the status — The dropdown shows only valid next statuses based on the current state.
Change the team — Reassign to a different department.
Reassign — Select a team member (filtered by the selected team).
Reopen — If you are the original reporter and the incident is resolved (within 5 business days), you can reopen it. A reason is required.
Add a comment — Required for every update.

Role-based access: - Viewers can only add comments to their own incidents after the incident reaches Active status. They can also reopen their own resolved incidents. - Employees can assign, resolve, change teams, and add comments. - Managers/Admins/Owners have full update access.

HIPAA Breach Notification Deadlines

When a HIPAA Breach incident is submitted, the system automatically calculates a 45-day notification deadline starting from the discovery date you entered. This reflects the federal requirement to report breaches to the Department of Health and Human Services (HHS).

The incident list and detail page display a deadline badge showing the current status:

Badge	Meaning
On Track (green)	More than 30 days remain
Warning (yellow)	30 days or fewer remain — Day 15 alert sent to admins
Urgent (red)	5 days or fewer remain — Day 40 alert sent to admins
Overdue (dark red)	Deadline has passed without being marked as reported
Reported (gray)	Admin has confirmed HHS submission

Admins receive email alerts at Day 15, Day 40, and Day 45. Each alert contains a login link to the incident — details are not included in the email.

Marking as reported to HHS:

On the incident detail page, admins see a Mark as Reported to HHS button. Clicking it records the submission date, changes the badge to "Reported", and cancels any remaining deadline alerts.

Important: The 45-day clock begins on the discovery date you enter in the incident form — not the date the report is submitted. If your organization discovered a breach several days before reporting it, enter the actual discovery date.

Exporting Incidents as PDF

All roles (Admin, Reporter, Viewer) can export any individual incident as a PDF document. Click the Export PDF button on the incident detail page.

The PDF includes: incident title, category, date submitted, reporter, current status, description, and the audit trail. Reporters receive a summary-only PDF — HIPAA metadata and Data Privacy metadata fields are omitted for confidentiality. Admins and Viewers receive the complete record.

Analytics Dashboard

The Analytics dashboard provides aggregated views of incident data. Access it from the Incidents section in the sidebar.

Access by role: - Admin — Full visibility: all incidents, all reporters, all categories. - Viewer — Full visibility. - Reporter — Their own incidents only.

Available charts and filters: - Incidents by category (pie chart) - Incidents over time (line/bar chart — weekly or monthly view) - Incidents by status (stacked bar) - Incidents by reporter (admin and viewer only) - Count cards: total open, HIPAA breaches with active deadlines, resolved this month

Automated Lifecycle

The system automatically manages incident lifecycle: - Draft cleanup — Abandoned drafts are deleted after 12 hours (checked hourly). - Auto-close — Resolved incidents with no interaction for 5 business days are automatically closed. The reporter is notified. - Unassigned alerts — If incidents remain unassigned for more than 3 business days, managers and admins receive an alert (checked weekday mornings).

Notifications

Incident submitted — Reporter is notified. Viewer-created incidents notify all managers. Other incidents notify admins/owners.
Status changed — Reporter and assignee are notified.
Incident assigned — The assigned user is notified.
Team assigned — All users in the assigned department are notified.
Auto-closed — Reporter is notified.
Unassigned alert — Managers and admins are notified.

Notifications appear via the bell icon in the top navigation bar. The panel is scrollable when there are many notifications. Click × on any notification to dismiss it, or use Mark all read to clear the unread count.

Dashboard

The dashboard includes an Incidents card showing a count of open incidents (those not resolved or closed). Click the card to navigate to the incidents list.

Frequently Asked Questions

Who can report incidents? All authenticated users (viewers and above) can report incidents.

Who can update incidents? Employees, managers, admins, and owners can change status, reassign, and add comments. Viewers can only add comments to their own incidents after the incident reaches Active status.

Can I reopen a closed incident? No. Closed incidents are finalized. However, you can reopen a resolved (not yet closed) incident within 5 business days if you are the original reporter.

What happens to private incidents? Private incidents are only visible to the reporter and users with admin, owner, or manager roles.

Are comments required? Yes. Every update requires a comment to maintain a complete audit trail.

What is the 45-day HIPAA breach notification deadline? When you report a HIPAA Breach incident, the system starts a 45-day clock from the discovery date you enter. This aligns with the federal requirement to report breaches to the Department of Health and Human Services (HHS). The system sends automatic email alerts to admins at Day 15 (warning) and Day 40 (urgent). Once the breach has been reported to HHS, an admin marks it as reported in the incident detail view.

Can reporters see HIPAA metadata in incident details? No. Reporters (and viewers) see the incident summary only — title, description, category, status, and dates. The HIPAA metadata panel (breach type, PHI categories, individuals affected) is visible to admins only. Exported PDFs follow the same rule.

The email I received has no incident details — is that normal? Yes. Incident notification emails intentionally contain no details. They include only a login link to the incident. This protects sensitive information in case the notification email itself is intercepted or forwarded. Log in to view the full incident.

Module Management

The Module Management page lets administrators and owners control which features are active for their organization. Each module maps to a section of the application — enabling a module makes it visible and accessible to the appropriate roles; disabling one hides it completely.

This page is available at Administration → Module Management in the sidebar. Only users with the Admin or Owner role can access it.

Module Categories

Modules are grouped into four categories:

Category	Description
System	Core platform features (Dashboard, User Profile). Always enabled — cannot be turned off.
Core	Standard modules available to all subscription tiers (Employee Management, Incidents, Risk Assessment, Policy Management).
Growth	Advanced modules available only on the Growth subscription tier (Asset Management, Risk Assessment Pro).
Add-on	Optional specialty modules that can be enabled independently of tier (HIPAA Assessment).

Subscription Tiers

The banner at the top of the page shows your organization's current subscription tier:

Value Tier — Includes all Core modules. Premium modules are shown with an "Upgrade required" badge and cannot be enabled without upgrading.
Growth Tier — Includes all Core and Premium modules. All modules are available to toggle.

Contact your account manager to upgrade your subscription tier.

Enabling a Module

Navigate to Administration → Module Management.
Find the module you want to enable. Confirm it shows no "Upgrade required" badge.
Check that any listed dependencies are already enabled (shown under the module description).
Toggle the switch to the on position.

The change takes effect immediately. The module appears in the sidebar for users whose role grants them view access.

Disabling a Module

Locate the module on the Module Management page.
Toggle the switch to the off position.

If another enabled module depends on the one you are disabling, the system will refuse and display the names of the dependent modules. Disable those first, then return to disable the original module.

Note: Disabling a module does not delete any data. Historical records (assessments, incidents, assets, etc.) are preserved and will be accessible again if the module is re-enabled.

Module Dependencies

Some Premium modules require other modules to be active:

Module	Requires
Risk Assessment Pro	Asset Management

Attempting to enable a module with an unmet dependency will display an error message listing the required modules. Enable the dependencies first.

Role-Based Access Within a Module

Enabling a module for your organization does not grant every user the same access level. Within each module, what a user can do is still governed by their role:

Role	Typical access
Owner / Admin	Full create, edit, and delete access
Manager	View access; no create or edit on restricted modules
Employee	View access; limited create where permitted
Viewer	View access only

Risk Assessment and Policy Management are restricted modules — only Admin and Owner roles can start or edit them regardless of module status. All other roles can view completed results.

Audit Log

Every module toggle and permission change is recorded. To review the history:

On the Module Management page, look for the Audit Log section (planned feature — visible to admin/owner once implemented).
Each entry shows who made the change, what changed, and when.

Frequently Asked Questions

Who can access Module Management? Only users with the Admin or Owner role.

Does disabling a module delete data? No. All data is retained. Disabling only hides the feature from the interface.

Can I re-enable a module after disabling it? Yes, at any time, as long as the subscription tier requirement is met.

Why is a Premium module showing "Upgrade required"? Your organization is on the Value tier. Upgrade to the Premium tier to unlock these modules.

What happens if I disable a module that users are currently using? Active sessions are not interrupted mid-action, but once the page refreshes the module will no longer appear in the navigation and any direct URL access will be blocked.

HIPAA & Data Privacy Assessment

The HIPAA & Data Privacy Assessment is a standalone training module that tests team members' knowledge of HIPAA regulations and data privacy best practices. It is designed for organizations that need to verify their staff understand HIPAA compliance requirements — particularly social work coaches and similar roles that handle protected health information (PHI).

This module is completely separate from the main PRIAMtiv tenant system. It has its own login, its own user accounts, and its own administration portal. Participants in the HIPAA assessment cannot access any other part of PRIAMtiv, and main application users do not automatically have access to the HIPAA module.

How It Works

A system administrator registers companies and their participants in the HIPAA Admin Portal. Each participant receives an email address that serves as their login credential. Participants log in, take a timed 30-question assessment, and receive a score. Those who pass (80% or higher) can download a PDF certificate of completion.

Before You Begin (Participants)

Time needed: Up to 40 minutes. The assessment has a countdown timer.
Who can take it: Only participants who have been registered by a system administrator.
What you need: The email address your administrator used when adding you to the system.
Passing score: 80% — you must answer at least 24 out of 30 questions correctly.
Retakes: If you do not pass, you can retake the assessment as many times as needed.

Step 1 — Log In

Navigate to the HIPAA Assessment login page at /hipaa/login. Enter the email address your administrator registered you with and click Start Assessment.

Note: No password is required. Your email address is your only credential. If the system does not recognize your email, contact your administrator to confirm you have been added.

Step 2 — Resume or Begin

If you have a previous in-progress assessment, the system will automatically resume where you left off. Your previous answers and remaining time are restored.

If you have no in-progress assessment, a new one is created with a fresh set of randomized questions and a 40-minute timer.

Step 3 — Answer Questions

The assessment presents 30 questions one at a time. Each question card shows:

The section label (for example, "HIPAA", "MGDPA", or "HIPAA+MGDPA") indicating which regulation the question covers.
The question type — Multiple Choice, True/False, or Short Answer.
The question text and answer options.

Questions come in the following formats:

Multiple Choice (MCQ) — Select one option from a list.
True / False — Choose True or False.
Short Answer (SA) — Type your answer in the text area. Short answer questions are evaluated against a reference answer.

To answer a multiple choice or true/false question, click the option you want to select. Your answer is saved immediately. To change your answer, click a different option.

For short answer questions, type your response and click away from the text area (or navigate to another question) to save.

Step 4 — Navigate Between Questions

Use the Next and Previous buttons at the bottom of each question card to move forward and backward.

A question navigation bar appears above the question card. It shows numbered pills for all 30 questions:

Blue — The question you are currently viewing.
Green — A question you have already answered.
Gray — A question you have not answered yet.

Click any pill to jump directly to that question.

A progress bar below the header shows your overall completion percentage. The header also displays how many questions you have answered out of the total (for example, "12 of 30 answered").

Step 5 — Watch the Timer

A countdown timer is displayed in the top-right corner of the assessment screen. You have 40 minutes to complete all 30 questions.

When more than 5 minutes remain, the timer is displayed in blue.
When fewer than 5 minutes remain, the timer turns red to warn you.
If the timer reaches zero, the assessment is automatically submitted with whatever answers you have provided so far. Unanswered questions are marked as incorrect.

Step 6 — Save and Resume

Your progress is saved automatically:

Answers are saved to the server each time you select an option or navigate away from a short answer question.
Timer progress is saved every 30 seconds in the background.
On exit: If you click the exit button (top-right corner), your current time and answers are saved before you are logged out.

If you log out and log back in later, the system will resume your in-progress assessment with your previous answers and remaining time intact.

Tip: If you are running low on time, focus on answering unanswered questions rather than reviewing ones you have already answered.

Step 7 — Submit the Assessment

When you reach the last question, the Next button changes to Finish Assessment. Clicking it opens a confirmation dialog that shows:

How many questions you have answered.
A warning if any questions remain unanswered (unanswered questions count as incorrect).

Click Submit to finalize, or Go Back to continue answering.

Step 8 — Review Your Results

After submission, you are taken to the results screen. It shows:

A pass or fail indicator with a large icon and message.
Your percentage score (for example, "83%").
The number of correct answers out of the total (for example, "25 out of 30 questions correct").
A progress bar showing your score visually, with the 80% passing threshold marked.

Step 9 — Download Your Certificate (If You Passed)

If you scored 80% or higher, a Download Certificate button appears on the results screen. Click it to download a PDF certificate that includes:

Your full name.
Your company name.
The date you completed the assessment.
Your score.
A unique certificate ID.
A 12-month validity period from the date of completion.

The certificate is generated as a professional PDF document suitable for printing or sharing with your employer.

Step 10 — Retake (If You Did Not Pass)

If you scored below 80%, a Retake Assessment button appears on the results screen. Click it to start a new assessment with a fresh set of randomized questions and a new 40-minute timer. There is no limit on the number of retakes.

Note: Each retake generates a completely new randomization of the 30 questions. You may see the same questions but in a different order.

Frequently Asked Questions

What email do I use to log in? Use the email address your company administrator registered you with. If you are unsure, contact your administrator.

Do I need a password? No. The HIPAA assessment uses email-only authentication. Enter your email and you are logged in.

Can I pause and come back later? Yes. Your answers and remaining time are saved automatically. When you log back in, you will resume exactly where you left off.

What happens if the timer runs out? The assessment is automatically submitted. Any questions you have not answered are counted as incorrect.

How many times can I retake the assessment? There is no limit. You can retake the assessment as many times as needed until you pass.

Can I see which questions I got wrong? No. For test integrity, individual question results are not shown. You will only see your overall score and pass/fail status.

How long is my certificate valid? Certificates are valid for 12 months from the date of completion.

Can I access other parts of PRIAMtiv from the HIPAA module? No. The HIPAA assessment is completely isolated from the main application. You cannot navigate to the dashboard, incidents, or any other feature from the HIPAA login.

Backing Up HIPAA Data

pnpm backup:hipaa

Creates a timestamped directory under db/backups/ — for example:

db/backups/hipaa-2024-01-15T10-30-00-000Z/
  manifest.json          ← document counts + timestamp
  hipaa_admin_sessions.json
  hipaa_assessments.json
  hipaa_certificates.json
  hipaa_companies.json
  hipaa_participants.json
  hipaa_questions.json
  hipaa_system_admins.json

Each file is a JSON array of { id, data } objects. Firestore Timestamp values are encoded as { __type: "Timestamp", seconds, nanoseconds } so they round-trip perfectly.

Restore

# Dry run first — validates the files without writing anything
pnpm backup:hipaa:restore db/backups/hipaa-2024-01-15T10-30-00-000Z --dry-run

# Actual restore
pnpm backup:hipaa:restore db/backups/hipaa-2024-01-15T10-30-00-000Z

The restore uses set() (upsert by document ID), so it's safe to run against a partially-populated database. It processes in batches of 500 to respect Firestore's write limits.

Notes

db/backups/ is added to .gitignore — the files contain personal data and must not be committed.
hipaa_questions is included in the backup even though it can be re-seeded from db/assessments/hipaa-questions.json, in case questions were edited at runtime.
Run a backup before pnpm db:wipe or any destructive migration, then restore afterward.

Logging In

Navigate to /hipaa-admin/login and enter the system administrator email and password. The default credentials are created during the initial seed process (see the seed commands section below). After logging in, you are taken to the admin dashboard.

Dashboard

The dashboard provides an at-a-glance overview of the entire HIPAA assessment system:

Companies — Total number of registered companies.
Participants — Total number of registered participants across all companies.
Assessments — Total number of completed assessments.
Certificates — Total number of certificates issued.
Pass Rate — Percentage of completed assessments that resulted in a passing score.
Average Score — Mean score across all completed assessments.

A Participant Status section breaks down participants by their current state: Invited, In Progress, Completed, or Failed.

Managing Companies

Navigate to Companies in the top navigation bar.

Adding a Company

Click Add Company.
Fill in the company details:
Company Name (required) — The name of the organization.
Contact Email (required) — A primary contact email for the company.
Contact Phone (optional) — A phone number.
Address (optional) — The company's address.
Click Create.

The company appears in the list immediately.

Viewing a Company

Click a company name in the list to see its detail page. The detail page shows:

The company's contact information.
Statistics — Counts of total, invited, in-progress, completed, and failed participants.
Participants table — All participants registered under this company, with their name, email, and current status.

Deactivating a Company

From the company detail page or list, deactivating a company prevents its participants from starting new assessments. Existing in-progress assessments are not affected.

Managing Participants

You can manage participants from the company detail page or from the global Participants page.

Adding a Single Participant

From a company's detail page, click Add Participant.
Enter the participant's First Name, Last Name, and Email address.
Click Add.

The participant is created with a status of "Invited" and can immediately log in at /hipaa/login using their email.

Important: The email you enter here is exactly what the participant must use to log in. Double-check for typos.

Adding Multiple Participants

Use the bulk endpoint (accessible via API) to add many participants at once. Participants with duplicate emails within the same company are automatically skipped.

Viewing All Participants

The Participants page in the top navigation shows all participants across all companies. Use the search bar to filter by name or email.

Each participant row shows:

Name — First and last name.
Email — The login email.
Status — One of:

Status	Meaning
Invited	The participant has been added but has not started the assessment.
In Progress	The participant has started the assessment but has not finished.
Completed	The participant passed the assessment (80% or higher).
Failed	The participant completed the assessment but did not reach the passing score.

Removing a Participant

Click the trash icon next to a participant to remove them. This permanently deletes their participant record. If they have any completed assessments or certificates, those records remain in the system for reporting purposes.

Viewing Reports

Navigate to Reports in the top navigation. The reports page shows:

Summary statistics — Total assessments, passed, failed, pass rate, and average score.
Results table — Every completed assessment, showing the participant's name, email, score (as a fraction and percentage), pass/fail status, and completion date.

Reports can be filtered by company using the API query parameter.

Frequently Asked Questions

How do I change the admin password? The admin account is created during the seed process. To change the password, update the seed script and re-run pnpm seed:hipaa, or update the hipaa_system_admins document directly in Firestore.

Can I have multiple admin accounts? The system supports multiple admin accounts. Add additional documents to the hipaa_system_admins collection in Firestore with hashed passwords.

What happens when a participant fails and retakes? Each retake creates a new assessment record. The participant's status changes back to "In Progress" when they start a new attempt. If they pass, it changes to "Completed". Their previous failed assessments remain in the reports for audit purposes.

Can I see individual question-level results? The admin reports show overall scores per assessment. Individual question-level answers are stored in the database but are not currently surfaced in the admin UI.

Team Members & Invitations

This section covers how administrators invite new employees to the platform and how to track the status of sent invitations.

Inviting a New Employee (Admin / Owner)

PRIAMtiv uses an email-based invitation flow for adding team members. When you invite someone, they receive an email with a secure link to set up their account. You do not create their account directly.

Navigate to Employees in the sidebar (under Assets).
Click the + icon in the top-right corner of the page header.
In the Invite New User dialog, enter:
Email Address — The email the new employee will use to log in.
Role — The access level to assign (Employee is the default for this flow).
Department — The department they belong to.
Click Send Invitation.
The invitee receives an email with a link valid for 2 hours. They click it, set a password, and are taken to the platform.

Note: The invitation link expires after 2 hours. If a link expires before the employee uses it, send a new invitation.

Employee Directory

The Employees page (/dashboard/employees) lists all members of your organization. Columns displayed:

Column	Description
Employee ID	System-assigned identifier
Name	First and last name
Email	Work email address
Role	Primary role (e.g. Employee, Manager)
Department	Assigned department
Phone	Contact phone number
Actions	Context-sensitive action buttons (see below)

Updating Your Phone Number or Address (All Employees)

Employees cannot directly edit their own phone number or address — changes must go through an approval workflow to maintain data integrity.

To request an update:

Go to Employees in the sidebar.
Find your own row. In the Actions column you will see:
A pencil icon — click to request a phone number change.
A pin icon — click to request an address change.
A dialog opens showing your current value and a field for the new value.
Enter the new value and click Submit for Approval.

What happens next:

All Managers, Admins, and Owners in your organization receive an in-app notification (bell icon) asking them to review the request.
The request appears on the Approval Requests page (/dashboard/requests).
You receive an in-app confirmation that your request was submitted.
As soon as any one Manager, Admin, or Owner approves or rejects your request, the approval notifications are removed from all approver inboxes.
You receive a notification confirming the outcome (approved or rejected).
If approved, your record is automatically updated.

Privacy note: Your address is only visible to yourself and admins/owners — other employees cannot see it.

Approval Requests (Manager / Admin / Owner)

Managers, Admins, and Owners can review and act on pending phone/address update requests at Approval Requests in the sidebar.

Each request shows: - Employee — Name and ID of the requester. - Field — What they want to change (Phone Number or Address). - Requested Value — The new value they submitted. - Status — Current status (pending).

Click Approve to apply the change, or Reject to deny it. Only one approval is needed — once acted upon, the notification is removed from all approvers' inboxes and the requester is notified.

Phone Number Format

Phone fields across the platform (Employees, Customers) accept input as raw digits and automatically display numbers in (XXX) XXX-XXXX format. You do not need to type parentheses, spaces, or hyphens — just type the digits. Only the 10 digits are stored in the system.

Examples: - Type 5551234567 → displays as (555) 123-4567 - Type 555 → displays as (555 (partial formatting while typing)

If you paste a formatted number like (555) 123-4567, the system strips the formatting and stores only the digits.

All Assets View

The All Assets page (/dashboard/allassets) provides a single scrollable view of every asset type in your organization, each collapsed in its own accordion section.

Accessing it: - Click View All Assets on the Asset Summary card on the Dashboard.

What you see depends on your subscription tier:

Tier	Content
Starter	Employees accordion is shown. Below it, an Asset Management upgrade prompt is displayed with a link to upgrade to Growth.
Growth	All five sections — Employees, Customers, Suppliers, Devices, and Vehicles — are shown, each expandable and collapsible independently.

Each section shows a compact table with the key fields for that asset type. Click View all → inside any section header to navigate to the full management page for that asset type.

Retiring an Asset

Assets are never permanently deleted — they are retired (soft-deleted). The retirement workflow depends on your role.

Employees — Request Retirement

Open the asset record and click the trash / retire icon.
Enter a justification (minimum 10 characters) explaining why the asset should be retired.
Click Submit request.

The asset status changes to pending_deletion. The asset remains visible but is flagged as pending. A manager, admin, or owner must approve the request before the asset is formally retired.

Your request appears in the Approval Requests queue for all managers, admins, and owners in your organisation. Only one approver is needed to act on it.

Managers, Admins, and Owners — Retire Immediately or Approve a Request

Retiring directly: 1. Open the asset record and click the trash / retire icon. 2. Enter a justification (min 10 characters). 3. Confirm — the asset is immediately set to status: retired.

Approving an employee's pending request: 1. Navigate to Approval Requests in the sidebar. 2. Find the pending deletion request and review the justification. 3. Click Approve to retire the asset, or Reject to return it to active status.

After Retirement

Retired assets are hidden from active lists by default. Use the status filter (set to retired) to view them.
The deletedAt timestamp and deletedBy user ID are recorded on the asset document for audit purposes.
All delete actions store a deleteJustification field on the asset record.
Retirement is not reversible through the UI — contact your system administrator if an asset was retired in error.

Invitation Report (Admin / Owner)

The Invitations page provides an audit view of all invitations sent for your organization.

Accessing the page: - Click Invitations in the sidebar (under the Administration section), or - Click the Pending Invitations tile on the Dashboard.

What you see:

Each invitation appears as a card showing: - Email — The email the invitation was sent to. - Status — One of: pending, active, used, or expired. - Role — The role the invitee was assigned. - Department — The department they were invited to join. - Expiry — How much time remains (or how long ago it expired). - Sent by — The user ID of the admin who sent the invitation.

Dashboard tile:

The Pending Invitations tile on the dashboard shows the count of invitations currently in pending status. Click it to go directly to the Invitations page.

Sending a new invitation from this page:

Click the + button in the top-right corner of the Invitations page to open the Invite New User dialog without navigating away.

Application Owner & Administrator Guide

This section is for the application owner or system administrator responsible for setting up, maintaining, and troubleshooting the PRIAMtiv platform.

Administrators of standalone (Social Works Edition) tenants can onboard multiple users at once by uploading a CSV or Excel file. This is the recommended approach for the initial onboarding of your team.

Preparing the Import File

Create a CSV or Excel file (.csv, .xlsx, or .xls) with the following columns. The header row is required; column order is flexible.

Column	Required	Values
`email`	Yes	Valid email address — must be unique within your organization
`firstName`	Yes	User's first name
`lastName`	Yes	User's last name
`role`	Yes	`admin`, `reporter`, or `viewer` (case-insensitive)
`employeeId`	No	Your organization's internal employee ID
`phone`	No	Contact phone number

Example:

email,firstName,lastName,role,employeeId,phone
jane.smith@city.gov,Jane,Smith,admin,EMP-001,555-1234
john.doe@city.gov,John,Doe,reporter,EMP-002,555-5678
alice.jones@city.gov,Alice,Jones,viewer,EMP-003,

Importing Users

Navigate to Administration → Import Users in the sidebar.
Click Choose File and select your prepared CSV or Excel file.
The system parses the file immediately in the browser and shows a preview table. Review for any errors highlighted in red (invalid email format, unrecognized role, duplicate email).
Fix any errors in your source file and re-upload, or proceed if all rows look correct.
Click Import to create the accounts.
A results table shows the outcome for each row: green for success, red for failure with a reason.

What Happens After Import

Each imported user receives a welcome email containing a password setup link. The link is valid for 24 hours.
Users must click the link and set their own password before they can log in.
If a user's link expires before they set their password, an admin can resend it from the user management section (planned feature) or ask the user to use the Forgot Password flow on the login page.
On first login, users are not required to change their password again — the password they set via the welcome link is their permanent password.

Import Limits and Notes

Maximum recommended batch size: 25 users per import. For larger groups, split into multiple files.
Duplicate emails within the same organization are rejected at the preview stage.
Users with an existing Firebase account (from a different organization) can be imported — they will be added to your organization with the role you assign.

Initial Setup (First-Time Deployment)

When deploying PRIAMtiv for the first time, you must seed the database with the reference data that the application depends on. Without this data, features like Risk Assessment will not function.

Prerequisites:

A Firebase project with Firestore enabled.
A Firebase service account key file saved as service-account-file.json in the project root.
Node.js and pnpm installed.
Redis running (required for incident queue workers).

Step 1 — Seed all reference data

Run the following command to populate the database with all required seed data in one step:

pnpm seed:all

This seeds company profile field templates, incident templates, and risk assessment question templates into the seed_data collection.

Step 2 — Seed the Risk Assessment engine

The Risk Assessment module requires its own data (question DAGs and scoring models). Run:

pnpm seed:assessment

This runs two sub-commands internally:

pnpm seed:dags — Reads active questions from risk_question_library in Firestore, validates them, and writes the compiled question_dags/risk-assessment-v1 document containing all risk questions organized by category (Cyber, Safety, Financial, Operational, etc.) with NAICS-based visibility rules.
pnpm seed:models — Creates the risk_models/default-v1 document containing scoring multipliers for company size and social impact.

Step 3 — Verify seed data integrity

After seeding, confirm that all required documents were created successfully:

pnpm verify:seed

This checks that critical seed documents exist and have the expected structure.

Step 4 — (Optional) Seed demo data

If you want a pre-configured demo company with sample users and data for testing or demonstrations:

pnpm seed:demo

Step 5 — Seed and configure the Module Management system

The Module Management system requires two seed operations and a one-time tenant migration:

pnpm seed:modules                    # Seeds module registry + default role permissions
pnpm migrate:tenant-subscriptions    # Creates a subscription document for every existing tenant
pnpm migrate:product-mode            # Sets productMode: 'full' on all existing tenants (idempotent)

seed:modules is safe to re-run at any time (for example, after a new module is added to the registry). Both migrations are idempotent — they skip tenants that already have the relevant fields set.

After migration, each tenant will have a tenant_subscriptions document with the Value tier and all Core modules enabled by default. Upgrade tenants to Premium tier via the Firestore console or a future admin UI.

Provisioning a Social Works (Standalone) Tenant:

When onboarding a new Social Works organization, provision their tenant with: - productMode: 'incident-standalone' - enabledModules: ['dashboard', 'incidents']

This can be set directly in the Firestore console on the tenant_subscriptions/{tenantId} document, or via the future tenant admin UI. Do not run migrate:product-mode after manually setting a standalone tenant — the script only sets 'full' for tenants that don't already have productMode set.

Step 6 — Seed the Policy Template catalog (Recommended)

Populate the database with the 12 pre-built master policy templates and their recommendation rules:

pnpm seed:templates

This creates all templates as published at version 1 and writes the associated matching rules into template_rules. The script is idempotent — re-running it skips templates that already exist by title. After seeding, tenants will see relevant template recommendations in the New Policy wizard.

Templates and rules can also be managed individually through the Platform Admin portal at /platform-admin/policy-templates and /platform-admin/template-rules.

Step 7 — Seed the HIPAA Assessment module (Optional)

If you plan to use the HIPAA & Data Privacy Assessment module, seed its questions and system administrator account:

pnpm seed:hipaa

This imports 30 HIPAA assessment questions into the hipaa_questions collection and creates a system administrator account for the HIPAA Admin Portal with the following default credentials:

Email: admin@powerdatainc.com
Password: HipaaAdmin2026!

Important: Change the default admin password after your first login by updating the hipaa_system_admins document in Firestore.

Step 8 — Start the application and workers

pnpm dev              # Start the Next.js application (port 9002)
pnpm worker:incident  # In a separate terminal — start the incident queue worker

Use this procedure when onboarding a new organization in the Social Works — Social Work Edition. Run it once per tenant, including after a full database wipe.

Prerequisites: The tenant must already exist in Firestore (i.e., the owner has completed company registration). You will need the tenant's Firestore document ID.

Finding the tenant ID:

Open the Firestore console.
Navigate to the tenants collection.
Find the document for the organization by its name. The document ID is the tenant ID.

Running the provisioning script:

# Dry run first — shows what will change without writing anything
pnpm provision:standalone <tenantId> --dry-run

# Apply when the dry run output looks correct
pnpm provision:standalone <tenantId>

What the script does:

Sets productMode: 'incident-standalone' on the tenant_subscriptions/{tenantId} document.
Sets enabledModules: ['dashboard', 'incidents'].
If a subscription document does not yet exist (e.g., after a wipe), creates one.
All other subscription fields (tier, billing email, status) are preserved on updates.

Expected output:

📋 Tenant found:
   ID:   abc123
   Name: City Social Services

📊 Current subscription state:
   productMode:    full
   enabledModules: ["dashboard","employees","incidents","policies","risk-assessment"]

✅ Updated existing subscription for "abc123".
   productMode    → 'incident-standalone'
   enabledModules → ["dashboard","incidents"]

🎉 Done. The tenant will see the standalone incident reporting UI on next login.

After running the script:

The tenant's users will see only Dashboard and Incidents in the navigation on their next login (or page refresh). No further configuration is required. To verify, check the tenant_subscriptions/{tenantId} document in Firestore and confirm productMode is "incident-standalone".

Note: This script is safe to re-run at any time. Running it on a tenant already in standalone mode is a no-op (same values are written again).

Individual Seed Commands Reference

Command	What It Seeds	When to Use
`pnpm seed:all`	Company profile fields, incident templates, risk question templates	First-time setup
`pnpm seed:assessment`	Question DAGs + risk scoring models	First-time setup, or after editing questions in the Risk Question Library
`pnpm seed:dags`	Question DAGs only (reads from Firestore `risk_question_library`)	After editing questions via the Platform Admin Risk Question Library
`pnpm seed:models`	Risk scoring models only	After changing scoring multipliers
`pnpm seed:questions`	Legacy flat question list	Rarely needed; legacy support
`pnpm seed:risk`	Risk assessment template (legacy format)	Rarely needed
`pnpm seed:demo`	Demo company with sample users and assets	Testing and demonstrations
`pnpm seed:counters`	Counter documents for auto-increment IDs	If counters are missing or corrupted
`pnpm seed:templates`	12 master policy templates + recommendation rules (idempotent)	First-time setup, or to add any catalog templates not yet in the database
`pnpm seed:hipaa`	HIPAA questions (30) + system admin account	First-time setup, or to reset HIPAA admin credentials
`pnpm seed:modules`	Module registry + default role permission matrix	First-time setup, or after adding new modules to the registry
`pnpm seed:modules:registry`	Module registry only (`modules_registry` collection)	After updating module definitions in `src/lib/modules/registry.ts`
`pnpm seed:modules:permissions`	Default role permissions only (`module_permissions` collection)	After changing the default permission matrix
`pnpm migrate:tenant-subscriptions`	Creates `tenant_subscriptions` documents for all existing tenants (idempotent)	First-time setup only; skips tenants that already have a subscription document
`pnpm migrate:product-mode`	Sets `productMode: 'full'` on all existing tenant subscriptions that lack the field (idempotent)	Run after deploying the standalone product mode feature; skip for tenants already manually set to `'incident-standalone'`
`pnpm verify:seed`	(Verification only — reads, does not write)	After any seeding operation

Database Cleanup & Troubleshooting

During development and testing, you may need to delete certain Firestore collections. Not all collections are safe to delete. The table below explains which collections can be removed and what the consequences are.

Collections That Must NOT Be Deleted

These collections are required for core features to function. Deleting them will break the application until they are re-seeded or re-created.

Collection	Why It Must Be Kept	How to Restore
`question_dags`	Contains all risk assessment questions. Without it, no assessment can be started. The application will attempt to auto-seed this on demand, but the auto-seed may not include the latest question updates.	Run `pnpm seed:dags`
`tenants`	Contains company profiles, NAICS codes, and social impact settings. These are created during company registration and cannot be re-seeded.	Cannot be restored — companies must re-register
`users`	Contains user accounts, roles, and profile data. Linked to Firebase Authentication.	Cannot be restored — users must re-register
`appConfig`	Contains RBAC permission mappings and subscription tier definitions.	Run `pnpm seed:rbac`
`tenant_subscriptions`	Contains each tenant's subscription tier, product mode, and the list of enabled modules. Without it, the Module Management system cannot determine which features are active.	Run `pnpm migrate:tenant-subscriptions && pnpm migrate:product-mode`
`modules_registry`	Contains the canonical list of all available modules. Used by the Module Management admin UI.	Run `pnpm seed:modules:registry`
`hipaa_questions`	Contains the 30 HIPAA assessment questions. Without it, no HIPAA assessment can be started.	Run `pnpm seed:hipaa`
`hipaa_system_admins`	Contains the HIPAA admin login credentials. Without it, no one can access the HIPAA Admin Portal.	Run `pnpm seed:hipaa`

Collections That Can Be Safely Deleted

These collections store runtime data that is regenerated during normal application use. Deleting them will not break the application, but users will lose their historical data.

Collection	What Happens If Deleted	Notes
`risk_assessments`	All in-progress and completed assessments are lost. Users can start new assessments.	Completed assessments auto-expire after 6 months anyway.
`assessment_audit_trails`	Audit log entries for question visibility decisions are lost. Assessments continue to work normally.	This collection is write-only during the assessment flow. It is never read by the assessment engine — it is only consumed by the admin audit trail viewer. Safe to delete during testing. See note below.
`incidents`	All incident records and their audit trails are lost.	Users can report new incidents.
`notifications`	All in-app notifications are lost.	New notifications are generated as events occur.
`seed_data`	Reference templates are lost. Does not affect running assessments.	Run `pnpm seed:all` to restore.
`risk_models`	Scoring multipliers are lost. Assessments can still be started but final score calculations may use fallback defaults.	Run `pnpm seed:models` to restore.
`hipaa_companies`	All registered HIPAA companies are lost. Admin must re-create them.	Re-create via the HIPAA Admin Portal.
`hipaa_participants`	All participant records are lost. Participants cannot log in until re-added.	Re-add via the HIPAA Admin Portal.
`hipaa_assessments`	All in-progress and completed HIPAA assessment records are lost. Participants can start new assessments.	Participants start fresh assessments.
`hipaa_certificates`	All issued certificates are lost. Participants who passed will need to retake to get a new certificate.	Participants retake the assessment.
`hipaa_admin_sessions`	All active admin sessions are invalidated. Admins must log in again.	Admins log in again at `/hipaa-admin/login`.
`module_permissions`	Custom role-permission overrides for modules are lost. The system falls back to the compiled default matrix — no features are broken.	Run `pnpm seed:modules:permissions` to restore defaults.
`module_audit_log`	The history of module enable/disable and permission changes is lost. Module state itself is unaffected.	Not restorable; entries are written-only as events occur.
`tenants/{id}/incident_audit_trail`	Per-incident audit history (status changes, metadata updates, HHS reports) is lost. Incidents themselves are unaffected.	Not restorable; entries are written-only as events occur.

About the `assessment_audit_trails` Collection

The assessment_audit_trails collection grows rapidly during testing because the DAG engine logs a visibility evaluation entry for every question node each time an assessment is started. For a typical assessment with 100+ questions, this creates 100+ audit trail documents per assessment session.

Can it be safely deleted? Yes. This collection is purely for compliance and debugging purposes. The assessment engine evaluates question visibility rules in memory and does not read from this collection. Deleting it will only affect the admin audit trail viewer (which will show no historical data). New audit entries will be created automatically when the next assessment is started.

Recommendation for testing: If Firestore usage or cost is a concern during development, you can periodically delete the assessment_audit_trails collection without any impact on assessment functionality.

Note: A dedicated admin UI for viewing and managing assessment audit trails is planned but not yet implemented. Once available, it will be accessible from the admin dashboard and will allow filtering by date, user, and assessment.

Full Database Wipe (Destructive)

To delete all Firestore collections and Firebase Authentication users (for example, to reset a development environment completely):

pnpm db:wipe

Warning: This is irreversible. All tenant data, user accounts, assessments, incidents, and seed data will be permanently deleted. You will need to re-run all seed commands and re-register all users afterward. Never run this against a production database.

After a full wipe, restore the application by running:

pnpm seed:all && pnpm seed:assessment && pnpm seed:templates && pnpm seed:modules && pnpm seed:hipaa && pnpm verify:seed

After users re-register their companies, run the tenant migrations to restore module access and product modes:

pnpm migrate:tenant-subscriptions && pnpm migrate:product-mode

Note: Social Works (standalone) tenants must have productMode: 'incident-standalone' re-set manually in Firestore after the migration, since migrate:product-mode sets all tenants to 'full'.

Frequently Asked Questions

Do I need to re-seed after updating the application? Generally no. Seed data is stable across updates. Risk questions are now managed via the Platform Admin Risk Question Library UI (/platform-admin/risk-questions). After editing questions or industry weights in that UI, use the Seed Control tab (or pnpm seed:dags) to push changes into the assessment engine.

Can I run seed commands on a database that already has data? Yes. Seed scripts use upsert logic — they will overwrite existing seed documents with fresh data without affecting tenant-created data like users, assessments, or incidents.

What if an assessment fails to start with a "DAG not found" error? Run pnpm seed:dags to restore the question_dags collection (requires active questions to be present in risk_question_library). The application also includes an auto-seed fallback, but running the seed command manually ensures you have the latest question set. Alternatively, use the Seed Control tab in the Platform Admin Risk Question Library.

Subscription Tiers

PRIAMtiv offers two tiers. Your organisation's tier is set at registration and can be changed by contacting support.

Starter

The Starter tier includes all core modules:

Dashboard
Employee management
Incident reporting and tracking
Risk assessment
Policy management
Team invitations

Growth

The Growth tier includes everything in Starter, plus:

Asset management — manage customers, suppliers, devices, and vehicles
Advanced risk assessment — NAICS-industry-aware DAG questionnaires
HIPAA compliance assessment
Advanced analytics

How to upgrade

Contact hello@priamtiv.com to upgrade your account from Starter to Growth.

What happens to my data if I downgrade?

Your data is preserved. Features that are no longer accessible on the lower tier will be hidden from the interface, but the underlying records remain in the database and will reappear if you upgrade again.

More modules will be documented here as they become available. For questions about a specific module, contact your system administrator.

Category	Description	Extra Fields
HIPAA Breach	Unauthorized access to, use of, or disclosure of Protected Health Information (PHI)	Breach type, PHI categories, individuals affected, discovery date
Data Privacy	Unauthorized collection, exposure, or misuse of personal data not covered by HIPAA	Data types involved, affected systems (optional)
General	All other incidents	None

PRIAM User Guide

Company Registration

Registering with Google (recommended)

Registering with Email

Step 1 — Organisation Details

Step 2 — Verify Email & Set Password

Signing In

Sign in with Email & Password

Sign in with Google

Risk Assessment

OVI — Organizational Vulnerability Index

Accessing Risk Assessment

Before You Begin

Step 1 — Set Your Social Impact Level

Step 2 — Resume or Begin

Step 3 — Navigate by Category

Step 4 — Answer Each Question

Step 5 — Save and Resume

Step 6 — Submit the Assessment

Step 7 — Review Your Results

Overall Score

Spider Chart (Category Breakdown)

Risk Matrix Heatmap

Recommendations

After the Assessment

Frequently Asked Questions

Policy Management

Policy Categories

Policy Lifecycle

Who Can Do What

Creating a Policy (Manager / Admin / Owner)

Template Update Notifications

Submitting for Approval

Review Thread (Pending Approval)

Approving or Rejecting a Policy (Admin / Owner)

Publishing a Policy (Admin / Owner)

Acknowledging a Policy (All Roles)

Editing a Draft

Renewing an Expiring or Expired Policy (Admin / Owner)

Company Statements & Settings-Level Policies

For the Product Team — Master Templates & Rules

Incident Reporting — Social Works Edition

Who Can Access This Edition

Roles in This Edition

Getting Started

Incident Management

Incident Statuses

Categories

Priorities

Reporting an Incident

Viewing Incidents

Viewing Incident Details

Updating an Incident

HIPAA Breach Notification Deadlines

Exporting Incidents as PDF

Analytics Dashboard

Automated Lifecycle

Notifications

Dashboard

Frequently Asked Questions

Module Management

Module Categories

Subscription Tiers

Enabling a Module

Disabling a Module

Module Dependencies

Role-Based Access Within a Module

Audit Log

Frequently Asked Questions

HIPAA & Data Privacy Assessment

How It Works

Before You Begin (Participants)

Step 1 — Log In

Step 2 — Resume or Begin

Step 3 — Answer Questions

Step 4 — Navigate Between Questions

Step 5 — Watch the Timer

Step 6 — Save and Resume

Step 7 — Submit the Assessment

Step 8 — Review Your Results

About the `assessment_audit_trails` Collection