Key Logic - Done

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 face ratings average score from smileyscale questions (happy=100, neutral=50, unhappy=0) referral likelihood score mapped from the nps style question response (promoter=100, passive=50, detractor=0) 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 docid\ v8xwkhn2y2afv1r0ztwcw 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