Developer Code Guidelines & Best Practices

Relevant source files

The following files were used as context for generating this wiki page:

• best-practices.md
• implementation_plan.md
• sunrise-angular/src/app/core/services/seo.service.ts
• sunrise-angular/README.md
• task.md
• sunrise-angular/src/assets/assets/css/global.css

Developer Code Guidelines & Best Practices define the technical standards and architectural patterns for the Sunrise Communication project. This documentation ensures high code quality, accessibility compliance, and performance optimization across the Angular v22 ecosystem.

The scope covers TypeScript implementation, Angular component architecture, state management via Signals, and SEO-driven development. Developers must follow these guidelines to maintain consistency while building lead-generation features like the Products & Solutions Catalog.
Sources: best-practices.md:1-5, implementation_plan.md:13-25

Framework & Environment

The project operates on Angular version 22.0.7 using the Angular CLI. It utilizes @angular/ssr for Server-Side Rendering (SSR) with an Express server to optimize search engine discovery and initial load performance.
Sources: sunrise-angular/README.md:1-5, implementation_plan.md:14-16

Project Operations

Standard CLI commands manage the development lifecycle:

• Start Server: ng serve launches the local environment at http://localhost:4200/.
• Build Project: ng build compiles artifacts into the dist/ directory with production optimizations.
• Test Suite: ng test executes unit tests via the Vitest runner.
  Sources: sunrise-angular/README.md:7-40

Angular Development Standards

Component Architecture

Sunrise Communication utilizes Standalone Components by default. The project follows specific decorator and binding rules:

• Standalone: Do not set standalone: true in decorators; it is the default in v20+.
• Change Detection: Do not set ChangeDetectionStrategy.OnPush explicitly; it is the default in v22+.
• Host Bindings: Place host bindings inside the host object of the @Component decorator instead of using @HostBinding or @HostListener.
• Communication: Use input() and output() functions rather than decorators. Use model() for two-way data binding.
  Sources: best-practices.md:7-13, best-practices.md:20-24, implementation_plan.md:23-25

State Management & Logic

Signals are the primary mechanism for state management and derived data.

• Local State: Use signal() for component-specific data.
• Derived State: Use computed() for values derived from other signals.
• Synchronization: Use linkedSignal() for state that must stay synchronized across multiple reactive sources.
• Modifications: Use update or set to modify signals; do not use mutate.
  Sources: best-practices.md:11-12, best-practices.md:32-35, implementation_plan.md:104-122

Template Syntax

Templates must remain simple and use native control flow for performance.

• Control Flow: Use @if, @for, and @switch instead of legacy directives like *ngIf or *ngFor.
• Dynamic Styling: Use class and style bindings instead of ngClass or ngStyle.
• Image Optimization: Use NgOptimizedImage for all static images to ensure efficient loading.
  Sources: best-practices.md:28-29, best-practices.md:38-40, implementation_plan.md:24-25

Service Architecture

Services must be designed around a single responsibility and utilize the latest Angular dependency injection patterns.

• Decorator: Prefer the @Service decorator for new singleton services instead of @Injectable({providedIn: 'root'}).
• Injection: Use the inject() function for dependency acquisition instead of constructor injection.
• Data Fetching: Use HttpClient with provideHttpClient(withFetch()) to enable SSR transfer state.
  Sources: best-practices.md:44-47, implementation_plan.md:95-99, sunrise-angular/src/app/core/services/seo.service.ts:13-17

Service Implementation Flow

The following diagram illustrates the standard signal-based service architecture used for data-driven modules like the ProductService.

Diagram showing the internal architecture of services using Writable and Computed Signals.
Sources: implementation_plan.md:86-102

SEO & Semantic Entity Architecture

The project implements a machine-to-machine discovery layer using structured data and technical manifests.

• JSON-LD @graph: The SeoService outputs a unified @graph including LocalBusiness, Service, Product, and FAQPage entities.
• AEO Optimization: Use "Inverted Pyramid" definitions and HowTo schemas to target AI search answer boxes.
• Technical Manifests: Maintain public/llms.txt and public/llms.json for AI agent consumption.
  Sources: task.md:13-21, sunrise-angular/src/app/core/services/seo.service.ts:46-120

SEO Data Flow

Sequence of operations when updating SEO metadata and structured data during navigation.
Sources: sunrise-angular/src/app/core/services/seo.service.ts:46-75, implementation_plan.md:165-185

Accessibility (a11y) & Styling

Requirements

All code must comply with the following accessibility standards:

• AXE Compliance: All components must pass AXE automated accessibility checks.
• WCAG AA: Follow minimum standards for focus management, color contrast, and ARIA attributes.
  Sources: best-practices.md:15-17

CSS & Layout

Styles are managed via SCSS for components and a central global.css for theme variables.

• CSS Variables: Use :root variables for colors (e.g., --main-color: rgb(223,3,3)) and fonts.
• Responsive Layout: Use the auto-container class (max-width: 1200px) for standard content centering.
• Animation: Leverage AOS (Animate on Scroll) for entrance transitions.
  Sources: sunrise-angular/src/assets/assets/css/global.css:50-80, sunrise-angular/src/assets/assets/css/global.css:300-310, implementation_plan.md:235-245

Data Models & Technical Specifications

Interface / Model	Key Fields	Purpose
Product	id, slug, brand, specs[], services_offered	Core data for hardware catalog entries.
ProductSpec	key, value	Represents technical specs (e.g., "Resolution": "4MP").
ServiceType	'Sales', 'Installation', 'AMC', 'Repair'	Union type for service offerings.
LocalBusiness	geo, aggregateRating, openingHours	Schema.org data for local presence.
Sources: implementation_plan.md:65-82, sunrise-angular/src/app/core/services/seo.service.ts:375-450

Development Best Practices Summary

1. Use strict TypeScript type checking and avoid any.
2. Implement lazy loading for all feature routes (e.g., products, services).
3. Use NgOptimizedImage but note it does not support inline base64 images.
4. Prefer Signal Forms (@angular/forms/signals) for new form implementations.
5. Maintain paths relative to the component file when using external templates or styles.
   Sources: best-practices.md:3-6, best-practices.md:11-13, best-practices.md:27, implementation_plan.md:125-135