Imported from rogers-group-inc/polaris (
.claude/skills/polaris-change-impact/SKILL.md). Install upstream withnpx skills add rogers-group-inc/polaris --skill polaris-change-impact. Copyright stays with the author.
Polaris change impact (the touches index)
A lookup index for cross-cutting invariants and per-service relationships. It answers
"if I change X, what else touches it?" without reading every consumer, and names the
canonical backend patterns to model new work after ("there are five places that already
do this — which one is the reference?"). The UI counterpart is polaris-ui-canon.
How to use
- Before changing a service or a shared invariant, find its section here (tables below).
- Walk the Used by / Writers / Readers lists to see what depends on the thing you're touching.
- Run through the When changing this checklist before you commit.
- Keep this index current. If your change moved writers/readers, broke an invariant, or
invalidated a checklist item, fix the entry in the same commit (
/polaris-docs-sync).npm run check:docsfails on a service with no## services/<name>.tsentry.
Format
Per-service sections: What it owns / Public API / Cross-service deps /
Used by (file → symbol — purpose) / Invariants / When changing this.
Cross-cutting sections swap Used by for Writers / Readers.
Pattern sections: What it is / Canonical implementation / Key conventions /
When adding a new instance — copy the canonical's shape rather than inventing a parallel one.
Code references are
path/file.ts → symbolName()— never line numbers, they drift. Grep the symbol name to locate it.
Cross-cutting concerns (one file each, under references/cross-cutting/)
| Concern | Read when |
|---|---|
| five-state-monitor-machine | anything sets or reads monitorStatus / consecutiveFailures |
| asset-source-projection | a discovery source writes an Asset field; AssetSource priority |
| windows-os-name-correction | os / osVersion on Windows hosts (rule 28) |
| polling-method-resolver | per-stream polling method, the four tiers, pollingCompatibility.ts |
| vendor-snmp-knowledge-boundary | any SNMP OID or vendor MIB symbol in code, BUILT_IN_OIDS, a new SNMP collector, noEnterpriseOids.test.ts failing |
| integration-type-onboarding | adding an 8th integration type (~30-callsite checklist) |
| fmg-fortigate-parity-surfaces | a FortiManager feature that must also ship on standalone FortiGate |
| asset-write-time-clamps-and-shadow-writes | the src/db.ts Prisma extension hooks |
| asset-management-access | Open HTTPS / SSH / RDP verbs, allowaccess |
| asset-last-seen-presence | lastSeen, bumpLastSeen, presence verification (rule 12) |
| asset-change-events | firmware / switch-port / AP / gateway change Events |
| reservation-push-lifecycle | pushStatus, queued push, retry, FortiGate DHCP writes |
| fortigate-snmp-location-and-coord-writeback | sysLocation, lat/long, coordSource, geocoding (the Nominatim → Census provider chain) |
| fortinet-infra-dhcp-binding | dhcpBinding, infra reservations (rule 23) |
| dns-resolved-reservations | dns_resolved rows (rule 11) |
| location-codes | a: b: f: r: jb: parsing (rule 15) |
| asset-tag-mutators | anything that adds or strips Asset.tags |
| dependency-aware-monitoring-suppression | dependencySuppressed, the DAG, Dep. Down (rule 38) |
| fortinet-parent-key-resolution | resolving a switch/AP's controlling gate — never by hostname |
| verbose-debug-mode | verboseLogging on an integration |
| pgbouncer-compatibility | anything needing a direct Postgres connection |
| schema-migrations-and-prisma-client-lifecycle | writing a migration, regenerating the client, update scripts |
| observability-metrics | adding / renaming a polaris_* metric |
| tiered-sample-retention | sample tables, rollups, retention windows, TimescaleDB chunks |
| server-side-list-tables | a paginated / filtered list endpoint |
| csp-inline-script-policy | any inline <script> or new page |
| dynamic-roles-permission-matrix | function keys, levels, role snapshots |
| sso-login-and-group-mapping | OIDC / LDAP / SAML / App Proxy login, group → role |
| alert-acknowledgement | acknowledge from email / push / in-app (rule 25) |
| automation-action-types | the four action types and the eight action locations |
| polaris-agent, polaris-agent-build, deployment | moved: polaris-agent/references/cross-cutting-polaris-agent*.md, polaris-deploy/references/cross-cutting-deployment.md |
Per-service entries (grouped, under references/services/)
| Group file | Services |
|---|---|
| alerting-engine | notificationEngine, notificationRuleService, notificationService, notificationTypes, notificationChangeEvents, downDetectionService, probeLossQuery, automationTestService |
| alerting-scope-dimensions | deviceFilterService, scopeRelationIndex, notificationDimensionService, notificationCadenceService, regionScopeService, maintenanceScheduleService, automationActionService |
| alerting-delivery | notificationDeliveryService, notificationEscalationService, notificationRecipientService, notificationPreferenceService, notificationChannelService, pushSubscriptionService, alertChartService, alertBrandService, alertInterfaceService, contactService, directorySyncService, directorySearchService, automationScriptService, automationScriptRunner |
| monitoring-collection | monitoringService, probePatchBuffer, interfaceInventoryService, interfaceTopologyService, apRadioService, arpTableService, peerInferredLldpService, agentlessHostService, agentlessProcessService, monitorOverrideService, osEventLogService, logFlagRuleService |
| snmp-mibs-profiles | oidRegistry, stdMibLibrary, mibService, mibParserUtils, vendorTelemetryProfiles, manufacturerProfileService, manufacturerAliasService |
| samples-timeseries | sampleWriteBuffer, sampleRollupService, sampleRetentionService, sampleHistoryService, sampleQueryRouter, probeOutageService, timescaleService, storageForecastService, capacityService, capacityAdvisorService, capacityDbIo |
| discovery-fortinet | fortimanagerService, fmgWorker, fmgActivityService, fortigateService, fortigateCoordPushService, fortigateLocationService, descriptionSyncService, reservationPushService, integrationHealthService, discoveryCancelWatchdog, discoveryDurationService, discoveryAutoAbortService, discoveryRunState, geocoderService |
| discovery-directory-cloud | entraIdService, activeDirectoryService, azureArcService, vcenterService, windowsServerService, presenceVerificationService, ldapClient, intunePublishService, arcPublishService |
| ipam-reservations | subnetService, subnetRefreshService, subnetArchiveService, subnetChassisConflictService, subnetExclusionService, blockService, ipService, reservationService, reservationStaleService, dnsResolvedReservationService, arpPrimeService, allocationTemplateService, utilizationService, networkScanService, networkScanRunner, duplicateIpConflictService, ipOverrideService, ipContextService, dnsService |
| assets-inventory | assetMergeService, assetGhostMergeService, assetTypeService, assetQuarantineService, assetSourcePriorityService, assetSightingService, assetIpHistoryService, assetUpstreamService, dependencyTreeService, connectionPathService, tagAssignmentService, discoveredHostnameService, projectionDriftService, macAddressService, ouiService |
| assets-auto-monitor-pins | autoMonitorInterfacesService, autoMonitorStorageService, massPinService |
| auth-identity | azureAuthService, oidcAuthService, ldapAuthService, entraProxyAuthService, ssoProvisioning, groupMappingService, roleService, apiTokenService, totpService, credentialService, sshHostKeyService, sshOnboardingScript, windowsSshOnboardingService, loginAccessService, apiDocsAccessService |
| settings-platform | settingsStore, serverSettingsService, brandingService, brandLogoService, appIconService, backupService, backupScheduleService, updateService, queueService, eventLogService, eventArchiveService, nginxApplyService, nginxConfigParser, nginxRenderer, proxyConfigService, privilegedSysadmin, dashSettingsService, dashRoleSnapshotService, weatherProxyService, deviceIconService, certInfo |
| agent-services | agentInstallService, agentInstallScripts, agentAutoDeployService, agentBuildService, agentChannelService, agentTokenService, agentCommandService, agentCommandWake, serviceInventoryService |
| dashboards-maps-tables | mapRegionService, regionHierarchyService, topologyLayoutService, applicationMapService, appMapDiscoveryService, savedDashboardService, savedFilterService, tableTabsService, userDashboardService, nocDashboardService, searchService |
A new service goes in the group whose "What it owns" it most resembles; when in doubt,
grep -l "## services/<sibling>.ts" references/services/*.md to find where its siblings sit.
Canonical backend patterns (under references/patterns/)
- backend-patterns-data.md — per-instance multi-lane worker; cross-asset graph derivation + persisted DAG; serialized check-then-insert (advisory lock); encrypt-at-rest for a JSON config column; server-generated keypair; current-state table refreshed per scrape (delete-replace); high-volume append-only time-series writes (batch-flush buffer); tiered rollups; operator-declared value mapping → alertable dimension.
- backend-patterns-integration.md — Setting-backed admin CRUD with reconciler; Prometheus metric instrumentation; per-integration verbose debug logging; permission-gated route + function key; queue-on-transient-failure with retry tick; outbound multi-channel delivery; deferred alert-email content; integration type (config + discovery + sync + modal).
Each pattern section carries What it is (one-sentence scope), Canonical implementation (entry-point path/file.ts → symbolName()), Key conventions (data shape, helpers, persistence, refresh model) and When adding a new instance (checklist before merging).
Only diverge from a canonical when the new surface genuinely needs something it doesn't — and note the divergence in your PR.
File map (under references/file-map/)
The repository tree with a purpose note per file: root-docs ·
public-1 · public-2 ·
src-api-dash-setup-models ·
src-services-1 · src-services-2 · src-services-3 ·
src-jobs · src-utils-1 · src-utils-2 ·
tests. Every src/services|jobs|api/routes|utils file must appear in one of them (npm run check:docs).
Services are listed in concern order, not alphabetically — grep -l "name.ts" references/file-map/*.md.