Org Skills

Structure, boundaries and file naming

Supporting material for angular-architecture. Agents load it on demand; it ships inside the skill folder.

RawSource

Open this when laying out a new workspace, adding a feature or an Nx library, or wiring the lint rule that enforces the dependency direction. Verified 2026-09 against https://angular.dev/style-guide and https://nx.dev/features/enforce-module-boundaries.

1. Single-app CLI workspace

src/app/
  app.ts  app.config.ts  app.routes.ts       # root component, providers, top-level lazy routes
  core/
    auth/        auth-store.ts  auth-interceptor.ts  auth-guard.ts
    http/        api-base-url.ts  error-interceptor.ts
    config/      app-config.ts        # InjectionToken + provideAppInitializer loader
    errors/      global-error-handler.ts
    layout/      shell.ts  nav.ts
  features/
    orders/
      orders.routes.ts                # the ONLY file the router imports
      index.ts                        # public API: what other features may import
      pages/       order-list.ts  order-detail.ts        # routed, inject stores/services
      components/  order-row.ts   order-status-badge.ts  # input()/output() only
      data/        orders-api.ts  orders-store.ts
      model/       order.ts       order-totals.ts        # types + pure functions
  shared/
    ui/     button/  dialog/  empty-state/   # presentational, zero feature knowledge
    util/   format-money.ts  date-range.ts   # pure functions, no DI

Dependency direction: features → shared, core · core → shared · shared → nothing · feature → feature only through index.ts.

Why index.ts and not deep imports: it is the only cheap way to change a feature's internals without a cross-team PR, and it is the thing a lint rule can check.

2. Enforcing it in a CLI workspace

eslint-plugin-boundaries (install eslint-plugin-boundaries), in eslint.config.js:

// eslint.config.js (flat config)
import boundaries from 'eslint-plugin-boundaries';

export default [
  {
    files: ['src/**/*.ts'],
    plugins: { boundaries },
    settings: {
      'boundaries/elements': [
        { type: 'core', pattern: 'src/app/core/*' },
        { type: 'shared', pattern: 'src/app/shared/*' },
        { type: 'feature', pattern: 'src/app/features/*', capture: ['name'] },
      ],
    },
    rules: {
      'boundaries/element-types': ['error', {
        default: 'disallow',
        rules: [
          { from: 'feature', allow: ['shared', 'core', ['feature', { name: '${from.name}' }]] },
          { from: 'core', allow: ['shared'] },
          { from: 'shared', allow: ['shared'] },
        ],
      }],
    },
  },
];

Run it in CI as ng lint. An unenforced boundary is gone within two sprints.

A cheaper stopgap while you adopt the plugin: no-restricted-imports with a pattern blocking **/features/*/!(index) — it catches deep imports but not the direction.

3. Nx workspace

Same layers, expressed as libraries with tags. One app, many libraries:

apps/portal/
libs/orders/feature-list/     tags: scope:orders,  type:feature
libs/orders/data-access/      tags: scope:orders,  type:data-access
libs/orders/ui/               tags: scope:orders,  type:ui
libs/orders/model/            tags: scope:orders,  type:util
libs/shared/ui/               tags: scope:shared,  type:ui
libs/shared/util/             tags: scope:shared,  type:util
Library type Contains May depend on
feature routed pages, smart components, the feature's routes file data-access, ui, util
data-access API services, stores, resources util
ui presentational components, directives, pipes util
util types, pure functions, constants util

Tag rules in eslint.config.js via @nx/enforce-module-boundaries:

'@nx/enforce-module-boundaries': ['error', {
  depConstraints: [
    { sourceTag: 'type:feature', onlyDependOnLibsWithTags: ['type:feature', 'type:data-access', 'type:ui', 'type:util'] },
    { sourceTag: 'type:data-access', onlyDependOnLibsWithTags: ['type:data-access', 'type:util'] },
    { sourceTag: 'type:ui', onlyDependOnLibsWithTags: ['type:ui', 'type:util'] },
    { sourceTag: 'type:util', onlyDependOnLibsWithTags: ['type:util'] },
    { sourceTag: 'scope:orders', onlyDependOnLibsWithTags: ['scope:orders', 'scope:shared'] },
    { sourceTag: 'scope:shared', onlyDependOnLibsWithTags: ['scope:shared'] },
  ],
}],

Two constraint families — type:* (what a library may reuse) and scope:* (which domain may see which) — cover almost every real rule. Add a third family only when a rule cannot be expressed with these.

Use Nx when at least one is true: more than one deployable app, libraries with different owners, or CI times that need affected-only builds. One app with four features does not need Nx; the folder tree plus a boundary lint rule gives the same discipline with no extra tooling.

4. File naming — pick once, configure the schematics

The current style guide names the file after the class with no type suffix: class UserProfile → user-profile.ts / user-profile.html / user-profile.css; OrdersApi → orders-api.ts; authGuard → auth-guard.ts. Angular CLI 20 and later scaffold this way by default.

New repos: take the default. Nothing to configure.

Existing repos on .component.ts / .service.ts: keep them — a rename touches every import and every test — and pin the schematics so generated files match:

// angular.json
"schematics": {
  "@schematics/angular:component": { "type": "component", "changeDetection": "OnPush" },
  "@schematics/angular:service":   { "type": "service" },
  "@schematics/angular:directive": { "type": "directive" },
  "@schematics/angular:guard":     { "type": "guard" }
}

Whichever you choose, write it in ARCHITECTURE.md and match the always-on instructions file, which selects files by folder rather than suffix so both conventions load the same rules. Never mix the two inside one project: a mixed tree makes every "where is the component for X" search a two-pattern search.

If you do decide to rename, do it as one mechanical PR with no behaviour change, and land it on a quiet branch day.

5. Where new code goes — the three questions

  1. Does anything outside this feature use it? No → inside the feature. Yes → shared/ui (component) or shared/util (function).
  2. Does it need DI or app state? No → model/ or shared/util as a pure function; it becomes trivially testable.
  3. Does exactly one instance exist for the whole app? Yes → core/, provided in app.config.ts.

A file that answers "yes" to (1) and "yes" to (2) is usually a feature that has not been named yet — give it a folder rather than pushing it into shared.