Eventiva/module-boundaries

Module Boundaries Configuration

Configure and enforce module boundaries for Eventiva packages using Nx tags and ESLint rules.

Quick Reference

Tag Structure

Projects should have 2-3 tags:

1. Type (required): type:core, type:database, type:extension, type:platform
2. Layer (required): layer:backend, layer:frontend, layer:shared
3. Capability (optional, multiple): capability:entities, capability:workflows, capability:ui

Type-Based Dependency Matrix

| Source | Can Depend On | |--------|---------------| | type:core | (nothing) | | type:database | type:core | | type:extension | type:core, type:extension | | type:platform | type:core, type:database, type:extension, type:platform |

Layer-Based Dependency Matrix

| Source | Can Depend On | |--------|---------------| | layer:backend | layer:backend, layer:shared | | layer:frontend | layer:frontend, layer:shared | | layer:shared | layer:shared |

Note: Projects with multiple tags must satisfy ALL applicable constraints.

Adding Tags to Projects

When creating or modifying packages, add 2-3 tags to project.json:

{
  "tags": ["type:extension", "layer:backend", "capability:entities", "capability:workflows"]
}

Tag Selection:

1. Choose one type tag based on module purpose
2. Choose one layer tag (backend/frontend/shared)
3. Add capability tags for what the module provides (entities, workflows, UI)

ESLint Configuration

Module boundaries are enforced in eslint.config.mjs with both type and layer constraints:

'@nx/enforce-module-boundaries': [
  'error',
  {
    depConstraints: [
      // Type-based constraints
      { sourceTag: 'type:core', onlyDependOnLibsWithTags: [] },
      { sourceTag: 'type:database', onlyDependOnLibsWithTags: ['type:core'] },
      { sourceTag: 'type:extension', onlyDependOnLibsWithTags: ['type:core', 'type:extension'] },
      { sourceTag: 'type:platform', onlyDependOnLibsWithTags: ['type:core', 'type:database', 'type:extension', 'type:platform'] },
      // Layer-based constraints
      { sourceTag: 'layer:backend', onlyDependOnLibsWithTags: ['layer:backend', 'layer:shared'] },
      { sourceTag: 'layer:frontend', onlyDependOnLibsWithTags: ['layer:frontend', 'layer:shared'] },
      { sourceTag: 'layer:shared', onlyDependOnLibsWithTags: ['layer:shared'] },
    ],
  },
],

Common Tasks

Adding a New Extension

1. Create the package structure
2. Add tags to project.json: "tags": ["type:extension", "layer:backend", "capability:entities", "capability:workflows"]
3. Add dependencies (must satisfy both type and layer constraints)
4. Run pnpm nx lint to verify

Moving Database Dependency to DevDependencies

If an extension needs database types but cannot have runtime dependency:

1. Remove from dependencies in package.json
2. Add to devDependencies in package.json
3. Verify lint passes

Fixing Boundary Violations

When ESLint reports a violation:

1. Check the error message for the violated constraint
2. Either:
   • Remove the invalid dependency, or
   • Move to devDependencies if only types are needed, or
   • Reconsider the package's type tag if the dependency is necessary

GitHub Labels

All tags (type, layer, capability) are synchronized with GitHub labels via .github/config.json. Labels use the same naming convention for consistency.

Reference

• Full documentation: docs/learnings/module-boundaries.md
• Nx documentation: https://nx.dev/docs/features/enforce-module-boundaries