Skip to main content

Modularization

This documentation is designed to explain the concept, setup, and usage of modularization in ADITO projects. It provides a structured, step-by-step walkthrough suitable both for first-time readers and for later reference when working with specific topics.

Reading the entire guide at least once in sequence is highly recommended. Skipping sections may lead to missing key relationships or contexts, resulting in suboptimal implementation decisions.

Why Modularization Matters​

In the past, all parts of the ADITO xRM platform were developed within a single monolithic Git repository. Customizing a project typically involved cloning this repository and applying changes directly. This practice led to a range of issues:

  • Upgrading difficulties: Updating to newer versions of ADITO xRM was complex and error-prone due to frequent and challenging-to-resolve merge conflicts.
  • Code reuse problems: Reusing functionality from one project in another was inefficient and often led to duplication or inconsistent maintenance.
  • Tight coupling of functionality: Modules such as "Contact Management" were inseparably linked to others like "Activity," even when not needed.
  • Poor team separation: All teams worked in the same codebase, increasing the risk of accidental cross-team changes and decreasing maintainability.

Modularization addresses these issues by:

  • Separating functional components into self-contained modules
  • Enabling selective reuse and customization
  • Supporting incremental upgrades and reducing merge conflicts
  • Enforcing clearer team boundaries and code ownership

Benefits of Modularization​

  • Faster setup of new projects.
  • Simplified editing of existing modules.
  • Clearer overview of modified projects.
  • Projects feel less overwhelming.
  • Updates apply without requiring merges of the basic project.
  • Fewer merge conflicts during normal development.
  • Improved visibility of changes through modules.

Definition of Terms​

The following terms are used throughout this guide.

module​

Modules are building blocks from which a project can be composed.

A single module is like a puzzle piece that can be assembled into a complete system.

Modules contain most of the data models available in the ADITO Designer. Certain data models that are project-specific are not present in modules. Preferences data models are only available in a reduced version.

Modules are identified in the package.json file with the adito.type property:

package.json
{
  "name": "@aditosoftware/my-module",
  "version": "1.2.3",
  "adito": {
    "type": "module"
  }
}
note

Testing a module is not possible without being connected/converted to a project.

project​

Projects are the final deliverables: complete systems assembled from modules.

A project is a complete puzzle that contains all the necessary pieces (modules).

Projects include additional data models with project-specific elements that modules do not provide:

  • system
  • application
  • dashboard

The Preferences data model is available here with the full configuration.

Only projects can be delivered as a web application.

A project is identified in the package.json file with the adito.type property:

{
  "name": "@aditosoftware/my-project",
  "version": "4.5.6",
  "adito": {
    "type": "project"
  }
}

Some Clarification of Terms:

  • Modularized Project: A project that integrates one or more modules. It does not matter if they are partly modularized or fully modularized.
  • Partially Modularized Project: A project that integrates modules but still contains its own custom content. Typically, these are customer projects.
  • Fully Modularized Project: A project composed entirely of modules and containing no own content (except possible configurations/translations). New objects such as contexts or processes are implemented via (new) module projects.
tip

See this guide on how and when to create a new module.

info

Do not confuse the term "project" with the opened projects in the ADITO Designer. Every package (module or project) can be opened in the ADITO Designer.

package​

A general term used to describe both project and module types managed via npm. In the context of modularization, npm packages are also referred to as dependencies.

Modification​

A Modification allows you to alter elements from a lower-level module within a higher-level package.

danger

Modifications can introduce unintended side effects. Prefer using Extension Points and Services whenever possible.

Extension Point​

An Extension Point is a well-defined interface for extending specific data models.

info

Implementations of Extension Points are stored in the modification folder and share the same file structure as a Modification.

However, Extension Points should be preferred over plain Modifications.

Service​

A Service Definition is a well-defined interface for extending processes.

info

Service implementations are stored in the modification folder and share the same file structure as a Modification.

However, Extension Points should be preferred over plain Modifications.

Naming Conventions​

You should always follow AID001 Coding Styles. Use these rules as an extension to the official naming conventions.

Git Repository Names​

  • Use lowercase letters only (e.g., salutation)
  • Hyphens are allowed (e.g., csv-importer)
  • Avoid underscores or other special characters
  • Optionally add a meaningful icon and description in Git, as shown in the xRM-Platform subgroup
tip

See the official npm documentation on how to name a package.

Extension Points​

  • Format: <DescriptiveName>ExtensionPoint (e.g., NormalFieldsExtensionPoint, HighPriorityViewsExtensionPoint)
  • Use specific, descriptive names

Extension Point Implementations​

  • Follow AID001 Coding Styles.
  • Treat implementations like normal child elements (they are not special-cased beyond style rules)

Language Files​

  • Format: LANGUAGE_<lang>_<module> (e.g., LANGUAGE_de_activity)
  • Files created via Designer use the correct format automatically
  • Do not rename – the format is required for proper merging during transpile

Services​

  • Global services: <module><ServiceName>_service (e.g., attributeUsageContexts_service)
  • Entity-bound services: <module><EntityEvent>_service (e.g., activityOnDBDelete_service)
tip

Choose names that clearly express what the service computes or performs

Service Implementations​

  • Use expressive names (e.g., addNewActivity_impl)
  • Avoid generic patterns like <module>_impl unless temporary
  • Temporary services: prefix with tmp_ (e.g., tmp_impl)
tip

The implementation name should make its purpose obvious

Modifications​

  • Do not change the autogenerated names

Keyword Registries​

  • Format: <ModuleName>Keywords_registry (e.g., ActivityKeywords_registry, ContactManagementKeywords_registry)