Org Skills

angular-architecture

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.

Download .zip Raw Source
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.

npx skills add AGCO-Global/org-skills --skill angular-architecture
# user-level instead of project-level:
npx skills add AGCO-Global/org-skills --skill angular-architecture -g

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.

Skill contents

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) 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 InjectionTokens 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

References

Deeper material the agent loads only when needed.