# Structure, boundaries and file naming

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`:

```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`:

```js
'@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:

```json
// 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`.
