When agents use itUse this whenever the user is starting or restructuring an Angular app, asks where code should live, how to organise features or Nx libraries, chooses between NgRx Store, SignalStore and plain signal services, decides on Angular Material vs a custom design system, edits app.config.ts, app.routes.ts, nx.json or project tags, or asks "how should I structure this" for anything Angular. Also use it when a component question hides a platform decision such as state scope or auth; for upgrades use angular-migration and for SSR use angular-ssr.
Install
Copilot (VS Code, Visual Studio, Copilot CLI and github.com) reads skills from the repository — commit them so the whole team gets them.
npx skills add AGCO-Global/org-skills --skill angular-architecture -a github-copilot
# or with the org installer (adds .github/skills/angular-architecture):
npx -y github:AGCO-Global/org-skills add skill angular-architecture
Uses the open skills CLI. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Windsurf and 60+ others — it asks which agent to install into.
Installs the frontend-angular-skills plugin, which bundles all Frontend / Angular skills and keeps them updated.
/plugin marketplace add AGCO-Global/org-skills
/plugin install frontend-angular-skills@org-skills
# or just this skill, in this repository:
npx skills add AGCO-Global/org-skills --skill angular-architecture -a claude-code
Use Download .zip above, then upload it under Customize → Skills → Upload skill. Team and Enterprise admins can sync this repo as a plugin marketplace instead.
Installs into .agents/skills/, which Codex reads.
npx skills add AGCO-Global/org-skills --skill angular-architecture -a codex
Installs into Cursor's skills folder.
npx skills add AGCO-Global/org-skills --skill angular-architecture -a cursor
Installs into Gemini CLI's skills folder.
npx skills add AGCO-Global/org-skills --skill angular-architecture -a gemini-cli
Nothing to install. Press Download .zip above, unzip it, and drop the angular-architecture folder into your tool's skills folder — .claude/skills/, .github/skills/, .cursor/skills/ or .agents/skills/. Step-by-step, per tool: How to use it. For any other tool with rules or custom prompts, Copy SKILL.md and paste it in — it is plain Markdown.
The npx commands need Node.js 20+ and use your normal git sign-in to GitHub, so they work while the repository is private. Without Node.js, see the No Node.js tab — a skill is a folder of Markdown, so copying it in works just as well.
Architecture here means a small number of written decisions that keep many teams shipping without stepping on each other: where code lives, who may import whom, where state lives and how long, and which platform services (auth, config, errors) exist exactly once. If the codebase is NgModules, zone.js and BehaviorSubject services, the architecture conversation is a migration conversation — say so and hand the sequencing to angular-migration.
1. Decide first
Question
Default
Change when
Workspace
Angular CLI, @angular/build:application builder
More than one app, or shared libraries with owners → Nx with tagged libraries
File naming
Style-guide names: class UserProfile in user-profile.ts, no type suffix (style guide)
Existing repo on .component.ts/.service.ts → keep it and pin the schematics type option; never mix within one project (section 2)
Components
Standalone, OnPush, signal inputs/outputs
Never for new code. OnPush and zoneless are framework defaults on v22/v21 — see version-notes.md in ../angular-development/references/
State
Signals in a feature service; NgRx SignalStore when a feature has entities, async methods and several consumers
App-wide, audited, event-sourced domain → NgRx Store, justified in an ADR. Small app → signals only
Server data
httpResource()/resource() owned by the page or store (stable v22)
v20/21 → HttpClient + toSignal(); heavy caching/invalidation needs → @tanstack/angular-query-experimental (package is still named experimental — check its status before adopting)
Forms
Signal Forms for new forms on v22
Existing Reactive Forms or v20/21 → typed Reactive Forms
UI library
Angular Material + CDK (ready-styled, M3 tokens)
Bespoke design system → Angular Aria (@angular/aria, headless accessible patterns) plus CDK overlays; data-grid-heavy back office → PrimeNG
Auth
OIDC Authorization Code + PKCE through a maintained library (MSAL Angular for Entra ID, angular-auth-oidc-client otherwise); one functional interceptor, one functional guard
Same-site backend-for-frontend with HttpOnly cookies when tokens must not reach the browser
Runtime config
provideAppInitializer() loads /config.json into an InjectionToken; one build for every environment
Values needed at build time only (feature stripping) → fileReplacements. Never secrets — everything in the bundle is public
Rendering
CSR for authenticated internal apps
Public, SEO or LCP-sensitive routes → angular-ssr
Tests
Vitest via @angular/build:unit-test, Playwright E2E
Karma still supported but no longer default — plan the move with angular-migration
2. Structure and boundaries
src/app/
app.config.ts app.routes.ts # providers; top-level lazy routes only
core/ auth/ http/ config/ errors/ layout/ # singletons, provided once
features/orders/
orders.routes.ts index.ts # lazy route file; public API of the feature
pages/ components/ data/ model/ # routed (smart) / presentational / api + store / types + pure functions
shared/ui/ shared/util/ # reusable dumb components, directives, pipes; pure helpers
Dependency direction is one-way:features → shared, core; core → shared; shared → nothing. A feature imports another feature only through its index.ts. Enforce it with lint (@nx/enforce-module-boundaries or eslint-plugin-boundaries) — an unenforced rule is gone in six months.
Pages inject, components receive. Only pages/ inject stores and API services; everything in components/ takes input() and emits output(), which keeps it reusable and cheap to test.
Naming is a repo-wide decision. New repos follow the style guide (no suffix; orders-api.ts, order-list.ts, auth-guard.ts). Legacy repos keep suffixes by setting "type": "component" / "service" under schematics in angular.json so generated files match. The always-on Angular instructions file matches files by folder, not suffix, so both work.
In Nx the same layers become library types — feature, ui, data-access, util — with scope:* and type:* tags. Tree, tag matrix and lint config: references/structure-and-boundaries.md.
3. State — choose by scope and lifetime
Scope
Pattern
Lifetime
One component
signal() / computed() / linkedSignal()
Component
A feature, few consumers
Service with private writable signals and public asReadonly()/computed()
Route (providers: [OrdersState] on the route)
A feature with entities, async methods, many consumers
Router query params read through withComponentInputBinding()
URL
Session, preferences
Root-provided service or store
App
One store per feature, provided at the feature route so it dies on leave; root-provided stores only for session-wide data. A store never imports another feature's store — compose in the page. SignalStore sample, withHooks/withProps/signalMethod and the RxJS boundary rules are in references/state-and-di.md.
4. RxJS boundary and DI design
RxJS owns events over time (typeahead, WebSocket, router events); signals own state now. Convert once with toSignal() at the edge of the service or store; templates read signals only.
Providers are functional and live in app.config.ts: provideRouter, provideHttpClient(withInterceptors([...])), provideAppInitializer, provideBrowserGlobalErrorListeners. Feature-scoped services go in the route's providers.
Abstraction points are InjectionTokens with a root factory (API_BASE_URL, LOGGER, STORAGE) — swap them in tests and SSR without touching consumers.
@Service() (v22) for plain root singletons; @Injectable() when the class needs useClass/useFactory, a non-root scope or constructor DI. Both are correct — do not "fix" one into the other.
Guards, resolvers and interceptors are functions (CanActivateFn, ResolveFn, HttpInterceptorFn); a guard returns true or a UrlTree, never navigates imperatively.
5. Routing
Every feature is loadChildren: () => import('./features/orders/orders.routes'); leaf pages use loadComponent. The initial bundle holds the shell, auth and the landing route.
withComponentInputBinding() so params and query params arrive as input(); route title on every route; data typed through a shared interface.
Resolvers only for data that must exist before first paint; otherwise render a skeleton and load in the page. Preloading: withPreloading(PreloadAllModules) for small apps, a custom strategy for large ones.
6. Platform services — exactly one of each
Auth (token acquisition, interceptor, guard), runtime config, global ErrorHandler reporting to monitoring, i18n strategy (@angular/localize build-time locales vs a runtime library such as Transloco when language switches without reload) and, only when teams deploy independently, micro-frontends (Native Federation). Defaults, trade-offs and wiring for each: references/platform-decisions.md.
7. Deliverable format
## Context — app type, teams, Angular version, constraints
## Decisions — table: decision | choice | why | revisit when (only rows that differ from section 1 need a why)
## Structure — folder or Nx library tree with the dependency rule and how lint enforces it
## State map — per feature: what state, which pattern, provided where
## ADRs — one per non-default decision, using references/adr-template.md
## Next steps — ordered, each shippable on its own; hand upgrades to angular-migration, SSR to angular-ssr
Checklist
Angular version and support status stated; v19 or below → upgrade plan comes first
One naming convention chosen, written down, and matched by the schematics config
Dependency direction defined and enforced by a lint rule that fails CI
Every feature lazy-loaded with a public index.ts; no deep imports across features
Each piece of state has one owner, one scope and a lifetime; no root store "just in case"
Auth, config, error handler and i18n each exist once in core/ and are provided in app.config.ts
No secret or per-environment URL baked into the bundle; config loads at runtime
Non-default choices (NgRx Store, micro-frontends, PrimeNG, SSR) have an ADR with a "revisit when"
strict, strictTemplates, @angular-eslint with template accessibility rules, and bundle budgets run in CI
Anti-patterns
SharedModule/barrel that exports everything → standalone imports per component; shared/ui exports single components.
Root-provided store per feature → provide at the feature route; state is released on leave and tests start clean.
NgRx Store for a CRUD app "for consistency" → signals or SignalStore; keep Store for event-sourced domains with an ADR.
BehaviorSubject + .value as the state container → private signal(), public asReadonly(); RxJS only for the event pipeline.
Feature importing another feature's internals → export through index.ts or move the shared piece to shared/; lint blocks the deep path.
Secrets or API keys in environment.ts → backend proxy; the bundle is public. Runtime config.json holds only public values.
Micro-frontends to fix a folder-structure problem → module boundaries in one build first; split deployables only for independent release cadence.
Mixed .component.ts and suffix-less files → pick one, configure schematics, rename in one mechanical PR.
Go deeper
references/structure-and-boundaries.md — full folder tree, Nx library types and tag matrix, boundary lint configs, naming config for angular.json
references/state-and-di.md — signal service and SignalStore samples, store extras, RxJS operator choice, DI token patterns
references/platform-decisions.md — auth, runtime config, error monitoring, i18n, UI library and micro-frontend decisions with wiring samples
references/adr-template.md — ADR skeleton and a filled example
version-notes.md in ../angular-development/references/ — what is default in v20, v21 and v22
Siblings: angular-development (writing the code), angular-migration (legacy → modern), angular-ssr, angular-performance, angular-testing; frontend-code-review for pull requests
---
name: angular-architecture
description: Designs the structure of Angular applications — feature-first folders with public APIs and lint-enforced boundaries, file-naming convention, state scope (signals, NgRx SignalStore, NgRx Store), RxJS boundaries, dependency-injection and route design, UI library choice (Material, CDK, Angular Aria, PrimeNG), authentication, runtime configuration, i18n, error monitoring, Nx monorepos and micro-frontends, recorded as ADRs. Use this whenever the user is starting or restructuring an Angular app, asks where code should live, how to organise features or Nx libraries, chooses between NgRx Store, SignalStore and plain signal services, decides on Angular Material vs a custom design system, edits app.config.ts, app.routes.ts, nx.json or project tags, or asks "how should I structure this" for anything Angular. Also use it when a component question hides a platform decision such as state scope or auth; for upgrades use angular-migration and for SSR use angular-ssr.
metadata:
technology: Angular
type: architecture
---
# Angular Architecture
> **Targets:** Angular 22 (LTS 20 and 21 noted where different; v19 and below unsupported) · **Verified:** 2026-09 against https://angular.dev/style-guide, https://angular.dev/reference/releases, https://angular.dev/guide/di/creating-and-using-services
Architecture here means a small number of written decisions that keep many teams shipping without stepping on each other: where code lives, who may import whom, where state lives and how long, and which platform services (auth, config, errors) exist exactly once. If the codebase is NgModules, zone.js and `BehaviorSubject` services, the architecture conversation is a migration conversation — say so and hand the sequencing to `angular-migration`.
## 1. Decide first
| Question | Default | Change when |
|---|---|---|
| Workspace | Angular CLI, `@angular/build:application` builder | More than one app, or shared libraries with owners → Nx with tagged libraries |
| File naming | Style-guide names: class `UserProfile` in `user-profile.ts`, no type suffix ([style guide](https://angular.dev/style-guide)) | Existing repo on `.component.ts`/`.service.ts` → keep it and pin the schematics `type` option; never mix within one project (section 2) |
| Components | Standalone, OnPush, signal inputs/outputs | Never for new code. OnPush and zoneless are framework defaults on v22/v21 — see `version-notes.md` in `../angular-development/references/` |
| State | Signals in a feature service; NgRx SignalStore when a feature has entities, async methods and several consumers | App-wide, audited, event-sourced domain → NgRx Store, justified in an ADR. Small app → signals only |
| Server data | `httpResource()`/`resource()` owned by the page or store (stable v22) | v20/21 → `HttpClient` + `toSignal()`; heavy caching/invalidation needs → `@tanstack/angular-query-experimental` (package is still named experimental — check its status before adopting) |
| Forms | Signal Forms for new forms on v22 | Existing Reactive Forms or v20/21 → typed Reactive Forms |
| UI library | Angular Material + CDK (ready-styled, M3 tokens) | Bespoke design system → Angular Aria (`@angular/aria`, headless accessible patterns) plus CDK overlays; data-grid-heavy back office → PrimeNG |
| Auth | OIDC Authorization Code + PKCE through a maintained library (MSAL Angular for Entra ID, `angular-auth-oidc-client` otherwise); one functional interceptor, one functional guard | Same-site backend-for-frontend with `HttpOnly` cookies when tokens must not reach the browser |
| Runtime config | `provideAppInitializer()` loads `/config.json` into an `InjectionToken`; one build for every environment | Values needed at build time only (feature stripping) → `fileReplacements`. Never secrets — everything in the bundle is public |
| Rendering | CSR for authenticated internal apps | Public, SEO or LCP-sensitive routes → `angular-ssr` |
| Tests | Vitest via `@angular/build:unit-test`, Playwright E2E | Karma still supported but no longer default — plan the move with `angular-migration` |
## 2. Structure and boundaries
```
src/app/
app.config.ts app.routes.ts # providers; top-level lazy routes only
core/ auth/ http/ config/ errors/ layout/ # singletons, provided once
features/orders/
orders.routes.ts index.ts # lazy route file; public API of the feature
pages/ components/ data/ model/ # routed (smart) / presentational / api + store / types + pure functions
shared/ui/ shared/util/ # reusable dumb components, directives, pipes; pure helpers
```
1. **Dependency direction is one-way:** `features → shared, core`; `core → shared`; `shared → nothing`. A feature imports another feature only through its `index.ts`. Enforce it with lint (`@nx/enforce-module-boundaries` or `eslint-plugin-boundaries`) — an unenforced rule is gone in six months.
2. **Pages inject, components receive.** Only `pages/` inject stores and API services; everything in `components/` takes `input()` and emits `output()`, which keeps it reusable and cheap to test.
3. **Naming is a repo-wide decision.** New repos follow the style guide (no suffix; `orders-api.ts`, `order-list.ts`, `auth-guard.ts`). Legacy repos keep suffixes by setting `"type": "component"` / `"service"` under `schematics` in `angular.json` so generated files match. The always-on Angular instructions file matches files by folder, not suffix, so both work.
4. **In Nx** the same layers become library types — `feature`, `ui`, `data-access`, `util` — with `scope:*` and `type:*` tags. Tree, tag matrix and lint config: `references/structure-and-boundaries.md`.
## 3. State — choose by scope and lifetime
| Scope | Pattern | Lifetime |
|---|---|---|
| One component | `signal()` / `computed()` / `linkedSignal()` | Component |
| A feature, few consumers | Service with private writable signals and public `asReadonly()`/`computed()` | Route (`providers: [OrdersState]` on the route) |
| A feature with entities, async methods, many consumers | NgRx SignalStore: `signalStore(withState, withComputed, withMethods)`, `rxMethod`, `withEntities` | Route |
| Server data | `httpResource()` in the page or store | Owner |
| Shareable UI state (filters, tab, page) | Router query params read through `withComponentInputBinding()` | URL |
| Session, preferences | Root-provided service or store | App |
One store per feature, provided at the feature route so it dies on leave; root-provided stores only for session-wide data. A store never imports another feature's store — compose in the page. SignalStore sample, `withHooks`/`withProps`/`signalMethod` and the RxJS boundary rules are in `references/state-and-di.md`.
## 4. RxJS boundary and DI design
1. RxJS owns *events over time* (typeahead, WebSocket, router events); signals own *state now*. Convert once with `toSignal()` at the edge of the service or store; templates read signals only.
2. Providers are functional and live in `app.config.ts`: `provideRouter`, `provideHttpClient(withInterceptors([...]))`, `provideAppInitializer`, `provideBrowserGlobalErrorListeners`. Feature-scoped services go in the route's `providers`.
3. Abstraction points are `InjectionToken`s with a root factory (`API_BASE_URL`, `LOGGER`, `STORAGE`) — swap them in tests and SSR without touching consumers.
4. `@Service()` (v22) for plain root singletons; `@Injectable()` when the class needs `useClass`/`useFactory`, a non-root scope or constructor DI. Both are correct — do not "fix" one into the other.
5. Guards, resolvers and interceptors are functions (`CanActivateFn`, `ResolveFn`, `HttpInterceptorFn`); a guard returns `true` or a `UrlTree`, never navigates imperatively.
## 5. Routing
- Every feature is `loadChildren: () => import('./features/orders/orders.routes')`; leaf pages use `loadComponent`. The initial bundle holds the shell, auth and the landing route.
- `withComponentInputBinding()` so params and query params arrive as `input()`; route `title` on every route; `data` typed through a shared interface.
- Resolvers only for data that must exist before first paint; otherwise render a skeleton and load in the page. Preloading: `withPreloading(PreloadAllModules)` for small apps, a custom strategy for large ones.
## 6. Platform services — exactly one of each
Auth (token acquisition, interceptor, guard), runtime config, global `ErrorHandler` reporting to monitoring, i18n strategy (`@angular/localize` build-time locales vs a runtime library such as Transloco when language switches without reload) and, only when teams deploy independently, micro-frontends (Native Federation). Defaults, trade-offs and wiring for each: `references/platform-decisions.md`.
## 7. Deliverable format
```
## Context — app type, teams, Angular version, constraints
## Decisions — table: decision | choice | why | revisit when (only rows that differ from section 1 need a why)
## Structure — folder or Nx library tree with the dependency rule and how lint enforces it
## State map — per feature: what state, which pattern, provided where
## ADRs — one per non-default decision, using references/adr-template.md
## Next steps — ordered, each shippable on its own; hand upgrades to angular-migration, SSR to angular-ssr
```
## Checklist
- [ ] Angular version and support status stated; v19 or below → upgrade plan comes first
- [ ] One naming convention chosen, written down, and matched by the `schematics` config
- [ ] Dependency direction defined and enforced by a lint rule that fails CI
- [ ] Every feature lazy-loaded with a public `index.ts`; no deep imports across features
- [ ] Each piece of state has one owner, one scope and a lifetime; no root store "just in case"
- [ ] Auth, config, error handler and i18n each exist once in `core/` and are provided in `app.config.ts`
- [ ] No secret or per-environment URL baked into the bundle; config loads at runtime
- [ ] Non-default choices (NgRx Store, micro-frontends, PrimeNG, SSR) have an ADR with a "revisit when"
- [ ] `strict`, `strictTemplates`, `@angular-eslint` with template accessibility rules, and bundle budgets run in CI
## Anti-patterns
- **`SharedModule`/barrel that exports everything** → standalone imports per component; `shared/ui` exports single components.
- **Root-provided store per feature** → provide at the feature route; state is released on leave and tests start clean.
- **NgRx Store for a CRUD app "for consistency"** → signals or SignalStore; keep Store for event-sourced domains with an ADR.
- **`BehaviorSubject` + `.value` as the state container** → private `signal()`, public `asReadonly()`; RxJS only for the event pipeline.
- **Feature importing another feature's internals** → export through `index.ts` or move the shared piece to `shared/`; lint blocks the deep path.
- **Secrets or API keys in `environment.ts`** → backend proxy; the bundle is public. Runtime `config.json` holds only public values.
- **Micro-frontends to fix a folder-structure problem** → module boundaries in one build first; split deployables only for independent release cadence.
- **Mixed `.component.ts` and suffix-less files** → pick one, configure schematics, rename in one mechanical PR.
## Go deeper
- `references/structure-and-boundaries.md` — full folder tree, Nx library types and tag matrix, boundary lint configs, naming config for `angular.json`
- `references/state-and-di.md` — signal service and SignalStore samples, store extras, RxJS operator choice, DI token patterns
- `references/platform-decisions.md` — auth, runtime config, error monitoring, i18n, UI library and micro-frontend decisions with wiring samples
- `references/adr-template.md` — ADR skeleton and a filled example
- `version-notes.md` in `../angular-development/references/` — what is default in v20, v21 and v22
- Siblings: `angular-development` (writing the code), `angular-migration` (legacy → modern), `angular-ssr`, `angular-performance`, `angular-testing`; `frontend-code-review` for pull requests