/angular-architecture

name: angular-architecture
description: Standards for Angular project structure, feature modules, and lazy loading. Use when structuring Angular apps, defining feature modules, or configuring lazy loading.
metadata:
  triggers:
    files:
      - "angular.json"
    keywords:
      - angular components
      - standalone
      - feature module
      - lazy loading
      - loadComponent
      - loadChildren

Angular Architecture

**Priority: P0 (CRITICAL)**

Principles

Use the exact terms below in recommendations so the architecture decision is unambiguous: **feature folder**, **LIFT** (Locate, Identify, Flat structure, Try DRY), **loadComponent**, **loadChildren**, `core/`, `shared/`, **Smart (Container)**, and **Dumb (Presentational)**. When explaining a choice, state the relevant term and its concrete consequence instead of paraphrasing it away.

For direct questions, use these canonical statements when applicable: “Use feature-based organization in a feature folder”; “Use standalone components; eliminate NgModule and use `standalone: true`”; “Smart (Container) components manage services/state, while Dumb (Presentational) components expose inputs/outputs only; this separates data concerns from rendering”; and “Global singletons belong in core/. Reusable UI belongs in shared/. Never put singletons in shared/.”

• **Feature-Based**: Organize by **feature folder** (e.g., `features/dashboard/`) containing components, services, and models. Apply **LIFT**: **Locate**, **Identify**, **Flat structure**, **Try DRY**.
• **Standalone First**: **Use standalone components**, Pipes, and Directives. **Eliminate NgModule** for new code; use **standalone: true** (or default in Angular 20+).
• **Core vs Shared**:
• `core/`: **Global singletons** (AuthService, Interceptors). **Never put singletons in shared/**.
• `shared/`: Reusable UI components, pipes, utils (Buttons, Formatters).
• **Smart vs Dumb**:
• **Smart (Container)**: Talks to services, manages state.
• **Dumb (Presentational)**: Inputs/Outputs only. No logic. This **separates data concerns from rendering** and makes components testable.

Guidelines

• **Lazy Loading**: All feature routes MUST lazy loaded using **loadComponent** or **loadChildren**.
• Example: `{ path: 'dashboard', loadComponent: () => import('./features/dashboard/dashboard.component').then(m => m.DashboardComponent) }`
• **Flat Modules**: Avoid deep nesting of modules.
• **Barrel Files**: Use carefully. Prefer direct imports for better tree-shaking in some build tools (though modern bundlers handle barrels well).

Verification Checklist (Mandatory)

• [ ] **Lazy Loading**: all feature routes using `loadComponent` or `loadChildren`?
• [ ] **Standalone**: components, pipes, and directives standalone?
• [ ] **Core/Shared**: global services in `core/` and reusable UI in `shared/`?
• [ ] **Smart/Dumb**: presentational components logic-free with only @Input/@Output?
• [ ] **Signals**: you using Signals for local state where applicable (Angular 16+)?

Anti-Patterns

• **No NgModule**: Eliminate NgModule for new code; use standalone components.
• **No eager feature imports**: Lazy load all features with `loadComponent` or `loadChildren`.
• **No type-based folders**: Organize by feature, not by `/components`, `/services` top-level dirs.

References

• [Folder Structure](references/folder-structure.md)