Module Boundaries & Architecture rules

Ensure that large classes with multiple responsibilities are refactored into smaller, more manageable classes.

Do not use global (package-level) variables for mutable state whenever possible. Instead, encapsulate state in structs or pass it as parameters. If you must use a global variable (for configuration or caching), protect it with mutexes if concurrent access is possible and document its usage.

Do not use global variables to share data across your program. Prefer passing values as function parameters or using configuration objects. Limiting variable scope makes code more predictable and less prone to side effects.

Ensure that imports are explicitly listed and avoid using wildcard imports (`import package.*;`).

Route all analytics events through a single service/helper instead of calling the SDK directly from widgets and blocs.

Whenever a build system is available to concatenate files, each component should be in its own file.

Provide a single updater that applies deltas/patches to messages rather than multiple ad-hoc updaters.

Factor shared before_actions/filters/error handling into ApplicationController or a base controller.

Avoid prop drilling translation functions/objects; expose shared accessors (e.g., a global translation service or context API).

Always specify access levels (public, private, protected) when declaring class properties and methods. Don’t use the old `var` keyword for properties. Explicit visibility clarifies intent and prevents unintended access.

If the PR introduces or expands usage of deprecated libraries/patterns the team is migrating away from (e.g., Moment.js, React Class Components), block and suggest the modern replacement. If the repo includes a migration guide (e.g., `docs/migration.md`, `CONTRIBUTING.md`, `docs/adr/*`), follow it and propose the equivalent snippet. If no guide exists, use an available web/search MCP to propose a safe, modern alternative and ask for confirmation of project standards.

Ensure that imported variables are not reassigned. This can cause runtime errors, especially in TypeScript. Modify object properties instead of reassigning variables.

Move complex domain calculations out of controllers/handlers into services or private helpers.

Move domain-specific processing (validation, normalization, mapping) into cohesive services instead of scattering it across controllers/handlers.

Factor repeated HTTP call setup/parsing/retry into a reusable helper or client.

Move repeated domain rules into reusable methods/services; keep controllers and handlers thin.

Move repeated domain calculations/transformations into named functions or service classes; keep controllers/scripts thin.

Move domain behavior from controllers/views into models or service objects.

Avoid implicit communication between parent and child components, such as using `this.$parent`, `this.$root`, or directly mutating props received from the parent. Prefer explicit communication via props down and events up.

Use private fields with accessors; expose the narrowest visibility that satisfies usage.

Default to private visibility; expose the minimal surface and prefer val with private set when mutation is needed.

Check if private or `file`-scoped classes that are never inherited are explicitly marked as `sealed` to indicate they are final.

Place cross-controller view helpers in ApplicationHelper (or a shared module) for reuse.

Perform one-time configuration/dependency validation at process startup (init/bootstrap). Avoid doing it inside per-request middleware/interceptor factories.