---
title: Key Logic - Done
slug: key-logic-done
createdAt: 2025-04-07T17:32:38.078Z
---

## Key Logic Overview

This section summarizes some of the core logic flows and architectural decisions reflected in the proposed database schema.

- **Pulse Score Calculation:**
  - The primary "Pulse Score" (0-100) is calculated per `PulseCheckInstance` upon completion and aggregated monthly per contact in `MonthlyContactMetrics`.
  - It uses a proprietary weighted average of three components:
    1. **Face Ratings:** Average score from SmileyScale questions (Happy=100, Neutral=50, Unhappy=0).
    2. **Referral Likelihood:** Score mapped from the NPS-style question response (Promoter=100, Passive=50, Detractor=0).
    3. **Comment Sentiment:** Score (0-100) derived from AI analysis of the `Responses.comment_text` (if provided).
  - **Adaptive Weighting:** If a comment is *not* provided (`Responses.comment_text` is NULL), the algorithm MUST adjust the weighting of the Face Ratings and Referral Likelihood components to ensure the final Pulse Score fairly represents the available feedback.
  - See [Pulse Score Calculation - Done](docId\:V8XWkhN2y2afV1r0ztwcW)&#x20;
- **NPS® Dashboard Calculation:**
  - The Net Promoter Score® displayed on the main PulseCheck dashboard is calculated using the standard formula: `(% Promoters) - (% Detractors)`.
  - This calculation is based on *all relevant responses* to the NPS-type question within the selected `PulseCheck`, Period/Instance, and applied Tag filters for that specific dashboard view. It is distinct from the 100/50/0 mapping used for the Pulse Score component.
- **Multi-Language Support (Pro Plan):**
  - Controlled by the `Plans.multi_language_enabled` flag. Non-Pro plans should not load related JS or data.
  - **Survey Display:** Uses browser language detection. Falls back to 'en' if the detected language isn't supported. Fetches translations from `QuestionTranslations` and corresponding UI text translations (managed via resource files or a dedicated table). Records the language used in `Responses.response_language_code`.
  - **Email Template Content:** Email language is determined by `Contacts.language_preference` (fallback 'en'). The system first checks `EmailTemplateContent` for user-customized content in the target language. If none exists, it falls back to system defaults (managed via application resource files is recommended).
  - **Auto-Translation (Pro Plan):** When a user saves edits to an email template (e.g., the 'en' version), an automated translation process is triggered to update the content for other supported languages in `EmailTemplateContent`, marking them appropriately (`is_custom = FALSE`).
- **Email Template Defaults vs. Customizations:**
  - System default email templates (managed internally, e.g., via resource files) are used as the base.
  - When a `PulseCheck` is created, default content for all supported languages is seeded into `EmailTemplateContent` for that PulseCheck's templates, marked as `is_custom = FALSE`.
  - When a user edits and saves a template for a specific language, that `EmailTemplateContent` record is updated and marked `is_custom = TRUE`. Auto-translations triggered by this save are marked `is_custom = FALSE`.
  - The "Revert to Default" action re-populates `EmailTemplateContent` from the system defaults and sets `is_custom = FALSE` for all languages for that template.
- **Scheduling and Instance Creation:**
  - A backend scheduler service reads `PulseChecks` configuration (`frequency`, `schedule_start_date`, `schedule_details`).
  - On the calculated send date, it identifies subscribed contacts (`ContactPulseCheckSubscriptions`) and creates a `PulseCheckInstances` record for each.
  - It then triggers the initial email send process for these instances.
- **Plan Limits & Overage Logic:**
  - Before adding contacts via `ContactPulseCheckSubscriptions`, the system checks the current count against the `Plans.contact_limit` associated with the `PulseCheck`.
  - UI elements (like the "Assign to PulseCheck" modal) visualize current vs. projected capacity and gate actions based on limits and the `Plans.allows_overages` flag.
  - A separate process (likely tied to the billing system) is needed to track and invoice for actual overages incurred on Pro plans based on `purchased_overage_bundles` or contact counts exceeding the base limit during a billing cycle.
- **Tagging and Filtering:**
  - Tags are defined workspace-wide in the `Tags` table, including `tag_type` and `dropdown_options`. The `is_filterable` flag controls visibility in filter UIs.
  - Tags are assigned to contacts via the `ContactTags` table, storing the `tag_value`.
  - Filter modals use defined, filterable tags to allow users to narrow down data views (e.g., Audience list, Dashboard). Applying filters modifies the underlying data queries using `JOIN` and `WHERE` clauses on `ContactTags`.
- **Bounce Handling:**
  - Requires integration with the email sending service to detect bounces.
  - Hard bounces should update `Contacts.status` to 'Bounced' and set `Contacts.is_bounced` to TRUE. Bounce details are logged in the `Bounces` table.
  - Bounced contacts should likely be excluded from future sends.
- **User Roles (V1 Simplification):**
  - The initial launch assumes a single 'Admin' role within a workspace (`Roles`, `WorkspaceMembers`). All workspace members have full permissions. The structure allows for adding more granular roles later.
- **Data Aggregation for Performance:**
  - The `MonthlyContactMetrics` table stores pre-calculated aggregates (average Pulse Score, NPS status, etc.) per contact per month to improve performance on contact-level dashboards and trend displays.
  - Similar aggregation might be considered at the overall PulseCheck level (`MonthlyPulseCheckMetrics`) if workspace-level or cross-PulseCheck reporting becomes a performance bottleneck.

