MyAiConfiguration/shared/rules/angular.md

Angular Code Guidelines

• Use modern Angular patterns and current framework conventions.
• Prefer standalone components, directives and pipes for new code.
• Avoid introducing NgModule unless the existing project architecture requires it.
• Keep components small and focused.
• Keep templates simple.
• Move complex logic out of templates.
• Keep business logic out of components where practical.
• Prefer services, facades or dedicated domain logic for non-trivial behavior.
• Avoid god components and god services.
• Keep dependencies explicit.
• Prefer composition over inheritance.
• Avoid unnecessary abstractions.
• Avoid unnecessary wrapper components.
• Follow the existing project architecture unless there is a strong reason to change it.

Components

• Use ChangeDetectionStrategy.OnPush unless there is a concrete reason not to.
• Prefer signal-based state for local component state.
• Prefer computed for derived state.
• Prefer effect only for actual side effects.
• Do not use effect as a replacement for normal data flow.
• Keep component state minimal.
• Avoid duplicating derived state.
• Prefer immutable state updates.
• Avoid direct mutation of shared state.
• Keep inputs and outputs strongly typed.
• Prefer signal-based inputs and outputs when consistent with the project.
• Avoid unnecessary two-way binding.
• Avoid unnecessary component-to-component coupling.
• Prefer explicit data flow from parent to child and explicit events upward.
• Do not expose internal component state unnecessarily.
• Use lifecycle hooks only when required.
• Avoid complex initialization logic inside constructors.

Templates

• Keep expressions short and readable.
• Do not execute expensive methods from templates.
• Avoid function calls in templates when their result can be derived or cached.
• Avoid complex conditions directly in markup.
• Prefer derived state in TypeScript over repeated template expressions.
• Use Angular control flow syntax such as @if, @for and @switch for new code.
• Always provide stable tracking for repeated collections.
• Avoid deeply nested template structures.
• Split large templates into focused components when it improves maintainability.
• Avoid unnecessary DOM elements.
• Use semantic HTML.
• Prefer native HTML behavior before custom implementations.
• Keep accessibility in mind when choosing elements and interactions.

Signals and State

• Prefer signals for local and synchronous reactive state.
• Prefer computed for derived values.
• Keep signals private when external mutation is not intended.
• Expose readonly state where practical.
• Avoid storing values that can be derived from existing state.
• Avoid circular signal dependencies.
• Avoid side effects inside computed.
• Keep effects small and deterministic.
• Clean up resources created by effects.
• Do not use global state unless multiple unrelated parts of the application genuinely need it.
• Do not introduce a state-management library without a clear requirement.

RxJS

• Use RxJS for asynchronous streams, events and complex reactive flows.
• Do not use RxJS when simple synchronous signals are sufficient.
• Prefer declarative observable pipelines.
• Avoid nested subscribe.
• Avoid manual subscriptions where async, signals or framework helpers are sufficient.
• Prefer takeUntilDestroyed or equivalent Angular lifecycle integration for manual subscriptions.
• Always consider subscription lifetime.
• Avoid memory leaks from unmanaged subscriptions.
• Use the correct flattening operator for the required semantics.
• Do not use switchMap, mergeMap, concatMap or exhaustMap interchangeably.
• Avoid unnecessary Subject usage.
• Prefer exposing observables instead of exposing mutable subjects.
• Prefer BehaviorSubject only when a current value is actually required.
• Avoid excessive observable chains for simple state.
• Avoid converting repeatedly between signals and observables without need.

Dependency Injection

• Prefer Angular dependency injection for application services.
• Keep injected dependencies minimal.
• Avoid service locator patterns.
• Prefer inject() where it improves readability and is consistent with the project.
• Do not inject services that are not used.
• Scope services intentionally.
• Prefer application-wide singletons only for truly shared stateless or coordinated state.
• Avoid storing request-specific or component-specific mutable state in root services.
• Use injection tokens for configuration or abstractions where appropriate.
• Do not create interfaces only to satisfy dependency injection when no abstraction is needed.

Services

• Keep services focused on a clear responsibility.
• Avoid large catch-all services.
• Separate API access, domain logic and UI state where practical.
• Avoid leaking transport models throughout the application.
• Do not expose mutable internal state directly.
• Prefer readonly APIs for state consumers.
• Avoid hidden side effects.
• Keep service methods predictable.
• Do not use services merely to move poorly structured component code elsewhere.

HTTP and APIs

• Keep API access centralized and strongly typed.
• Prefer dedicated API clients or data-access services.
• Do not use any for API responses.
• Treat all server responses as untrusted at runtime.
• Validate external data when the contract is security- or correctness-critical.
• Keep DTOs separate from domain models when their responsibilities differ.
• Avoid duplicate API calls.
• Cache only when the invalidation strategy is clear.
• Avoid manual URL string construction when typed helpers or centralized endpoints are available.
• Use interceptors only for cross-cutting concerns.
• Do not put unrelated business logic into HTTP interceptors.
• Handle cancellation where appropriate.
• Handle expected error states explicitly.

Forms

• Prefer reactive forms for non-trivial forms.
• Keep forms strongly typed.
• Avoid untyped forms.
• Keep validation rules centralized and reusable where practical.
• Validate on both client and server where required.
• Never treat client-side validation as a security boundary.
• Keep form state separate from domain state when useful.
• Avoid large components that combine layout, validation, persistence and business logic.
• Display validation errors consistently.
• Preserve user input when recoverable errors occur.

Routing

• Keep route definitions explicit and predictable.
• Prefer lazy loading for larger feature areas.
• Avoid loading large feature bundles eagerly without need.
• Use route guards only for navigation behavior, not as a security boundary.
• Authorization must still be enforced on the backend.
• Keep resolvers focused.
• Avoid expensive work during navigation unless required.
• Keep route parameters strongly typed at application boundaries where practical.
• Do not rely on client-side routing state for sensitive authorization decisions.

Performance

• Use OnPush.
• Use stable tracking in loops.
• Avoid unnecessary change detection triggers.
• Avoid repeated expensive template calculations.
• Avoid unnecessary subscriptions.
• Avoid unnecessary DOM rendering.
• Lazy-load large features and heavy dependencies where appropriate.
• Avoid large initial bundles.
• Avoid importing full libraries when only a small part is required.
• Avoid unnecessary deep cloning.
• Avoid unnecessary object and array recreation in hot paths.
• Keep state updates targeted.
• Avoid unnecessary global state updates.
• Measure bundle size and runtime performance before micro-optimizing.
• Prefer architectural improvements over template-level micro-optimizations.

Security

• Treat all external data as untrusted.
• Never bypass Angular sanitization without a verified reason.
• Avoid direct DOM manipulation.
• Avoid innerHTML with untrusted content.
• Avoid bypassSecurityTrust* unless explicitly required and the input is fully controlled.
• Never expose secrets in frontend code.
• Never store sensitive credentials in the Angular application.
• Do not rely on frontend checks for authorization.
• Enforce authentication and authorization on the backend.
• Avoid leaking sensitive information through logs or error messages.
• Use secure cookie or token handling according to the application's authentication architecture.
• Avoid storing sensitive tokens in insecure browser storage without a deliberate security decision.
• Do not disable security controls for convenience.

DOM and Browser APIs

• Prefer Angular APIs and declarative templates over direct DOM manipulation.
• Use Renderer2 only when direct rendering abstraction is actually needed.
• Avoid accessing globals directly when it harms testability or SSR compatibility.
• Consider SSR and hydration compatibility for browser-specific code.
• Guard access to window, document, localStorage and similar browser-only APIs when SSR is supported.
• Clean up event listeners, observers and timers.
• Avoid layout thrashing in performance-sensitive code.

Accessibility

• Use semantic HTML.
• Preserve keyboard navigation.
• Ensure interactive elements are actually interactive elements.
• Do not replace buttons with clickable div elements.
• Provide labels for form controls.
• Maintain visible focus behavior.
• Use ARIA only when native HTML semantics are insufficient.
• Avoid unnecessary custom widgets.
• Keep accessible names and states synchronized with UI state.

Styling

• Keep styles scoped and predictable.
• Avoid unnecessary global CSS.
• Follow the project's styling strategy consistently.
• Avoid excessive specificity.
• Avoid !important unless there is a concrete reason.
• Prefer reusable design tokens and shared styles over duplicated magic values.
• Keep component styles focused on component concerns.
• Avoid styling based on fragile DOM structure.
• Do not mix multiple styling approaches without need.

Testing

• Test behavior, not implementation details.
• Prefer focused component tests.
• Test critical user interactions.
• Test services and domain logic independently where useful.
• Avoid brittle tests coupled to internal structure.
• Avoid excessive mocking.
• Mock external boundaries rather than internal implementation details.
• Keep tests deterministic.
• Avoid time-dependent tests without controlled clocks.
• Avoid network-dependent tests without proper isolation.
• Keep test setup minimal and readable.
• Update tests when refactoring changes structure but not behavior.

Architecture

• Keep UI, application, domain and data-access concerns separated where practical.
• Organize code by feature rather than by technical file type when it improves cohesion.
• Avoid circular dependencies.
• Avoid cross-feature imports without a clear contract.
• Keep shared code genuinely shared.
• Do not move feature-specific logic into generic shared modules.
• Avoid dumping unrelated helpers into global utility files.
• Keep public APIs of feature areas small.
• Avoid exposing internal implementation details across feature boundaries.
• Prefer local ownership of state and logic.

Code Quality

• Use strict TypeScript settings.
• Avoid any.
• Avoid unnecessary type assertions.
• Avoid non-null assertions unless safety is guaranteed.
• Prefer modern, readable syntax.
• Use descriptive names.
• Avoid vague names such as data, item, value or temp when better names exist.
• Remove dead code.
• Remove unused imports and dependencies.
• Remove commented-out code instead of keeping it in source files.
• Do not add comments unless the user explicitly requests them.
• Treat Angular, TypeScript and lint warnings seriously.
• Do not suppress diagnostics without a concrete reason.
• Prefer correctness, security and maintainability over cleverness.

Dependency Rules

• Prefer Angular and browser platform capabilities before adding third-party libraries.
• Do not add dependencies without a clear benefit.
• Avoid libraries that duplicate existing framework functionality.
• Avoid abandoned or poorly maintained packages.
• Keep Angular package versions aligned.
• Do not mix incompatible Angular package versions.
• Respect the existing lockfile and package manager.
• Avoid unrelated dependency upgrades.

Performance Priority

Prioritize Angular performance work in this order:

• Application architecture
• Network and API behavior
• Bundle size and lazy loading
• State architecture
• Change detection
• Rendering and DOM complexity
• RxJS and subscription behavior
• Memory allocations
• CPU micro-optimizations

Never optimize based purely on assumptions.

Safety Rule

• Angular frontend code is never a security boundary.
• Client-side validation, guards, hidden controls and disabled UI elements do not replace backend enforcement.
• Do not bypass Angular's built-in security mechanisms without a verified and explicit reason.
• Prefer safe framework defaults over custom low-level behavior.