Angular Structure

Angular Enterprise Architecture Guidelines (2026)

Feature-first, enterprise-grade Angular architecture that scales across teams and codebases. Assumes TypeScript strict, modern tooling (esbuild + Vite, Angular 21+), and emphasizes feature isolation, signals-first reactivity, performance, and operability.

1) High-Level Structure

src/
  app/
    app.component.ts              # root component (thin shell)
    app.config.ts                 # application providers
    app.routes.ts                 # top-level route definitions
    core/                         # singleton services, guards, interceptors
      auth/
        auth.service.ts
        auth.guard.ts
        auth.interceptor.ts
      error/
        global-error-handler.ts
      layout/
        header.component.ts
        sidebar.component.ts
        footer.component.ts
    shared/                       # reusable & stateless UI/utilities
      ui/                         # presentational components (buttons, cards, table)
      directives/                 # generic directives
      pipes/                      # generic pipes
      utils/                      # pure TS helpers
      styles/                     # design tokens, mixins, global CSS
    features/                     # domain-driven feature slices
      users/
        user-list/
          user-list.component.ts
        user-detail/
          user-detail.component.ts
        user-form/
          user-form.component.ts
        data-access/
          users.service.ts
          users.store.ts
          users.model.ts
        users.routes.ts
  environments/
    environment.ts
    environment.prod.ts
  assets/
  styles/
    tokens.css
    globals.css
  main.ts                         # app bootstrap

Philosophy

• Organize by feature/domain, not by technical layer.
• Keep shared stateless and UI-only; keep data-access inside the owning feature.
• Prefer co-location: tests, styles, stories next to implementation.
• Standalone components are the default — no NgModule for new code.

Nx Monorepo: For large orgs, extract features into domain libraries (packages/products/feat-product-list, packages/products/data-access) and enforce module boundaries via tags (type:feature, type:shared, scope:products).

2) Core App Wiring

• Bootstrap: app.config.ts hosts all root providers (provideRouter, provideHttpClient, provideZonelessChangeDetection, etc.).
• Routing: Standalone routes in app.routes.ts with lazy-loaded feature routes.
• Layout: App chrome (header + sidebar + footer) lives in core/layout/, not in shared or features. Use <router-outlet /> for content slots.
• Errors: Global ErrorHandler + error reporting (Sentry, etc.).
• Runtime config: Load from /config.json or environment files; expose via a typed service.

Example

// app.config.ts
export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(appRoutes, withComponentInputBinding()),
    provideHttpClient(
      withInterceptors([authInterceptor, errorInterceptor]),
      withFetch()
    ),
    provideZonelessChangeDetection(),
    provideClientHydration(withEventReplay(), withIncrementalHydration()),
  ],
};

// main.ts
bootstrapApplication(AppComponent, appConfig);

3) Shared Layer (Stateless & Reusable)

shared/
  ui/
    PageHeader/
    DataTable/
    EmptyState/
    Skeleton/
    Button/
    Modal/
  directives/
    click-outside.directive.ts
    autofocus.directive.ts
  pipes/
    date-format.pipe.ts
    truncate.pipe.ts
  utils/
    date.ts
    array.ts
  styles/
    tokens.css
    globals.css

Rules

• No data fetching or business logic here.
• Components are presentational (inputs in, outputs out).
• Keep design-system atoms/molecules here; domain widgets stay inside features.
• Prefer Angular CDK primitives for accessible, unstyled components.
• Use ChangeDetectionStrategy.OnPush on all shared components.

4) Feature Slices (DDD-style)

Each feature encapsulates UI, data-access, and local state.

features/users/
  users.routes.ts               # lazy-loaded route config for this feature
  user-list/
    user-list.component.ts      # smart: orchestrates data + renders UI
    user-list.component.html
    user-list.component.spec.ts
  user-detail/
    user-detail.component.ts
  user-form/
    user-form.component.ts      # shared between create/edit
  data-access/
    users.service.ts            # HTTP client
    users.store.ts              # NgRx SignalStore
    users.model.ts              # DTOs & ViewModels
    users.adapter.ts            # DTO <-> VM mappings
  testing/
    builders.ts                 # test factories/mocks

Rules

• Smart components (pages) orchestrate state and navigation; dumb components render.
• data-access/ keeps backend specifics (endpoints, DTOs) isolated; never leak raw DTOs to components.
• Reuse the same form component for create/edit — pass defaultValues via signal inputs and an onSubmit output.
• Cross-feature imports should go through a barrel index.ts if needed — prefer minimal cross-feature coupling.

5) Signals — Reactivity Model

Angular's signals system is the foundation of modern Angular reactivity. All signal primitives are stable as of Angular 20+.

Core Primitives

// Writable signal
const count = signal(0);
count.set(5);
count.update(v => v + 1);

// Computed (read-only, memoized, lazy)
const doubled = computed(() => count() * 2);

// LinkedSignal (writable computed — resets when source changes)
const options = signal(['express', 'standard']);
const selected = linkedSignal(() => options()[0]);
selected.set(options()[1]); // manual override allowed

// Effect (side effects — runs asynchronously)
effect(() => {
  console.log('Count changed:', count());
});

Signal-Based Component APIs

@Component({
  selector: 'app-user-card',
  standalone: true,
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <h2>{{ name() }}</h2>
    @if (isAdmin()) { <span>Admin</span> }
  `
})
export class UserCardComponent {
  // Signal inputs (replaces @Input())
  name = input.required<string>();
  role = input<string>('viewer');

  // Computed from inputs
  isAdmin = computed(() => this.role() === 'admin');

  // Model signal (two-way binding with [(value)])
  value = model<string>('');

  // Signal outputs (replaces @Output())
  saved = output<void>();

  // Signal queries (replaces @ViewChild / @ContentChild)
  myInput = viewChild<ElementRef>('myInput');
  panels = contentChildren(PanelComponent);
}

Best practices

• Prefer computed() for derived values (memoized, lazy).
• Use linkedSignal() only when you need both reactivity AND manual writes.
• Use effect() sparingly — last resort for side effects (logging, analytics, external APIs).
• Use untracked() to read signals without creating dependencies.

6) New Control Flow Syntax

The built-in control flow (stable since Angular 17) replaces *ngIf, *ngFor, *ngSwitch:

<!-- @if / @else if / @else -->
@if (user(); as user) {
  <h1>Welcome, {{ user.name }}</h1>
} @else {
  <h1>Please log in</h1>
}

<!-- @for with track (required) -->
@for (item of items(); track item.id) {
  <app-item-card [item]="item" />
} @empty {
  <p>No items found.</p>
}

<!-- @switch -->
@switch (status()) {
  @case ('loading') { <app-spinner /> }
  @case ('error') { <app-error [message]="error()" /> }
  @case ('success') { <app-content [data]="data()" /> }
}

Key advantages

• Better type narrowing in templates.
• track expression is required in @for (performance guarantee).
• @empty block for empty collections.
• Contextual variables: $index, $count, $first, $last, $even, $odd.

7) Deferrable Views (@defer)

@defer (on viewport; prefetch on idle) {
  <app-heavy-chart [data]="chartData()" />
} @placeholder (minimum 200ms) {
  <div class="skeleton-chart"></div>
} @loading (after 100ms; minimum 500ms) {
  <app-spinner />
} @error {
  <p>Failed to load chart component.</p>
}

Available triggers

Prefetching: prefetch on idle loads JavaScript before the trigger fires, so rendering is instant when triggered. Reduces initial bundle size by 30-50%.

8) Data Fetching

httpResource (Reactive — Experimental)

@Component({ ... })
export class ProductListComponent {
  private category = input<string>('all');

  // Auto re-fetches when category changes
  products = httpResource<Product[]>(() => `/api/products?category=${this.category()}`);
}

Template usage:

@if (products.hasValue()) {
  @for (product of products.value(); track product.id) {
    <app-product-card [product]="product" />
  }
} @else if (products.isLoading()) {
  <app-spinner />
} @else if (products.error()) {
  <app-error [error]="products.error()" />
}

Key points

• httpResource is for read operations only (GET).
• For mutations (POST/PUT/DELETE), use HttpClient directly.
• Built on HttpClient — supports interceptors, testing with HttpTestingController.
• Cancels in-flight requests when dependencies change.

HttpClient (Mutations & Legacy)

@Injectable({ providedIn: 'root' })
export class UsersService {
  private http = inject(HttpClient);
  private baseUrl = '/api/users';

  getAll() {
    return this.http.get<UserDto[]>(this.baseUrl);
  }

  create(input: CreateUserInput) {
    return this.http.post<UserDto>(this.baseUrl, input);
  }

  update(id: string, input: UpdateUserInput) {
    return this.http.put<UserDto>(`${this.baseUrl}/${id}`, input);
  }

  delete(id: string) {
    return this.http.delete<void>(`${this.baseUrl}/${id}`);
  }
}

Functional Interceptors

// auth.interceptor.ts
export const authInterceptor: HttpInterceptorFn = (req, next) => {
  const token = inject(AuthService).getToken();
  if (token) {
    req = req.clone({ setHeaders: { Authorization: `Bearer ${token}` } });
  }
  return next(req);
};

// error.interceptor.ts
export const errorInterceptor: HttpInterceptorFn = (req, next) => {
  return next(req).pipe(
    retry({ count: 2, delay: 1000 }),
    catchError((error: HttpErrorResponse) => {
      if (error.status === 401) inject(AuthService).logout();
      return throwError(() => error);
    })
  );
};

9) State Management Strategy

NgRx SignalStore (Recommended)

// features/users/data-access/users.store.ts
import { signalStore, withState, withComputed, withMethods, patchState } from '@ngrx/signals';
import { withEntities, setAllEntities } from '@ngrx/signals/entities';
import { rxMethod } from '@ngrx/signals/rxjs-interop';

type UsersState = {
  isLoading: boolean;
  filter: string;
};

export const UsersStore = signalStore(
  { providedIn: 'root' },
  withState<UsersState>({ isLoading: false, filter: '' }),
  withEntities<User>(),
  withComputed((store) => ({
    filteredUsers: computed(() =>
      store.entities().filter(u => u.name.includes(store.filter()))
    ),
  })),
  withMethods((store, usersService = inject(UsersService)) => ({
    updateFilter(filter: string) {
      patchState(store, { filter });
    },
    loadUsers: rxMethod<void>(
      pipe(
        tap(() => patchState(store, { isLoading: true })),
        switchMap(() => usersService.getAll()),
        tap(users => patchState(store, setAllEntities(users), { isLoading: false }))
      )
    ),
  }))
);

Key patterns

• One SignalStore per feature domain.
• Co-locate state, updaters, and effects in a single store file.
• Use patchState() for immutable state updates.
• Use rxMethod() from @ngrx/signals/rxjs-interop for async side effects.
• Use { providedIn: 'root' } for global stores; provide at route level for scoped stores.

10) Routing

Standalone Route Configuration

// app.routes.ts
export const appRoutes: Routes = [
  {
    path: '',
    component: LayoutComponent,
    children: [
      {
        path: 'users',
        loadChildren: () => import('./features/users/users.routes')
          .then(m => m.USERS_ROUTES),
        canMatch: [() => inject(AuthService).isAuthenticated()],
      },
      {
        path: 'dashboard',
        loadComponent: () => import('./features/dashboard/dashboard.component')
          .then(m => m.DashboardComponent),
        canActivate: [authGuard],
        resolve: { stats: statsResolver },
      },
    ],
  },
  {
    path: 'login',
    loadComponent: () => import('./features/auth/login.component')
      .then(m => m.LoginComponent),
  },
];

Feature Routes

// features/users/users.routes.ts
export const USERS_ROUTES: Routes = [
  { path: '', component: UserListComponent },
  { path: 'new', component: UserFormComponent },
  { path: ':id', component: UserDetailComponent },
  { path: ':id/edit', component: UserFormComponent },
];

Functional Guards & Resolvers

// core/auth/auth.guard.ts
export const authGuard: CanActivateFn = (route, state) => {
  const authService = inject(AuthService);
  const router = inject(Router);
  return authService.isAuthenticated()
    ? true
    : router.createUrlTree(['/login'], { queryParams: { returnUrl: state.url } });
};

// Functional resolver
export const userResolver: ResolveFn<User> = (route) => {
  return inject(UsersService).getById(route.paramMap.get('id')!);
};

Key patterns

• Functional guards and resolvers — class-based are deprecated.
• Use canMatch instead of canLoad (deprecated) — prevents lazy loading code user cannot access.
• loadChildren for feature route files; loadComponent for single-component routes.
• Scoped providers via providers array on route config.

11) Forms

Typed Reactive Forms (Production Standard)

interface UserForm {
  name: FormControl<string>;
  email: FormControl<string>;
  address: FormGroup<{
    street: FormControl<string>;
    city: FormControl<string>;
  }>;
}

@Component({ ... })
export class UserFormComponent {
  private fb = inject(NonNullableFormBuilder);
  private defaultValues = input<UserVM | null>(null);

  form = this.fb.group<UserForm>({
    name: this.fb.control('', [Validators.required, Validators.minLength(2)]),
    email: this.fb.control('', [Validators.required, Validators.email]),
    address: this.fb.group({
      street: this.fb.control(''),
      city: this.fb.control(''),
    }),
  });

  submitted = output<UserFormValue>();

  constructor() {
    effect(() => {
      const defaults = this.defaultValues();
      if (defaults) this.form.patchValue(defaults);
    });
  }

  onSubmit() {
    if (this.form.valid) {
      this.submitted.emit(this.form.getRawValue());
    }
  }
}

Signal Forms (experimental in Angular 21) use a single [field] directive and signal-based form models. Not production-ready yet — use typed Reactive Forms.

12) Styling

• Tailwind CSS v4 is the recommended default. New Oxide engine (10x faster builds), CSS-first configuration, zero runtime cost.
• Angular CDK for accessible, unstyled component primitives.
• Component-scoped styles with ViewEncapsulation.Emulated (default) — styles are automatically scoped.
• Use :host for component-level styling.
• styled-components / Emotion: Not applicable in Angular. Avoid CSS-in-JS runtime approaches.
• Centralize design tokens in shared/styles/tokens.css.
• Co-locate component-specific styles with their component files.

/* styles.css (global) — Tailwind v4 */
@import "tailwindcss";

@Component({
  styles: `
    :host { display: block; }
  `,
  template: `
    <div class="flex items-center gap-4 p-4 rounded-lg bg-white shadow">
      <ng-content />
    </div>
  `
})

13) Performance

Zoneless Change Detection (Default in Angular 21+)

// app.config.ts
providers: [
  provideZonelessChangeDetection(),
]

Benefits: 60% faster startup, smaller bundle (no zone.js), no more ExpressionChangedAfterItHasBeenChecked errors. Requires signals-based reactivity.

Performance Checklist

• Use @defer for below-the-fold and heavy components (30-50% bundle reduction).
• Use track in @for with stable unique IDs (never use object references).
• Use computed() for derived values (memoized, lazy).
• Use httpResource with reactive signals (auto-cancels stale requests).
• Enable incremental hydration for SSR apps.
• Use NgOptimizedImage for image optimization.
• Use ChangeDetectionStrategy.OnPush everywhere (or go zoneless).
• Split code by route with loadChildren / loadComponent.

14) Security & Compliance

• Angular auto-sanitizes interpolated values in templates (HTML, styles, URLs).
• Avoid innerHTML with untrusted data; use DomSanitizer.bypassSecurityTrustHtml() only when absolutely necessary.
• Use Renderer2 instead of direct DOM manipulation (ElementRef.nativeElement).
• Content Security Policy (CSP); avoid inline scripts/styles. Angular supports Trusted Types API.
• CSRF: HttpClient handles CSRF tokens via the double-submit cookie pattern.
• Auth tokens: use Secure, HttpOnly, SameSite cookies where possible.
• Use withFetch() in provideHttpClient() for modern fetch API.
• Functional route guards for authentication/authorization.
• Handle secrets on the server; never ship secrets to the client bundle.

15) Server-Side Rendering & Hydration

// app.config.server.ts
export const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(),
    provideServerRouteConfig([
      { path: '', renderMode: RenderMode.Server },
      { path: 'about', renderMode: RenderMode.Prerender },
    ]),
  ],
};

// app.config.ts — client hydration
providers: [
  provideClientHydration(
    withEventReplay(),
    withIncrementalHydration()
  ),
]

Incremental Hydration

@defer (hydrate on viewport) {
  <app-product-reviews />
}

@defer (hydrate on interaction) {
  <app-comment-form />
}

@defer (hydrate never) {
  <app-static-footer />
}

Hydration triggers: on viewport, on interaction, on idle, on timer, on hover, when condition, never.

16) Testing

// user-list.component.spec.ts
describe('UserListComponent', () => {
  beforeEach(() => {
    TestBed.configureTestingModule({
      imports: [UserListComponent],
      providers: [provideHttpClientTesting()],
      deferBlockBehavior: DeferBlockBehavior.Manual,
    });
  });

  it('should display users', async () => {
    const fixture = TestBed.createComponent(UserListComponent);
    const httpTesting = TestBed.inject(HttpTestingController);

    fixture.detectChanges();
    httpTesting.expectOne('/api/users').flush([{ id: '1', name: 'Alice' }]);
    fixture.detectChanges();

    expect(fixture.nativeElement.textContent).toContain('Alice');
  });
});

• Co-locate *.spec.ts with source files.
• Factories/builders under features/*/testing/ and test/.
• Jest is valid only for legacy projects where migration cost is prohibitive.

17) Build Tools

Angular CLI uses esbuild for compilation and Vite for the dev server by default since Angular 17. No vite.config.ts needed.

{
  "build": { "builder": "@angular-devkit/build-angular:application" },
  "serve": { "builder": "@angular-devkit/build-angular:dev-server" },
  "test":  { "builder": "@angular/build:unit-test" }
}

18) Tooling & Governance

• TypeScript strict mode — mandatory, no exceptions. TS 5.8+.
• Path aliases for @app, @shared, @features/*, @core.
• ESLint (@angular-eslint) + Prettier; add custom rules to forbid cross-feature imports.
• inject() function preferred over constructor injection — use Angular's migration schematic (ng generate @angular/core:inject).
• Consider Nx for monorepos: cached builds, affected tests, and module boundary linting via tags (type:feature, type:shared, scope:users).

{
  "paths": {
    "@app/*": ["src/app/*"],
    "@core/*": ["src/app/core/*"],
    "@shared/*": ["src/app/shared/*"],
    "@features/*": ["src/app/features/*"]
  }
}

19) CI/CD & Quality Gates

• Lint, typecheck, unit + integration tests on PRs.
• E2E smoke on main; preview deployments for feature branches.
• Bundle analyzer in CI; enforce budgets.
• Dependency review & security scanning.
• Nx affected commands to only test/build what changed.

20) API Boundary & Models

• Keep HTTP clients inside each feature under data-access/.
• Map DTO <-> ViewModel with adapters to decouple UI from backend changes.
• Handle auth/error/trace via functional interceptors at app.config.ts.
• Prefer generated clients from OpenAPI/GraphQL, wrapped by thin facades.

// users.adapter.ts
export const toUserVM = (dto: UserDto): UserVM => ({
  id: dto.id,
  name: `${dto.firstName} ${dto.lastName}`,
  role: dto.role ?? 'user',
});

21) Example: Users Feature

Routes

// features/users/users.routes.ts
export const USERS_ROUTES: Routes = [
  { path: '', component: UserListComponent },
  { path: 'new', component: UserFormComponent },
  { path: ':id', component: UserDetailComponent },
  { path: ':id/edit', component: UserFormComponent },
];

List Page (Smart Component)

// features/users/user-list/user-list.component.ts
@Component({
  standalone: true,
  imports: [PageHeader, UsersTable],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <main class="container">
      <app-page-header title="Users" subtitle="Manage accounts" />
      @if (store.isLoading()) {
        <app-spinner />
      } @else {
        <app-users-table
          [users]="store.filteredUsers()"
          (edit)="onEdit($event)"
        />
      }
    </main>
  `,
})
export class UserListComponent implements OnInit {
  protected store = inject(UsersStore);
  private router = inject(Router);

  ngOnInit() {
    this.store.loadUsers();
  }

  onEdit(user: User) {
    this.router.navigate(['/users', user.id, 'edit']);
  }
}

Create / Edit with Shared Form

<!-- Create -->
<main class="container">
  <app-page-header title="Add User" />
  <app-user-form (submitted)="store.createUser($event)" />
</main>

<!-- Edit -->
<main class="container">
  <app-page-header title="Edit User" />
  <app-user-form [defaultValues]="user()" (submitted)="store.updateUser(id(), $event)" />
</main>

22) Layout Pattern

core/layout/
  layout.component.ts       # header + sidebar + <router-outlet />
  header.component.ts
  sidebar.component.ts

// app.routes.ts
export const appRoutes: Routes = [
  {
    path: '',
    component: LayoutComponent,
    children: [
      { path: 'users', loadChildren: () => import('./features/users/users.routes').then(m => m.USERS_ROUTES) },
      { path: 'dashboard', loadComponent: () => import('./features/dashboard/dashboard.component').then(m => m.DashboardComponent) },
      { path: '', redirectTo: 'users', pathMatch: 'full' },
    ],
  },
  {
    path: 'login',
    loadComponent: () => import('./features/auth/login.component').then(m => m.LoginComponent),
  },
];

Summary Table

Recommended Stack (2026)