@agilewallaby/c4-model 2.1.0 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agilewallaby/c4-model",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "publishConfig": {
     "access": "public"
   },
@@ -11,8 +11,7 @@
   "dependencies": {
     "change-case": "^5.4.4",
     "glob": "^10.3.10",
-    "testcontainers": "^10.28.0",
-    "tslib": "^2.3.0"
+    "testcontainers": "^10.28.0"
   },
   "type": "module",
   "main": "./src/index.js",

package/src/archetype.d.ts

@@ -0,0 +1,30 @@
+import { TechnologyDefinition } from './core';
+export type ElementKind = 'person' | 'softwareSystem' | 'container' | 'component';
+export declare class ElementArchetype {
+    readonly name: string;
+    readonly elementKind: ElementKind;
+    readonly parent?: ElementArchetype | undefined;
+    readonly ownDescription?: string;
+    readonly ownTechnology?: string;
+    readonly ownTags: ReadonlyArray<string>;
+    readonly description?: string;
+    readonly technology?: string;
+    readonly tags: ReadonlyArray<string>;
+    constructor(name: string, elementKind: ElementKind, definition?: TechnologyDefinition, parent?: ElementArchetype | undefined);
+}
+export declare class RelationshipArchetype {
+    readonly name: string;
+    readonly parent?: RelationshipArchetype | undefined;
+    readonly ownDescription?: string;
+    readonly ownTechnology?: string;
+    readonly ownTags: ReadonlyArray<string>;
+    readonly description?: string;
+    readonly technology?: string;
+    readonly tags: ReadonlyArray<string>;
+    constructor(name: string, definition?: TechnologyDefinition, parent?: RelationshipArchetype | undefined);
+}
+export declare function mergeArchetypeWithOverride(archetype: {
+    description?: string;
+    technology?: string;
+    tags: ReadonlyArray<string>;
+}, override?: TechnologyDefinition): TechnologyDefinition;

package/src/buildModel.d.ts

@@ -0,0 +1,20 @@
+import { Model } from './model';
+type Catalog = Record<string, unknown>;
+type RootCatalog = Record<string, Catalog>;
+export interface AnyC4Module {
+    readonly key: string;
+    registerDefinitions(model: Model): Catalog;
+    buildRelationships(local: Catalog, dependencies: RootCatalog): void;
+}
+export interface BuildModelOptions {
+    modelName?: string;
+    modules?: ReadonlyArray<AnyC4Module>;
+    globPath?: string;
+    searchRoot?: string;
+}
+export declare function buildModelWithCatalog<TRoot>(options?: BuildModelOptions): Promise<{
+    model: Model;
+    catalog: TRoot;
+}>;
+export declare function buildModel(options?: BuildModelOptions): Promise<Model>;
+export {};

package/src/component.d.ts

@@ -1,7 +1,8 @@
 import { Element, TechnicalElement, TechnologyDefinition } from './core';
+import { ElementArchetype } from './archetype';
 export type ComponentDefinition = TechnologyDefinition;
 export declare class Component extends TechnicalElement {
     readonly name: string;
-    constructor(name: string, definition?: ComponentDefinition);
+    constructor(name: string, definition?: ComponentDefinition, archetype?: ElementArchetype, overrideDefinition?: TechnologyDefinition);
     getChildElements(): ReadonlyArray<Element>;
 }

package/src/container.d.ts

@@ -1,23 +1,24 @@
 import { Element, Group, TechnicalElement, TechnologyDefinition } from './core';
 import { Component, ComponentDefinition } from './component';
+import { ElementArchetype } from './archetype';
 export type ContainerDefinition = TechnologyDefinition;
 interface DefineComponent {
-    defineComponent(name: string, definition?: ComponentDefinition): Component;
+    defineComponent(name: string, archetypeOrDef?: ElementArchetype | ComponentDefinition, override?: ComponentDefinition): Component;
 }
 export declare class ContainerGroup extends Group implements DefineComponent {
     readonly name: string;
     private readonly container;
     private _components;
     constructor(name: string, container: DefineComponent);
-    defineComponent(name: string, definition?: ComponentDefinition): Component;
+    defineComponent(name: string, archetypeOrDef?: ElementArchetype | ComponentDefinition, override?: ComponentDefinition): Component;
     getComponents(): ReadonlyArray<Component>;
 }
 export declare class Container extends TechnicalElement implements DefineComponent {
     readonly name: string;
     private _components;
     private _groups;
-    constructor(name: string, definition?: ContainerDefinition);
-    defineComponent(name: string, definition?: ComponentDefinition): Component;
+    constructor(name: string, definition?: ContainerDefinition, archetype?: ElementArchetype, overrideDefinition?: TechnologyDefinition);
+    defineComponent(name: string, archetypeOrDef?: ElementArchetype | ComponentDefinition, override?: ComponentDefinition): Component;
     addGroup(groupName: string): ContainerGroup;
     getGroups(): ReadonlyArray<ContainerGroup>;
     getComponentsNotInGroups(): ReadonlyArray<Component>;

package/src/core.d.ts

@@ -1,3 +1,4 @@
+import { ElementArchetype, RelationshipArchetype } from './archetype';
 export interface Definition {
     description?: string;
     tags?: string[];
@@ -9,10 +10,12 @@ export declare abstract class Element {
     readonly name: string;
     readonly description?: string;
     readonly tags: ReadonlyArray<string>;
+    readonly archetype?: ElementArchetype;
+    readonly overrideDefinition?: TechnologyDefinition;
     private _relationships;
-    constructor(name: string, defaultTags?: string[], definition?: Definition);
+    constructor(name: string, defaultTags?: string[], definition?: Definition, archetype?: ElementArchetype, overrideDefinition?: TechnologyDefinition);
     get canonicalName(): string;
-    uses(otherElement: Element, definition?: TechnologyDefinition): void;
+    uses(otherElement: Element, archetypeOrDef?: RelationshipArchetype | TechnologyDefinition, override?: TechnologyDefinition): void;
     get relationships(): ReadonlyArray<Relationship>;
     abstract getChildElements(): ReadonlyArray<Element>;
     getRelationshipsInHierarchy(): ReadonlyArray<Relationship>;
@@ -20,7 +23,7 @@ export declare abstract class Element {
 }
 export declare abstract class TechnicalElement extends Element {
     readonly technology?: string;
-    constructor(name: string, defaultTags?: string[], definition?: TechnologyDefinition);
+    constructor(name: string, defaultTags?: string[], definition?: TechnologyDefinition, archetype?: ElementArchetype, overrideDefinition?: TechnologyDefinition);
 }
 export declare class Relationship {
     readonly source: Element;
@@ -28,7 +31,9 @@ export declare class Relationship {
     readonly description?: string;
     readonly tags: ReadonlyArray<string>;
     readonly technology?: string;
-    constructor(source: Element, destination: Element, definition?: TechnologyDefinition);
+    readonly archetype?: RelationshipArchetype;
+    readonly overrideDefinition?: TechnologyDefinition;
+    constructor(source: Element, destination: Element, definition?: TechnologyDefinition, archetype?: RelationshipArchetype, overrideDefinition?: TechnologyDefinition);
 }
 export declare class Group {
     readonly name: string;

package/src/generateDiagrams.d.ts

@@ -1,4 +1,4 @@
-import { BuildModelOptions } from './model';
+import { BuildModelOptions } from './buildModel';
 import { Views } from './views';
 export interface GenerateDiagramsOptions<TRoot> extends BuildModelOptions {
     views: (catalog: TRoot) => Views;

package/src/index.d.ts

@@ -1,3 +1,4 @@
+export * from './archetype';
 export * from './model';
 export * from './person';
 export * from './softwareSystem';
@@ -5,4 +6,5 @@ export * from './container';
 export * from './component';
 export * from './views';
 export * from './structurizrDslWriter';
+export * from './buildModel';
 export * from './generateDiagrams';

package/src/index.js

@@ -1,24 +1,77 @@
-// libs/c4-model/src/model.ts
-import { glob } from "glob";
-import { join, dirname } from "path";
-import { fileURLToPath } from "url";
+// libs/c4-model/src/archetype.ts
+var ElementArchetype = class {
+  constructor(name, elementKind, definition, parent) {
+    this.name = name;
+    this.elementKind = elementKind;
+    this.parent = parent;
+    this.ownDescription = definition?.description;
+    this.ownTechnology = definition?.technology;
+    this.ownTags = definition?.tags ?? [];
+    this.description = this.ownDescription ?? parent?.description;
+    this.technology = this.ownTechnology ?? parent?.technology;
+    this.tags = [...parent?.tags ?? [], ...this.ownTags];
+  }
+  ownDescription;
+  ownTechnology;
+  ownTags;
+  description;
+  technology;
+  tags;
+};
+var RelationshipArchetype = class {
+  constructor(name, definition, parent) {
+    this.name = name;
+    this.parent = parent;
+    this.ownDescription = definition?.description;
+    this.ownTechnology = definition?.technology;
+    this.ownTags = definition?.tags ?? [];
+    this.description = this.ownDescription ?? parent?.description;
+    this.technology = this.ownTechnology ?? parent?.technology;
+    this.tags = [...parent?.tags ?? [], ...this.ownTags];
+  }
+  ownDescription;
+  ownTechnology;
+  ownTags;
+  description;
+  technology;
+  tags;
+};
+function mergeArchetypeWithOverride(archetype, override) {
+  return {
+    description: override?.description ?? archetype.description,
+    technology: override?.technology ?? archetype.technology,
+    tags: [...archetype.tags, ...override?.tags ?? []]
+  };
+}
 
 // libs/c4-model/src/core.ts
 import { camelCase } from "change-case";
 var Element = class {
-  constructor(name, defaultTags = [], definition) {
+  constructor(name, defaultTags = [], definition, archetype, overrideDefinition) {
     this.name = name;
     this.description = definition?.description;
     this.tags = (definition?.tags ?? []).concat(["Element"]).concat(defaultTags);
+    this.archetype = archetype;
+    this.overrideDefinition = overrideDefinition;
   }
   description;
   tags;
+  archetype;
+  overrideDefinition;
   _relationships = [];
   get canonicalName() {
     return camelCase(this.name);
   }
-  uses(otherElement, definition) {
-    const relationship = new Relationship(this, otherElement, definition);
+  uses(otherElement, archetypeOrDef, override) {
+    let definition;
+    let archetype;
+    if (archetypeOrDef instanceof RelationshipArchetype) {
+      archetype = archetypeOrDef;
+      definition = mergeArchetypeWithOverride(archetypeOrDef, override);
+    } else {
+      definition = archetypeOrDef;
+    }
+    const relationship = new Relationship(this, otherElement, definition, archetype, override);
     this._relationships.push(relationship);
   }
   get relationships() {
@@ -37,22 +90,26 @@ var Element = class {
 };
 var TechnicalElement = class extends Element {
   technology;
-  constructor(name, defaultTags = [], definition) {
-    super(name, defaultTags, definition);
+  constructor(name, defaultTags = [], definition, archetype, overrideDefinition) {
+    super(name, defaultTags, definition, archetype, overrideDefinition);
     this.technology = definition?.technology;
   }
 };
 var Relationship = class {
-  constructor(source, destination, definition) {
+  constructor(source, destination, definition, archetype, overrideDefinition) {
     this.source = source;
     this.destination = destination;
     this.description = definition?.description;
     this.technology = definition?.technology;
     this.tags = (definition?.tags ?? []).concat(["Relationship"]);
+    this.archetype = archetype;
+    this.overrideDefinition = overrideDefinition;
   }
   description;
   tags;
   technology;
+  archetype;
+  overrideDefinition;
 };
 var Group = class {
   constructor(name) {
@@ -64,8 +121,8 @@ var Group = class {
 
 // libs/c4-model/src/component.ts
 var Component = class extends TechnicalElement {
-  constructor(name, definition) {
-    super(name, ["Component"], definition);
+  constructor(name, definition, archetype, overrideDefinition) {
+    super(name, ["Component"], definition, archetype, overrideDefinition);
     this.name = name;
   }
   getChildElements() {
@@ -81,8 +138,8 @@ var ContainerGroup = class extends Group {
     this.container = container;
   }
   _components = /* @__PURE__ */ new Map();
-  defineComponent(name, definition) {
-    const component = this.container.defineComponent(name, definition);
+  defineComponent(name, archetypeOrDef, override) {
+    const component = this.container.defineComponent(name, archetypeOrDef, override);
     this._components.set(name, component);
     return component;
   }
@@ -91,17 +148,25 @@ var ContainerGroup = class extends Group {
   }
 };
 var Container = class extends TechnicalElement {
-  constructor(name, definition) {
-    super(name, ["Container"], definition);
+  constructor(name, definition, archetype, overrideDefinition) {
+    super(name, ["Container"], definition, archetype, overrideDefinition);
     this.name = name;
   }
   _components = /* @__PURE__ */ new Map();
   _groups = /* @__PURE__ */ new Map();
-  defineComponent(name, definition) {
+  defineComponent(name, archetypeOrDef, override) {
     if (this._components.has(name)) {
       throw Error(`A Component named '${name}' is defined elsewhere in this Container. A Component can be defined only once.`);
     }
-    const component = new Component(name, definition);
+    let definition;
+    let archetype;
+    if (archetypeOrDef instanceof ElementArchetype) {
+      archetype = archetypeOrDef;
+      definition = mergeArchetypeWithOverride(archetypeOrDef, override);
+    } else {
+      definition = archetypeOrDef;
+    }
+    const component = new Component(name, definition, archetype, override);
     this._components.set(name, component);
     return component;
   }
@@ -133,8 +198,8 @@ var SoftwareSystemGroup = class extends Group {
     this.softwareSystem = softwareSystem;
   }
   _containers = /* @__PURE__ */ new Map();
-  defineContainer(name, definition) {
-    const container = this.softwareSystem.defineContainer(name, definition);
+  defineContainer(name, archetypeOrDef, override) {
+    const container = this.softwareSystem.defineContainer(name, archetypeOrDef, override);
     this._containers.set(name, container);
     return container;
   }
@@ -143,17 +208,25 @@ var SoftwareSystemGroup = class extends Group {
   }
 };
 var SoftwareSystem = class extends Element {
-  constructor(name, definition) {
-    super(name, ["Software System"], definition);
+  constructor(name, definition, archetype, overrideDefinition) {
+    super(name, ["Software System"], definition, archetype, overrideDefinition);
     this.name = name;
   }
   _containers = /* @__PURE__ */ new Map();
   _groups = /* @__PURE__ */ new Map();
-  defineContainer(name, definition) {
+  defineContainer(name, archetypeOrDef, override) {
     if (this._containers.has(name)) {
       throw Error(`A Container named '${name}' is defined elsewhere in this SoftwareSystem. A Container can be defined only once.`);
     }
-    const container = new Container(name, definition);
+    let definition;
+    let archetype;
+    if (archetypeOrDef instanceof ElementArchetype) {
+      archetype = archetypeOrDef;
+      definition = mergeArchetypeWithOverride(archetypeOrDef, override);
+    } else {
+      definition = archetypeOrDef;
+    }
+    const container = new Container(name, definition, archetype, override);
     this._containers.set(name, container);
     return container;
   }
@@ -179,8 +252,8 @@ var SoftwareSystem = class extends Element {
 
 // libs/c4-model/src/person.ts
 var Person = class extends Element {
-  constructor(name, definition) {
-    super(name, ["Person"], definition);
+  constructor(name, definition, archetype, overrideDefinition) {
+    super(name, ["Person"], definition, archetype, overrideDefinition);
     this.name = name;
   }
   getChildElements() {
@@ -189,7 +262,6 @@ var Person = class extends Element {
 };
 
 // libs/c4-model/src/model.ts
-var __dirname = dirname(fileURLToPath(import.meta.url));
 var ModelGroup = class extends Group {
   constructor(name, model) {
     super(name);
@@ -198,13 +270,13 @@ var ModelGroup = class extends Group {
   }
   softwareSystems = /* @__PURE__ */ new Map();
   people = /* @__PURE__ */ new Map();
-  defineSoftwareSystem(name, definition) {
-    const softwareSystem = this.model.defineSoftwareSystem(name, definition);
+  defineSoftwareSystem(name, archetypeOrDef, override) {
+    const softwareSystem = this.model.defineSoftwareSystem(name, archetypeOrDef, override);
     this.softwareSystems.set(name, softwareSystem);
     return softwareSystem;
   }
-  definePerson(name, definition) {
-    const person = this.model.definePerson(name, definition);
+  definePerson(name, archetypeOrDef, override) {
+    const person = this.model.definePerson(name, archetypeOrDef, override);
     this.people.set(name, person);
     return person;
   }
@@ -222,11 +294,19 @@ var Model = class {
   softwareSystems = /* @__PURE__ */ new Map();
   people = /* @__PURE__ */ new Map();
   groups = /* @__PURE__ */ new Map();
-  defineSoftwareSystem(name, definition) {
+  defineSoftwareSystem(name, archetypeOrDef, override) {
     if (this.softwareSystems.has(name)) {
       throw Error(`A SoftwareSystem named '${name}' is defined elsewhere in this Model. A SoftwareSystem can be defined only once.`);
     }
-    const system = new SoftwareSystem(name, definition);
+    let definition;
+    let archetype;
+    if (archetypeOrDef instanceof ElementArchetype) {
+      archetype = archetypeOrDef;
+      definition = mergeArchetypeWithOverride(archetypeOrDef, override);
+    } else {
+      definition = archetypeOrDef;
+    }
+    const system = new SoftwareSystem(name, definition, archetype, override);
     this.softwareSystems.set(name, system);
     return system;
   }
@@ -239,11 +319,19 @@ var Model = class {
     }
     return group;
   }
-  definePerson(name, definition) {
+  definePerson(name, archetypeOrDef, override) {
     if (this.people.has(name)) {
       throw Error(`A Person named '${name}' is defined elsewhere in this Model. A Person can be defined only once.`);
     }
-    const person = new Person(name, definition);
+    let definition;
+    let archetype;
+    if (archetypeOrDef instanceof ElementArchetype) {
+      archetype = archetypeOrDef;
+      definition = mergeArchetypeWithOverride(archetypeOrDef, override);
+    } else {
+      definition = archetypeOrDef;
+    }
+    const person = new Person(name, definition, archetype, override);
     this.people.set(name, person);
     return person;
   }
@@ -267,37 +355,6 @@ var Model = class {
     return Array.from(this.groups.values());
   }
 };
-async function buildModelWithCatalog(options = {}) {
-  const { modelName = "model", globPath = "c4.dsl.ts", searchRoot = __dirname } = options;
-  const model = new Model(modelName);
-  const result = await glob(`**/${globPath}`, { cwd: searchRoot });
-  if (result.length === 0) {
-    throw new Error(`No ${globPath} files found`);
-  }
-  const modules = await Promise.all(result.map((file) => import(join(searchRoot, file))));
-  const registrations = [];
-  const rootCatalog = {};
-  for (const module of modules) {
-    if (!module.c4Module) {
-      continue;
-    }
-    const instance = module.c4Module;
-    const local = instance.registerDefinitions(model);
-    rootCatalog[instance.key] = local;
-    registrations.push({ instance, key: instance.key, local });
-  }
-  if (registrations.length === 0) {
-    throw new Error(`No c4Module exports found in any ${globPath} files`);
-  }
-  for (const { instance, key, local } of registrations) {
-    const dependencies = Object.fromEntries(Object.entries(rootCatalog).filter(([k]) => k !== key));
-    instance.buildRelationships(local, dependencies);
-  }
-  return { model, catalog: rootCatalog };
-}
-async function buildModel(options = {}) {
-  return (await buildModelWithCatalog(options)).model;
-}
 
 // libs/c4-model/src/views.ts
 var View = class {
@@ -379,13 +436,115 @@ var StructurizrDSLWriter = class {
     this.model = model;
     this.views = views;
   }
+  collectArchetypes() {
+    const elementSet = /* @__PURE__ */ new Set();
+    const relationshipSet = /* @__PURE__ */ new Set();
+    const collectFromElement = (element) => {
+      if (element.archetype) {
+        let arch = element.archetype;
+        while (arch) {
+          elementSet.add(arch);
+          arch = arch.parent;
+        }
+      }
+      element.relationships.forEach((rel) => {
+        if (rel.archetype) {
+          let arch = rel.archetype;
+          while (arch) {
+            relationshipSet.add(arch);
+            arch = arch.parent;
+          }
+        }
+      });
+      element.getChildElements().forEach(collectFromElement);
+    };
+    const allElements = [...this.model.getPeople(), ...this.model.getSoftwareSystems()];
+    allElements.forEach(collectFromElement);
+    const sortArchetypes = (set) => {
+      const sorted = [];
+      const visited = /* @__PURE__ */ new Set();
+      const visit = (arch) => {
+        if (visited.has(arch)) return;
+        if (arch.parent && set.has(arch.parent)) visit(arch.parent);
+        visited.add(arch);
+        sorted.push(arch);
+      };
+      set.forEach(visit);
+      return sorted;
+    };
+    return {
+      elementArchetypes: sortArchetypes(elementSet),
+      relationshipArchetypes: sortArchetypes(relationshipSet)
+    };
+  }
+  writeArchetypes(level) {
+    const { elementArchetypes, relationshipArchetypes } = this.collectArchetypes();
+    if (elementArchetypes.length === 0 && relationshipArchetypes.length === 0) return "";
+    let dsl = this.writeLine(`archetypes {`, level);
+    for (const arch of elementArchetypes) {
+      const baseType = arch.parent ? arch.parent.name : arch.elementKind;
+      let inner = "";
+      if (arch.ownDescription) {
+        inner += this.writeLine(`description "${arch.ownDescription}"`, level + 2);
+      }
+      if (arch.ownTechnology) {
+        inner += this.writeLine(`technology "${arch.ownTechnology}"`, level + 2);
+      }
+      if (arch.ownTags.length > 0) {
+        inner += this.writeLine(`tags ${arch.ownTags.map((t) => `"${t}"`).join(" ")}`, level + 2);
+      }
+      if (inner) {
+        dsl += this.writeLine(`${arch.name} = ${baseType} {`, level + 1);
+        dsl += inner;
+        dsl += this.writeLine(`}`, level + 1);
+      } else {
+        dsl += this.writeLine(`${arch.name} = ${baseType} {}`, level + 1);
+      }
+    }
+    for (const arch of relationshipArchetypes) {
+      const arrow = arch.parent ? `--${arch.parent.name}->` : `->`;
+      let inner = "";
+      if (arch.ownDescription) {
+        inner += this.writeLine(`description "${arch.ownDescription}"`, level + 2);
+      }
+      if (arch.ownTechnology) {
+        inner += this.writeLine(`technology "${arch.ownTechnology}"`, level + 2);
+      }
+      if (arch.ownTags.length > 0) {
+        inner += this.writeLine(`tags ${arch.ownTags.map((t) => `"${t}"`).join(" ")}`, level + 2);
+      }
+      if (inner) {
+        dsl += this.writeLine(`${arch.name} = ${arrow} {`, level + 1);
+        dsl += inner;
+        dsl += this.writeLine(`}`, level + 1);
+      } else {
+        dsl += this.writeLine(`${arch.name} = ${arrow} {}`, level + 1);
+      }
+    }
+    dsl += this.writeLine(`}`, level);
+    return dsl;
+  }
   writeElement(elementType, element, level, closeElement = true) {
     let elementDsl = "";
-    elementDsl += this.writeLine(`${element.canonicalName} = ${elementType} "${element.name}" {`, level);
-    if (element.description) {
-      elementDsl += this.writeLine(`description "${element.description}"`, level + 1);
+    const type = element.archetype ? element.archetype.name : elementType;
+    elementDsl += this.writeLine(`${element.canonicalName} = ${type} "${element.name}" {`, level);
+    if (element.archetype) {
+      const ovr = element.overrideDefinition;
+      if (ovr?.description) {
+        elementDsl += this.writeLine(`description "${ovr.description}"`, level + 1);
+      }
+      if (ovr?.tags && ovr.tags.length > 0) {
+        elementDsl += this.writeLine(`tags ${ovr.tags.map((tag) => `"${tag}"`).join(" ")}`, level + 1);
+      }
+      if (ovr && "technology" in ovr && ovr.technology) {
+        elementDsl += this.writeLine(`technology "${ovr.technology}"`, level + 1);
+      }
+    } else {
+      if (element.description) {
+        elementDsl += this.writeLine(`description "${element.description}"`, level + 1);
+      }
+      elementDsl += this.writeLine(`tags ${element.tags.map((tag) => `"${tag}"`).join(" ")}`, level + 1);
     }
-    elementDsl += this.writeLine(`tags ${element.tags.map((tag) => `"${tag}"`).join(" ")}`, level + 1);
     if (closeElement) {
       elementDsl += this.writeLine(`}`, level);
     }
@@ -394,7 +553,9 @@ var StructurizrDSLWriter = class {
   writeComponent(component, level) {
     let componentDsl = "";
     componentDsl += this.writeElement("component", component, level, false);
-    componentDsl += this.writeLine(`technology "${component.technology}"`, level + 1);
+    if (!component.archetype && component.technology) {
+      componentDsl += this.writeLine(`technology "${component.technology}"`, level + 1);
+    }
     componentDsl += this.writeLine(`}`, level);
     return componentDsl;
   }
@@ -410,7 +571,9 @@ var StructurizrDSLWriter = class {
   writeContainer(container, level) {
     let containerDsl = "";
     containerDsl += this.writeElement("container", container, level, false);
-    containerDsl += this.writeLine(`technology "${container.technology}"`, level + 1);
+    if (!container.archetype && container.technology) {
+      containerDsl += this.writeLine(`technology "${container.technology}"`, level + 1);
+    }
     container.getComponentsNotInGroups().forEach((component) => {
       containerDsl += this.writeComponent(component, level + 1);
     });
@@ -441,17 +604,39 @@ var StructurizrDSLWriter = class {
     softwareSystemDsl += this.writeLine(`}`, level);
     return softwareSystemDsl;
   }
+  writeRelationship(relationship, level) {
+    let dsl = "";
+    if (relationship.archetype) {
+      const arrow = `--${relationship.archetype.name}->`;
+      const ovr = relationship.overrideDefinition;
+      const desc = ovr?.description ?? relationship.description ?? "uses";
+      dsl += this.writeLine(
+        `${relationship.source.canonicalName} ${arrow} ${relationship.destination.canonicalName} "${desc}" {`,
+        level
+      );
+      if (ovr?.technology) {
+        dsl += this.writeLine(`technology "${ovr.technology}"`, level + 1);
+      }
+      if (ovr?.tags && ovr.tags.length > 0) {
+        dsl += this.writeLine(`tags ${ovr.tags.map((tag) => `"${tag}"`).join(" ")}`, level + 1);
+      }
+      dsl += this.writeLine(`}`, level);
+    } else {
+      const tech = relationship.technology ? ` "${relationship.technology}"` : "";
+      dsl += this.writeLine(
+        `${relationship.source.canonicalName} -> ${relationship.destination.canonicalName} "${relationship.description ?? "uses"}"${tech} {`,
+        level
+      );
+      dsl += this.writeLine(`tags ${relationship.tags.map((tag) => `"${tag}"`).join(" ")}`, level + 1);
+      dsl += this.writeLine(`}`, level);
+    }
+    return dsl;
+  }
   writeRelationships(elements, level) {
     let relationshipsDsl = "";
     elements.forEach((element) => {
       element.getRelationshipsInHierarchy().forEach((relationship) => {
-        const tech = relationship.technology ? ` "${relationship.technology}"` : "";
-        relationshipsDsl += this.writeLine(
-          `${relationship.source.canonicalName} -> ${relationship.destination.canonicalName} "${relationship.description ?? "uses"}"${tech} {`,
-          level
-        );
-        relationshipsDsl += this.writeLine(`tags ${relationship.tags.map((tag) => `"${tag}"`).join(" ")}`, level + 1);
-        relationshipsDsl += this.writeLine(`}`, level);
+        relationshipsDsl += this.writeRelationship(relationship, level);
       });
     });
     return relationshipsDsl;
@@ -471,6 +656,7 @@ var StructurizrDSLWriter = class {
   writeModel(model, level) {
     let modelDsl = "";
     modelDsl += this.writeLine(`model {`, level);
+    modelDsl += this.writeArchetypes(level + 1);
     modelDsl += this.writeLine("// Elements", level + 1);
     model.getPeopleNotInGroups().forEach((person) => {
       modelDsl += this.writeElement("person", person, level + 1);
@@ -487,10 +673,7 @@ var StructurizrDSLWriter = class {
     return modelDsl;
   }
   writeView(view, viewType, level) {
-    let viewDsl = this.writeLine(
-      `${viewType}${view.subject ? ' "' + view.subject.canonicalName + '"' : ""} "${view.key}" {`,
-      level
-    );
+    let viewDsl = this.writeLine(`${viewType}${view.subject ? ' "' + view.subject.canonicalName + '"' : ""} "${view.key}" {`, level);
     viewDsl += this.writeLine(`description "${view.description}"`, level + 1);
     if (view.title) {
       viewDsl += this.writeLine(`title "${view.title}"`, level + 1);
@@ -540,6 +723,46 @@ var StructurizrDSLWriter = class {
   }
 };
 
+// libs/c4-model/src/buildModel.ts
+import { glob } from "glob";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+async function buildModelWithCatalog(options = {}) {
+  const { modelName = "model", modules: explicitModules } = options;
+  const model = new Model(modelName);
+  let c4Modules;
+  if (explicitModules) {
+    c4Modules = [...explicitModules];
+  } else {
+    const { globPath = "c4.dsl.ts", searchRoot = __dirname } = options;
+    const result = await glob(`**/${globPath}`, { cwd: searchRoot });
+    if (result.length === 0) {
+      throw new Error(`No ${globPath} files found`);
+    }
+    const imported = await Promise.all(result.map((file) => import(join(searchRoot, file))));
+    c4Modules = imported.filter((m) => m.c4Module).map((m) => m.c4Module);
+  }
+  if (c4Modules.length === 0) {
+    throw new Error("No c4Module instances found");
+  }
+  const registrations = [];
+  const rootCatalog = {};
+  for (const instance of c4Modules) {
+    const local = instance.registerDefinitions(model);
+    rootCatalog[instance.key] = local;
+    registrations.push({ instance, key: instance.key, local });
+  }
+  for (const { instance, key, local } of registrations) {
+    const dependencies = Object.fromEntries(Object.entries(rootCatalog).filter(([k]) => k !== key));
+    instance.buildRelationships(local, dependencies);
+  }
+  return { model, catalog: rootCatalog };
+}
+async function buildModel(options = {}) {
+  return (await buildModelWithCatalog(options)).model;
+}
+
 // libs/c4-model/src/generateDiagrams.ts
 import * as fs from "fs";
 import * as os from "os";
@@ -573,9 +796,11 @@ export {
   Component,
   Container,
   ContainerGroup,
+  ElementArchetype,
   Model,
   ModelGroup,
   Person,
+  RelationshipArchetype,
   SoftwareSystem,
   SoftwareSystemGroup,
   StructurizrDSLWriter,
@@ -583,5 +808,6 @@ export {
   Views,
   buildModel,
   buildModelWithCatalog,
-  generateDiagrams
+  generateDiagrams,
+  mergeArchetypeWithOverride
 };

package/src/model.d.ts

@@ -1,6 +1,7 @@
 import { Group } from './core';
 import { SoftwareSystem, SoftwareSystemDefinition } from './softwareSystem';
 import { Person, PersonDefinition } from './person';
+import { ElementArchetype } from './archetype';
 export type CatalogKeyOf<TRoot, TModule> = {
     [K in keyof TRoot]: TRoot[K] extends TModule ? K : never;
 }[keyof TRoot];
@@ -11,10 +12,10 @@ export interface C4Module<TRoot, TLocal> {
     buildRelationships(local: TLocal, dependencies: Dependencies<TRoot, TLocal>): void;
 }
 interface DefineSoftwareSystem {
-    defineSoftwareSystem(name: string, definition?: SoftwareSystemDefinition): SoftwareSystem;
+    defineSoftwareSystem(name: string, archetypeOrDef?: ElementArchetype | SoftwareSystemDefinition, override?: SoftwareSystemDefinition): SoftwareSystem;
 }
 interface DefinePerson {
-    definePerson(name: string, definition?: PersonDefinition): Person;
+    definePerson(name: string, archetypeOrDef?: ElementArchetype | PersonDefinition, override?: PersonDefinition): Person;
 }
 export declare class ModelGroup extends Group implements DefineSoftwareSystem, DefinePerson {
     readonly name: string;
@@ -22,14 +23,14 @@ export declare class ModelGroup extends Group implements DefineSoftwareSystem, D
     private softwareSystems;
     private people;
     constructor(name: string, model: DefineSoftwareSystem & DefinePerson);
-    defineSoftwareSystem(name: string, definition?: SoftwareSystemDefinition): SoftwareSystem;
-    definePerson(name: string, definition?: PersonDefinition): Person;
+    defineSoftwareSystem(name: string, archetypeOrDef?: ElementArchetype | SoftwareSystemDefinition, override?: SoftwareSystemDefinition): SoftwareSystem;
+    definePerson(name: string, archetypeOrDef?: ElementArchetype | PersonDefinition, override?: PersonDefinition): Person;
     getSoftwareSystems(): ReadonlyArray<SoftwareSystem>;
     getPeople(): ReadonlyArray<Person>;
 }
 export interface ModelDefinitions {
-    defineSoftwareSystem(name: string, definition?: SoftwareSystemDefinition): SoftwareSystem;
-    definePerson(name: string, definition?: PersonDefinition): Person;
+    defineSoftwareSystem(name: string, archetypeOrDef?: ElementArchetype | SoftwareSystemDefinition, override?: SoftwareSystemDefinition): SoftwareSystem;
+    definePerson(name: string, archetypeOrDef?: ElementArchetype | PersonDefinition, override?: PersonDefinition): Person;
 }
 export declare class Model {
     name: string;
@@ -37,9 +38,9 @@ export declare class Model {
     private softwareSystems;
     private people;
     private groups;
-    defineSoftwareSystem(name: string, definition?: SoftwareSystemDefinition): SoftwareSystem;
+    defineSoftwareSystem(name: string, archetypeOrDef?: ElementArchetype | SoftwareSystemDefinition, override?: SoftwareSystemDefinition): SoftwareSystem;
     addGroup(groupName: string): Group & ModelDefinitions;
-    definePerson(name: string, definition?: PersonDefinition): Person;
+    definePerson(name: string, archetypeOrDef?: ElementArchetype | PersonDefinition, override?: PersonDefinition): Person;
     validate(): void;
     getPeople(): ReadonlyArray<Person>;
     getSoftwareSystems(): ReadonlyArray<SoftwareSystem>;
@@ -47,14 +48,4 @@ export declare class Model {
     getSoftwareSystemsNotInGroups(): ReadonlyArray<SoftwareSystem>;
     getGroups(): ReadonlyArray<ModelGroup>;
 }
-export interface BuildModelOptions {
-    modelName?: string;
-    globPath?: string;
-    searchRoot?: string;
-}
-export declare function buildModelWithCatalog<TRoot>(options?: BuildModelOptions): Promise<{
-    model: Model;
-    catalog: TRoot;
-}>;
-export declare function buildModel(options?: BuildModelOptions): Promise<Model>;
 export {};

package/src/person.d.ts

@@ -1,7 +1,8 @@
-import { Definition, Element } from './core';
+import { Definition, Element, TechnologyDefinition } from './core';
+import { ElementArchetype } from './archetype';
 export type PersonDefinition = Definition;
 export declare class Person extends Element {
     readonly name: string;
-    constructor(name: string, definition?: PersonDefinition);
+    constructor(name: string, definition?: PersonDefinition, archetype?: ElementArchetype, overrideDefinition?: TechnologyDefinition);
     getChildElements(): ReadonlyArray<Element>;
 }

package/src/softwareSystem.d.ts

@@ -1,8 +1,9 @@
-import { Definition, Element, Group } from './core';
+import { Definition, Element, Group, TechnologyDefinition } from './core';
 import { Container, ContainerDefinition } from './container';
+import { ElementArchetype } from './archetype';
 export type SoftwareSystemDefinition = Definition;
 interface DefineContainer {
-    defineContainer(name: string, definition?: ContainerDefinition): Container;
+    defineContainer(name: string, archetypeOrDef?: ElementArchetype | ContainerDefinition, override?: ContainerDefinition): Container;
 }
 export interface SoftwareSystemReference {
     name: string;
@@ -12,15 +13,15 @@ export declare class SoftwareSystemGroup extends Group implements DefineContaine
     private readonly softwareSystem;
     private _containers;
     constructor(name: string, softwareSystem: DefineContainer);
-    defineContainer(name: string, definition?: ContainerDefinition): Container;
+    defineContainer(name: string, archetypeOrDef?: ElementArchetype | ContainerDefinition, override?: ContainerDefinition): Container;
     getContainers(): ReadonlyArray<Container>;
 }
 export declare class SoftwareSystem extends Element implements DefineContainer {
     readonly name: string;
     private _containers;
     private _groups;
-    constructor(name: string, definition?: SoftwareSystemDefinition);
-    defineContainer(name: string, definition?: ContainerDefinition): Container;
+    constructor(name: string, definition?: SoftwareSystemDefinition, archetype?: ElementArchetype, overrideDefinition?: TechnologyDefinition);
+    defineContainer(name: string, archetypeOrDef?: ElementArchetype | ContainerDefinition, override?: ContainerDefinition): Container;
     addGroup(groupName: string): SoftwareSystemGroup;
     getGroups(): ReadonlyArray<SoftwareSystemGroup>;
     getChildElements(): ReadonlyArray<Element>;

package/src/structurizrDslWriter.d.ts

@@ -4,12 +4,15 @@ export declare class StructurizrDSLWriter {
     private readonly model;
     private readonly views;
     constructor(model: Model, views: Views);
+    private collectArchetypes;
+    private writeArchetypes;
     private writeElement;
     private writeComponent;
     private writeContainerGroup;
     private writeContainer;
     private writeSoftwareSystemGroup;
     private writeSoftwareSystem;
+    private writeRelationship;
     private writeRelationships;
     private writeModelGroup;
     private writeModel;