# Core Architecture Standards for Angular

This document outlines the core architectural standards for Angular applications. It provides guidelines for project structure, fundamental patterns, and organization principles to ensure maintainability, scalability, and performance.

## 1. Project Structure and Organization

### 1.1. Feature-Based Modules

**Standard:** Organize the application into feature-based modules. Each module encapsulates a specific feature or business capability.

**Do This:** Create a directory for each feature module under the "src/app" directory.

**Don't Do This:** Avoiding creating a monolithic "app.module.ts" containing all components, services, and dependencies.

**Why:** Feature-based modules promote modularity, improve separation of concerns, and enable lazy loading, resulting in faster initial load times and improved maintainability.

**Example:**

"""

src/

app/

auth/ // Authentication feature module

auth.module.ts

auth-routing.module.ts

components/

services/

auth.service.ts

dashboard/ // Dashboard feature module

dashboard.module.ts

dashboard-routing.module.ts

components/

overview/

overview.component.ts

overview.component.html

shared/ // Shared module for reusable components, services, and pipes

shared.module.ts

components/

data-table/

data-table.component.ts

data-table.component.html

services/

data.service.ts

app.component.ts

app.module.ts

app-routing.module.ts

"""

### 1.2. Core Module

**Standard:** Create a "core" module for application-wide services and singleton components.

**Do This:** Place services that need to be instantiated only once (e.g., authentication service, configuration service) and singleton components (e.g., "AppComponent") in the "core" module. Import the "core" module only into the "AppModule".

**Don't Do This:** Import "core" module into other feature modules. This can lead to multiple instances of singleton services.

**Why:** The "core" module ensures that certain services and components are instantiated only once and provides a clear separation of concerns.

**Example:**

"""

src/

app/

core/

core.module.ts

services/

auth.service.ts

config.service.ts

app.module.ts

"""

"""typescript

// core.module.ts

import { NgModule, Optional, SkipSelf } from '@angular/core';

import { AuthService } from './services/auth.service';

import { CommonModule } from '@angular/common';

import { ConfigService } from './services/config.service';

@NgModule({

imports: [CommonModule],

providers: [AuthService, ConfigService],

})

export class CoreModule {

constructor(@Optional() @SkipSelf() parentModule: CoreModule) {

if (parentModule) {

throw new Error('CoreModule is already loaded. Import it in the AppModule only.');

}

"""

"""typescript

// app.module.ts

import { NgModule } from '@angular/core';

import { BrowserModule } from '@angular/platform-browser';

import { CoreModule } from './core/core.module';

import { AppComponent } from './app.component';

@NgModule({

declarations: [AppComponent],

imports: [BrowserModule, CoreModule],

bootstrap: [AppComponent],

})

export class AppModule {}

"""

### 1.3. Shared Module

**Standard**: Create a "shared" module for reusable components, directives, and pipes.

**Do This**: Place components, directives, pipes, and modules that reused across multiple feature modules in "shared" module. Export all symbols that should be accessible from other modules.

**Don't Do This**: Import feature-specific services into "shared" module. Place components that are only used by one feature module in "shared" module.

**Why:** The "shared" module promotes code reuse and consistency across the application.

**Example:**

"""

src/

app/

shared/

shared.module.ts

components/

data-table/

data-table.component.ts

data-table.component.html

directives/

highlight.directive.ts

pipes/

truncate.pipe.ts

"""

"""typescript

// shared.module.ts

import { NgModule } from '@angular/core';

import { CommonModule } from '@angular/common';

import { DataTableComponent } from './components/data-table/data-table.component';

import { HighlightDirective } from './directives/highlight.directive';

import { TruncatePipe } from './pipes/truncate.pipe';

@NgModule({

declarations: [DataTableComponent, HighlightDirective, TruncatePipe],

imports: [CommonModule],

exports: [DataTableComponent, HighlightDirective, TruncatePipe, CommonModule], // Export CommonModule for *ngIf, *ngFor etc.

})

export class SharedModule {}

"""

### 1.4. Lazy Loading Modules

**Standard:** Use lazy loading for feature modules to improve initial load time.

**Do This:** Configure routes for feature modules to be loaded lazily using "loadChildren".

**Don't Do This:** Load all modules eagerly, which can significantly increase the initial load time of the application.

**Why:** Lazy loading reduces the initial bundle size by loading modules on demand, improving the user experience.

**Example:**

"""typescript

// app-routing.module.ts

import { NgModule } from '@angular/core';

import { RouterModule, Routes } from '@angular/router';

const routes: Routes = [

{

path: 'auth',

loadChildren: () => import('./auth/auth.module').then((m) => m.AuthModule),

{

path: 'dashboard',

loadChildren: () => import('./dashboard/dashboard.module').then((m) => m.DashboardModule),

{

path: '',

redirectTo: 'dashboard',

pathMatch: 'full',

];

@NgModule({

imports: [RouterModule.forRoot(routes)],

exports: [RouterModule],

})

export class AppRoutingModule {}

"""

### 1.5. Folder Structure Conventions

**Standard:** Follow consistent folder structure conventions within each module.

**Do This:** Create subfolders for components, services, models, and pipes within each module.

**Don't Do This:** Mix file types in a single folder, which reduces readability and maintainability.

**Example:**

"""

src/

app/

auth/

components/

services/

auth.service.ts

models/

user.model.ts

auth.module.ts

auth-routing.module.ts

"""

### 1.6. Naming Conventions

**Standard:** Use consistent naming conventions for files and classes.

**Do This:**

* Components: "ComponentNameComponent" (e.g., "LoginComponent")

* Services: "ServiceNameService" (e.g., "AuthService")

* Modules: "ModuleNameModule" (e.g., "AuthModule")

* Models: "ModelNameModel" (e.g., "UserModel")

* Files: "component-name.component.ts", "service-name.service.ts", "module-name.module.ts", "model-name.model.ts"

**Don't Do This:** Use inconsistent or ambiguous names, which makes it harder to understand the purpose of the file or class.

**Why:** Consistent naming conventions improve code readability and make it easier to locate files and classes. For example, VS Code and other IDEs provide suggestions based on these patterns.

## 2. Architectural Patterns

### 2.1. Smart vs. Dumb Components

**Standard:** Distinguish between smart (container) and dumb (presentational) components.

**Do This:** Smart components should handle data fetching, state management, and business logic. Dumb components should focus on rendering data and emitting events. Use "@Input()" and "@Output()" to pass data between them.

**Don't Do This:** Performing data fetching or complex business logic inside dumb components. This tightly couples the component to specific data sources, making it less reusable.

**Why:** This pattern promotes reusability, testability, and separation of concerns. Smart components act as orchestrators while dumb components are reusable views.

**Example:**

"""typescript

// Smart component (e.g., UserListComponent)

import { Component, OnInit } from '@angular/core';

import { UserService } from '../user.service';

import { User } from '../user.model';

@Component({

selector: 'app-user-list',

templateUrl: './user-list.component.html',

styleUrls: ['./user-list.component.scss'],

})

export class UserListComponent implements OnInit {

users: User[] = [];

constructor(private userService: UserService) {}

ngOnInit(): void {

this.userService.getUsers().subscribe((users) => {

this.users = users;

});

}

onDelete(userId: number): void {

this.userService.deleteUser(userId).subscribe(() => {

this.users = this.users.filter((user) => user.id !== userId);

});

}

"""

"""html

Delete

"""

"""typescript

// Dumb component (e.g., UserItemComponent)

import { Component, Input, Output, EventEmitter } from '@angular/core';

import { User } from '../user.model';

@Component({

selector: 'app-user-item',

templateUrl: './user-item.component.html',

styleUrls: ['./user-item.component.scss'],

})

export class UserItemComponent {

@Input() user!: User;

@Output() delete = new EventEmitter();

}

"""

### 2.2. Services for Business Logic

**Standard:** Encapsulate business logic in services.

**Do This:** Create services to handle data fetching, data manipulation, and complex calculations. Inject these services into components that need to access the business logic.

**Don't Do This:** Placing business logic directly in components. This makes components harder to test and reduces reusability.

**Why:** Services promote code reusability, testability, and separation of concerns. They also make it easier to manage and maintain the application's business logic.

**Example:**

"""typescript

// user.service.ts

import { Injectable } from '@angular/core';

import { HttpClient } from '@angular/common/http';

import { Observable } from 'rxjs';

import { User } from './user.model';

@Injectable({

providedIn: 'root',

})

export class UserService {

private apiUrl = '/api/users';

constructor(private http: HttpClient) {}

getUsers(): Observable {

return this.http.get(this.apiUrl);

}

deleteUser(userId: number): Observable {

return this.http.delete("${this.apiUrl}/${userId}");

}

"""

### 2.3. State Management

**Standard:** Choose an appropriate state management solution based on application complexity.

**Do This:** For simple applications, use "@Input()" and "@Output()" (as detailed above). For complex applications, consider using NgRx, Akita, or a similar state management library. Alternatively, consider a service-based state management approach for less complex applications.

**Don't Do This:** Directly modifying the state in multiple components, leading to unpredictable behavior and difficulties in debugging.

**Why:** A state management solution provides a predictable way to manage application state, making it easier to reason about and debug the application.

**Example (Service-based state management):**

"""typescript

//Simple example for smaller projects.

// counter.service.ts

import { Injectable } from '@angular/core';

import { BehaviorSubject } from 'rxjs';

@Injectable({

providedIn: 'root'

})

export class CounterService {

private counter = new BehaviorSubject(0);

public counter$ = this.counter.asObservable();

increment() {

this.counter.next(this.counter.value + 1);

}

decrement() {

this.counter.next(this.counter.value - 1);

}

"""

### 2.4. Interceptors

**Standard:** Use interceptors to handle cross-cutting concerns such as authentication, logging, and error handling.

**Do This:** Create interceptors to add headers, log requests, and handle errors globally. Register the interceptors in the "AppModule".

**Don't Do This:** Implementing these concerns directly in each service method, leading to code duplication and maintenance issues.

**Why:** Interceptors provide a centralized way to handle cross-cutting concerns, reducing code duplication and improving maintainability.

**Example:**

"""typescript

// auth.interceptor.ts

import { Injectable } from '@angular/core';

import { HttpInterceptor, HttpRequest, HttpHandler, HttpEvent } from '@angular/common/http';

import { Observable } from 'rxjs';

import { AuthService } from './auth.service';

@Injectable()

export class AuthInterceptor implements HttpInterceptor {

constructor(private authService: AuthService) {}

intercept(request: HttpRequest, next: HttpHandler): Observable> {

const token = this.authService.getToken();

if (token) {

const authRequest = request.clone({

setHeaders: {

Authorization: "Bearer ${token}",

});

return next.handle(authRequest);

}

return next.handle(request);

}

"""

"""typescript

// app.module.ts

import { NgModule } from '@angular/core';

import { BrowserModule } from '@angular/platform-browser';

import { HttpClientModule, HTTP_INTERCEPTORS } from '@angular/common/http';

import { AuthInterceptor } from './auth.interceptor';

import { AppComponent } from './app.component';

@NgModule({

declarations: [AppComponent],

imports: [BrowserModule, HttpClientModule],

providers: [

{

provide: HTTP_INTERCEPTORS,

useClass: AuthInterceptor,

multi: true,

bootstrap: [AppComponent],

})

export class AppModule {}

"""

### 2.5. Reactive Programming with RxJS

**Standard:** Embrace reactive programming using RxJS for handling asynchronous operations.

**Do This:** Use RxJS operators to transform, filter, and combine streams of data. Leverage the "async" pipe in templates for automatic subscription management.

**Don't Do This:** Subscribing to observables directly in components without properly unsubscribing, leading to memory leaks.

**Why:** RxJS provides a powerful way to handle asynchronous operations and data streams, improving the responsiveness and maintainability of the application.

**Example:**

"""typescript

// user.service.ts

import { Injectable } from '@angular/core';

import { HttpClient } from '@angular/common/http';

import { Observable } from 'rxjs';

import { map } from 'rxjs/operators';

import { User } from './user.model';

@Injectable({

providedIn: 'root',

})

export class UserService {

private apiUrl = '/api/users';

constructor(private http: HttpClient) {}

getUsers(): Observable {

return this.http.get(this.apiUrl).pipe(

map((users) => {

return users.map((user) => ({

...user,

name: user.name.toUpperCase(),

}));

})

);

}

"""

"""html

"""

"""typescript

// user-list.component.ts

import { Component, OnInit } from '@angular/core';

import { UserService } from '../user.service';

import { Observable } from 'rxjs';

import { User } from '../user.model';

@Component({

selector: 'app-user-list',

templateUrl: './user-list.component.html',

styleUrls: ['./user-list.component.scss'],

})

export class UserListComponent implements OnInit {

users$!: Observable;

constructor(private userService: UserService) {}

ngOnInit(): void {

this.users$ = this.userService.getUsers();

}

"""

### 2.6. Dependency Injection

**Standard:** Use Angular's dependency injection (DI) system to manage dependencies.

**Do This:** Inject services and other dependencies into components, directives, and other services using the constructor.

**Don't Do This:** Creating instances of service classes directly using the "new" keyword, avoiding the benefits of DI like testability and configuration.

**Why:** DI promotes loose coupling, testability, and reusability. It also simplifies the management of dependencies.

**Example:**

"""typescript

// login.component.ts

import { Component } from '@angular/core';

import { AuthService } from '../auth.service';

@Component({

selector: 'app-login',

templateUrl: './login.component.html',

styleUrls: ['./login.component.scss'],

})

export class LoginComponent {

constructor(private authService: AuthService) {}

this.authService.login('username', 'password');

}

"""

## 3. Error Handling

### 3.1. Centralized Error Handling

**Standard:** Implement centralized error handling using interceptors or a global error handler.

**Do This:** Create an error handler service that logs errors and displays user-friendly messages. Use interceptors to catch HTTP errors and forward them to the error handler. Consider using "ErrorHandler" for uncaught exceptions.

**Don't Do This:** Handling errors directly in each component or service method, leads to error-handling logic scattered throughout the application, making it difficult to maintain.

**Why:** Centralized error handling improves the user experience and simplifies error logging and debugging.

**Example:**

"""typescript

// error.interceptor.ts

import { Injectable } from '@angular/core';

import { HttpInterceptor, HttpRequest, HttpHandler, HttpEvent, HttpErrorResponse } from '@angular/common/http';

import { Observable, throwError } from 'rxjs';

import { catchError } from 'rxjs/operators';

import { ErrorHandlerService } from './error-handler.service';

@Injectable()

export class ErrorInterceptor implements HttpInterceptor {

constructor(private errorHandlerService: ErrorHandlerService) {}

intercept(request: HttpRequest, next: HttpHandler): Observable> {

return next.handle(request).pipe(

catchError((error: HttpErrorResponse) => {

this.errorHandlerService.handleError(error);

return throwError(error);

})

);

}

"""

"""typescript

// error-handler.service.ts

import { Injectable } from '@angular/core';

@Injectable({

providedIn: 'root',

})

export class ErrorHandlerService {

handleError(error: any): void {

console.error('An error occurred:', error);

// Display a user-friendly message

alert('An error occurred. Please try again later.');

}

"""

## 4. Code Reusability

### 4.1. Custom Components

**Standard:** Create custom components for reusable UI elements.

**Do This:** Create components for common UI patterns like data tables, forms, and dialogs. Make these components configurable using "@Input()" and "@Output()".

**Don't Do This:** Duplicating UI code across multiple components, making it harder to maintain consistency and introduce changes.

**Why:** Custom components promote code reuse and improve the consistency of the user interface.

**Example:** (See "shared.module.ts" example above.)

## 5. Security

### 5.1. Input Validation

**Standard:** Validate user inputs on both the client and server sides.

**Do This:** Use Angular's reactive forms to validate user inputs. Also, implement server-side validation to prevent malicious data from being stored in the database.

**Don't Do This:** Relying solely on client-side validation, as it can be bypassed by malicious users.

**Why:** Input validation protects the application from security vulnerabilities such as cross-site scripting (XSS) and SQL injection.

### 5.2. Authentication and Authorization

**Standard:** Implement secure authentication and authorization mechanisms.

**Do This:** Use JSON Web Tokens (JWT) for authentication. Implement role-based access control (RBAC) to authorize users based on their roles.

**Don't Do This:** Storing sensitive information in local storage or cookies without proper encryption, because this exposes the application to security risks.

**Why:** Secure authentication and authorization protect the application from unauthorized access and data breaches.

## 6. Performance Optimization

### 6.1. Change Detection

**Standard:** Optimize change detection using "OnPush" strategy.

**Do This:** Use "ChangeDetectionStrategy.OnPush" for components that only depend on their inputs. This reduces the number of change detection cycles and improves performance.

**Don't Do This:** Relying solely on the default change detection strategy ("Default"), especially for complex components with many bindings, leading to performance issues.

**Why:** "OnPush" change detection improves performance by only checking for changes when the input references change.

"""typescript

import { Component, Input, ChangeDetectionStrategy } from '@angular/core';

@Component({

selector: 'app-user-profile',

templateUrl: './user-profile.component.html',

styleUrls: ['./user-profile.component.scss'],

changeDetection: ChangeDetectionStrategy.OnPush,

})

export class UserProfileComponent {

@Input() user!: User;

}

"""

### 6.2. TrackBy Function

**Standard:** Use "trackBy" function with "*ngFor" to improve performance when rendering lists.

**Do This:** Provide a "trackBy" function that returns a unique identifier for each item in the list. This prevents Angular from re-rendering the entire list when only a few items have changed.

**Don't Do This:** Omitting "trackBy" for large lists, potentially causing performance issues due to unnecessary DOM updates.

**Why:** "trackBy" improves performance by only re-rendering items that have actually changed.

"""html

"""

"""typescript

trackByFn(index: number, item: any): any {

return item.id;

}

"""

### 6.3. Ahead-of-Time (AOT) Compilation

**Standard:** Use AOT compilation to improve application startup time.

**Do This:** Enable AOT compilation in the "angular.json" file.

**Don't Do This:** Relying solely on Just-in-Time (JIT) compilation (mostly for development), resulting in slower startup times for production deployments.

**Why:** AOT compilation compiles the application during the build process, resulting in smaller bundle sizes and faster startup times.

### 6.4 Imagemin and lazy loading

**Standard**: Configure your image assets using "imagemin" when using the CLI to ensure all images are properly compressed.

**Standard**: Be sure to lazy load all images.

**Why**: Properly configured media assets ensure delivery of applications with the smallest footprint and allow users to stream in images as the images come into proper view.

Cline

This guide explains how to effectively use .clinerules with Cline, the AI-powered coding assistant.

Overview

The .clinerules file is a powerful configuration file that helps Cline understand your project's requirements, coding standards, and constraints. When placed in your project's root directory, it automatically guides Cline's behavior and ensures consistency across your codebase.

Key Concepts

Purpose of .clinerules

Defines project-specific guidelines and requirements
Enforces consistent coding standards
Establishes documentation practices
Sets testing and quality requirements
Configures error handling preferences

File Location

Place the .clinerules file in your project's root directory. Cline automatically detects and follows these rules for all files within the project.

Rule Structure

1. Project Overview

# Project Overview
project:
  name: 'Your Project Name'
  description: 'Brief project description'
  stack:
    - technology: 'Framework/Language'
      version: 'X.Y.Z'
    - technology: 'Database'
      version: 'X.Y.Z'

2. Code Standards

# Code Standards
standards:
  style:
    - 'Use consistent indentation (2 spaces)'
    - 'Follow language-specific naming conventions'
  documentation:
    - 'Include JSDoc comments for all functions'
    - 'Maintain up-to-date README files'
  testing:
    - 'Write unit tests for all new features'
    - 'Maintain minimum 80% code coverage'

3. Security Rules

# Security Guidelines
security:
  authentication:
    - 'Implement proper token validation'
    - 'Use environment variables for secrets'
  dataProtection:
    - 'Sanitize all user inputs'
    - 'Implement proper error handling'

Best Practices

Writing Effective Rules

Be Specific
- Use clear, actionable language
- Provide examples where helpful
- Define measurable criteria
Maintain Organization
- Group related rules together
- Use consistent formatting
- Keep critical rules at the top
Regular Updates
- Review rules periodically
- Update based on team feedback
- Document changes in version control

Common Patterns

# Common Patterns Example
patterns:
  components:
    - pattern: 'Use functional components by default'
    - pattern: 'Implement error boundaries for component trees'
  stateManagement:
    - pattern: 'Use React Query for server state'
    - pattern: 'Implement proper loading states'

Integration with Development Workflow

Using with Version Control

Commit the Rules
- Include .clinerules in version control
- Document rule changes in commit messages
- Review rule changes as part of PR process
Team Collaboration
- Discuss rule changes with team
- Maintain changelog for rule updates
- Ensure all team members understand rules

Troubleshooting

Common Issues

Rules Not Being Applied
- Verify file location (must be in root directory)
- Check file formatting
- Ensure Cline has access to the file
Conflicting Rules
- Review rule hierarchy
- Resolve conflicts explicitly
- Document rule precedence
Performance Considerations
- Keep rules concise and focused
- Avoid overly complex rule structures
- Regular cleanup of obsolete rules

Examples

Basic Project Setup

# Basic .clinerules Example
project:
  name: 'Web Application'
  type: 'Next.js Frontend'
  standards:
    - 'Use TypeScript for all new code'
    - 'Follow React best practices'
    - 'Implement proper error handling'

testing:
  unit:
    - 'Jest for unit tests'
    - 'React Testing Library for components'
  e2e:
    - 'Cypress for end-to-end testing'

documentation:
  required:
    - 'README.md in each major directory'
    - 'JSDoc comments for public APIs'
    - 'Changelog updates for all changes'

Advanced Configuration

# Advanced .clinerules Example
project:
  name: 'Enterprise Application'
  compliance:
    - 'GDPR requirements'
    - 'WCAG 2.1 AA accessibility'

architecture:
  patterns:
    - 'Clean Architecture principles'
    - 'Domain-Driven Design concepts'

security:
  requirements:
    - 'OAuth 2.0 authentication'
    - 'Rate limiting on all APIs'
    - 'Input validation with Zod'

Core Architecture Standards for Angular

Cline

Overview

Key Concepts

Purpose of .clinerules

File Location

Rule Structure

1. Project Overview

2. Code Standards

3. Security Rules

Best Practices

Writing Effective Rules

Common Patterns

Integration with Development Workflow

Using with Version Control

Troubleshooting

Common Issues

Examples

Basic Project Setup

Advanced Configuration

Related Rules

Angular v19+ Development Standards and Best Practices: A Comprehensive Guide

NgRx Signal Store Best Practices

NgRx Signals Testing Guidelines

Angular Material Theming Guidelines (v3)

Angular Testing Guidelines (Jasmine + ng-mocks)