Module Boundaries & Architecture code review rules

For changes that affect architecture, data models, external APIs, security posture, deployment topology, or cost (>10%), create an ADR in docs/adr/ using the standard template (Context, Decision, Consequences) and link the PR and issue IDs.

Ensure that factory method injection is used in `@Configuration` classes instead of `@Autowired` field injection.

Identify cases where a module imports itself. Self-imports are usually unintentional and can cause confusion or unnecessary dependencies. Suggest removing them.

Check for global variable usage (e.g., variables prefixed with `$`). Suggest using instance variables, constants, or dependency injection instead.

Provide a single permission check API (e.g., can(user, action, resource)) and reuse it across layers.

When accepting a slice or map from external snippet or returning one, consider copying it. This prevents unintentional modifications to the original data. For example, don't store a slice argument directly if the caller might modify it later; instead, make a copy for internal use.

Check if modules export mutable variables. Mutable exports can be modified by other modules, leading to unpredictable behavior. Recommend exporting immutable values instead.

Do not violate the project's architecture boundaries. Examples of violations: Controllers/Views directly querying the database; UI importing infrastructure modules; domain modules importing unrelated domains. If the repo defines boundaries (lint rules, Nx tags, dependency-cruiser, ARCHITECTURE.md), enforce them. When in doubt, route all I/O through the intended service/repository layer and keep domain logic isolated.

Check if the `__all__` list in a module contains titles that are not defined. Listing undefined titles can cause `ImportError` when performing wildcard imports.

Controllers handling multiple concerns become harder to maintain and test. Split responsibilities into separate controllers.

In JS/TS workspaces, imports must use workspace package names (as defined in each package.json and exports) rather than relative paths crossing package boundaries.

Authorize every request by role and resource scope. Policies must default-deny and require explicit allow; privileged roles (admin, auditor) must be rare and reviewed quarterly.

Load and validate environment/config once during startup; inject settings into modules instead of re-reading env.

Ensure that constructor injection is used instead of field injection (`@Autowired` on fields) in Spring components for better testability.

Obtain collaborators via constructor injection (or a DI container) instead of new/service locators in business code.

Keep UI/controllers thin; move domain logic to services or domain objects.

For applications, styles in a top-level `App` component and in layout components may be global, but all other components should always be scoped. This can be achieved through CSS modules, class-based strategies like BEM, or the `scoped` attribute in Single-File Components.

Request dependencies via constructors and register them with the DI container; avoid new-ing services in code.

Maintain a single go.work at the monorepo root listing all local modules via use directives. Forbid go.mod replace directives that point to sibling modules (e.g., ../pkg) in workspace modules.

Ensure `dart:html`, `dart:js`, and `dart:js_util` are only used in Flutter web plugins to prevent runtime errors in non-web environments.

Detect the use of default exports. Named exports provide better clarity, maintainability, and prevent issues when refactoring.

Ensure that classes with only static members are converted to top-level functions or extensions. Avoid unnecessary class instantiation.

Flag usages marked as @deprecated (via JSDoc or types) and propose the documented alternative when available.

Ensure that titlespace structures are not overly deep. Favor a flat, organized structure to enhance readability and navigation.

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.

Expose DTOs/ViewModels from API endpoints; avoid leaking persistence/domain entities directly.

Detect relative imports (e.g., `from .module import x`). Relative imports can break if the project structure changes. Recommend using absolute imports (`from package.module import x`) for better clarity and maintainability.

Pass dependencies (clients, sessions, configs) into functions/classes instead of creating them internally.

Always use ES Modules (`import` and `export`) for managing dependencies and organizing code in Vue applications. Avoid non-standard module systems or global namespace pollution.

Expose read-only views (IReadOnlyList/IReadOnlyCollection) from APIs that should not allow mutation.

Check if the code imports individual classes or functions instead of the entire module. Directly importing specific classes or functions can clutter the titlespace and increase naming conflicts. Recommend importing the module and referencing items explicitly.

Prefer the most restrictive access modifier that works (private/internal) and expose only necessary members.