@agilewallaby/c4-model 1.0.2 → 1.1.0

package/CLAUDE.md

@@ -0,0 +1,45 @@
+# c4-model
+
+## About
+
+TypeScript library for defining C4 architecture models and generating Structurizr DSL.
+
+## Structurizr DSL Reference
+
+Structurizr DSL docs are available locally at `docs/structurizr/` (run
+`pnpm fetch-structurizr-docs` to populate). When working on `structurizrDslWriter.ts`,
+read the relevant files from that directory. If not present locally, source is:
+https://github.com/structurizr/structurizr.github.io/tree/main/dsl
+
+## Running tasks
+
+```sh
+pnpm exec nx run c4-model:test
+pnpm exec nx run c4-model:build
+pnpm exec nx run c4-model:lint
+```
+
+## Architecture
+
+- `core.ts` — Base classes: `Element`, `TechnicalElement`, `Relationship`, `Reference`, `Group`
+- `model.ts` — `Model` class, `C4Module` interface, `buildModel()` two-phase loader
+- `person.ts` / `softwareSystem.ts` / `container.ts` / `component.ts` — C4 element types
+- `views.ts` — View definitions (system landscape, context, container, component)
+- `structurizrDslWriter.ts` — Generates Structurizr DSL from a Model + Views
+
+## C4Module pattern
+
+Modules are defined in `c4.dsl.ts` files discovered by `buildModel()` via glob. Each exports a `c4Module`:
+
+```ts
+export const c4Module: C4Module<RootCatalog, LocalCatalog> = {
+    key: 'myModule',
+    registerDefinitions(model) { /* define elements, return catalog */ },
+    buildRelationships(local, dependencies) { /* wire up cross-module relationships */ },
+}
+```
+
+- **Phase 1**: All modules register definitions; results stored in a root catalog keyed by module key
+- **Phase 2**: Each module receives its own catalog and all other modules' catalogs to build relationships
+- `CatalogKeyOf` and `Dependencies` utility types ensure type-safe keys and dependency access
+- See `libs/c4-model-examples` for integration tests using `buildModel()`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agilewallaby/c4-model",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "publishConfig": {
     "access": "public"
   },
@@ -9,9 +9,13 @@
     "url": "https://github.com/AgileWallaby/c4.git"
   },
   "dependencies": {
+    "change-case": "^5.4.4",
+    "glob": "^10.3.10",
+    "testcontainers": "^10.28.0",
     "tslib": "^2.3.0"
   },
   "type": "commonjs",
   "main": "./src/index.js",
-  "typings": "./src/index.d.ts"
-}
+  "typings": "./src/index.d.ts",
+  "types": "./src/index.d.ts"
+}

package/src/component.d.ts

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

package/src/{lib/component.js → component.js}

@@ -1,10 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ReferencedComponent = exports.Component = void 0;
+exports.Component = void 0;
 const core_1 = require("./core");
 class Component extends core_1.TechnicalElement {
     constructor(name, definition) {
-        super(name, ["Component"], definition);
+        super(name, ['Component'], definition);
         this.name = name;
     }
     getChildElements() {
@@ -12,7 +12,4 @@ class Component extends core_1.TechnicalElement {
     }
 }
 exports.Component = Component;
-class ReferencedComponent extends core_1.Reference {
-}
-exports.ReferencedComponent = ReferencedComponent;
 //# sourceMappingURL=component.js.map

package/src/component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.js","sourceRoot":"","sources":["../../../../libs/c4-model/src/component.ts"],"names":[],"mappings":";;;AAAA,iCAAwE;AAIxE,MAAa,SAAU,SAAQ,uBAAgB;IAC3C,YAC6B,IAAY,EACrC,UAAgC;QAEhC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,CAAC,EAAE,UAAU,CAAC,CAAA;QAHb,SAAI,GAAJ,IAAI,CAAQ;IAIzC,CAAC;IAEM,gBAAgB;QACnB,OAAO,EAAE,CAAA;IACb,CAAC;CACJ;AAXD,8BAWC"}

package/src/{lib/container.d.ts → container.d.ts}

@@ -1,11 +1,10 @@
-import { Element, Group, Reference, TechnicalElement, TechnologyDefinition } from "./core";
-import { Component, ComponentDefinition, ReferencedComponent } from "./component";
-export interface ContainerDefinition extends TechnologyDefinition {
-}
+import { Element, Group, TechnicalElement, TechnologyDefinition } from './core';
+import { Component, ComponentDefinition } from './component';
+export type ContainerDefinition = TechnologyDefinition;
 interface DefineComponent {
     defineComponent(name: string, definition?: ComponentDefinition): Component;
 }
-export declare class ContainerGroup extends Group<Container> implements DefineComponent {
+export declare class ContainerGroup extends Group implements DefineComponent {
     readonly name: string;
     private readonly container;
     private _components;
@@ -24,7 +23,4 @@ export declare class Container extends TechnicalElement implements DefineCompone
     getComponentsNotInGroups(): ReadonlyArray<Component>;
     getChildElements(): ReadonlyArray<Element>;
 }
-export declare class ReferencedContainer extends Reference<Component> {
-    referenceComponent(name: string): ReferencedComponent;
-}
 export {};

package/src/{lib/container.js → container.js}

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ReferencedContainer = exports.Container = exports.ContainerGroup = void 0;
+exports.Container = exports.ContainerGroup = void 0;
 const core_1 = require("./core");
 const component_1 = require("./component");
+// TODO: This will be a Group<Container> if that is added back in
 class ContainerGroup extends core_1.Group {
     constructor(name, container) {
         super(name);
@@ -22,14 +23,14 @@ class ContainerGroup extends core_1.Group {
 exports.ContainerGroup = ContainerGroup;
 class Container extends core_1.TechnicalElement {
     constructor(name, definition) {
-        super(name, ["Container"], definition);
+        super(name, ['Container'], definition);
         this.name = name;
         this._components = new Map();
         this._groups = new Map();
     }
     defineComponent(name, definition) {
         if (this._components.has(name)) {
-            throw Error(`A Component named '${name}' is defined elsewhere in this Container. A Component can be defined only once, but can be referenced multiple times.`);
+            throw Error(`A Component named '${name}' is defined elsewhere in this Container. A Component can be defined only once.`);
         }
         const component = new component_1.Component(name, definition);
         this._components.set(name, component);
@@ -47,19 +48,12 @@ class Container extends core_1.TechnicalElement {
         return Array.from(this._groups.values());
     }
     getComponentsNotInGroups() {
-        const componentsInGroups = this.getGroups().flatMap(group => group.getComponents());
-        return Array.from(this._components.values()).filter(component => !componentsInGroups.includes(component));
+        const componentsInGroups = this.getGroups().flatMap((group) => group.getComponents());
+        return Array.from(this._components.values()).filter((component) => !componentsInGroups.includes(component));
     }
     getChildElements() {
         return Array.from(this._components.values());
     }
 }
 exports.Container = Container;
-class ReferencedContainer extends core_1.Reference {
-    referenceComponent(name) {
-        const componentReference = this.referenceChild(name, (name) => new component_1.ReferencedComponent(name));
-        return componentReference;
-    }
-}
-exports.ReferencedContainer = ReferencedContainer;
 //# sourceMappingURL=container.js.map

package/src/container.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"container.js","sourceRoot":"","sources":["../../../../libs/c4-model/src/container.ts"],"names":[],"mappings":";;;AAAA,iCAA+E;AAC/E,2CAA4D;AAQ5D,iEAAiE;AACjE,MAAa,cAAe,SAAQ,YAAK;IAGrC,YAC6B,IAAY,EACpB,SAA0B;QAE3C,KAAK,CAAC,IAAI,CAAC,CAAA;QAHc,SAAI,GAAJ,IAAI,CAAQ;QACpB,cAAS,GAAT,SAAS,CAAiB;QAJvC,gBAAW,GAAG,IAAI,GAAG,EAAqB,CAAA;IAOlD,CAAC;IAEM,eAAe,CAAC,IAAY,EAAE,UAAgC;QACjE,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;QAClE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAA;QACrC,OAAO,SAAS,CAAA;IACpB,CAAC;IAEM,aAAa;QAChB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAA;IAChD,CAAC;CACJ;AAnBD,wCAmBC;AAED,MAAa,SAAU,SAAQ,uBAAgB;IAI3C,YAC6B,IAAY,EACrC,UAAgC;QAEhC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,CAAC,EAAE,UAAU,CAAC,CAAA;QAHb,SAAI,GAAJ,IAAI,CAAQ;QAJjC,gBAAW,GAAG,IAAI,GAAG,EAAqB,CAAA;QAC1C,YAAO,GAAG,IAAI,GAAG,EAA0B,CAAA;IAOnD,CAAC;IAEM,eAAe,CAAC,IAAY,EAAE,UAAgC;QACjE,IAAI,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,MAAM,KAAK,CAAC,sBAAsB,IAAI,iFAAiF,CAAC,CAAA;QAC5H,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,qBAAS,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;QAEjD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAA;QAErC,OAAO,SAAS,CAAA;IACpB,CAAC;IAEM,QAAQ,CAAC,SAAiB;QAC7B,IAAI,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;QACvC,IAAI,CAAC,KAAK,EAAE,CAAC;YACT,KAAK,GAAG,IAAI,cAAc,CAAC,SAAS,EAAE,IAAI,CAAC,CAAA;YAC3C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;QACtC,CAAC;QACD,OAAO,KAAK,CAAA;IAChB,CAAC;IAEM,SAAS;QACZ,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IAC5C,CAAC;IAEM,wBAAwB;QAC3B,MAAM,kBAAkB,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC,CAAA;QACrF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,kBAAkB,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAA;IAC/G,CAAC;IAEM,gBAAgB;QACnB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAA;IAChD,CAAC;CACJ;AA5CD,8BA4CC"}

package/src/core.d.ts

@@ -0,0 +1,36 @@
+export interface Definition {
+    description?: string;
+    tags?: string[];
+}
+export interface TechnologyDefinition extends Definition {
+    technology?: string;
+}
+export declare abstract class Element {
+    readonly name: string;
+    readonly description?: string;
+    readonly tags: ReadonlyArray<string>;
+    private _relationships;
+    constructor(name: string, defaultTags?: string[], definition?: Definition);
+    get canonicalName(): string;
+    uses(otherElement: Element, definition?: TechnologyDefinition): void;
+    get relationships(): ReadonlyArray<Relationship>;
+    abstract getChildElements(): ReadonlyArray<Element>;
+    getRelationshipsInHierarchy(): ReadonlyArray<Relationship>;
+    getChildElementNames(path?: string): ReadonlyArray<string>;
+}
+export declare abstract class TechnicalElement extends Element {
+    readonly technology?: string;
+    constructor(name: string, defaultTags?: string[], definition?: TechnologyDefinition);
+}
+export declare class Relationship {
+    readonly source: Element;
+    readonly destination: Element;
+    readonly description?: string;
+    readonly tags: ReadonlyArray<string>;
+    readonly technology?: string;
+    constructor(source: Element, destination: Element, definition?: TechnologyDefinition);
+}
+export declare class Group {
+    readonly name: string;
+    constructor(name: string);
+}

package/src/{lib/core.js → core.js}

@@ -1,16 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Group = exports.Reference = exports.Relationship = exports.TechnicalElement = exports.Element = void 0;
+exports.Group = exports.Relationship = exports.TechnicalElement = exports.Element = void 0;
+const change_case_1 = require("change-case");
 class Element {
     constructor(name, defaultTags = [], definition) {
         var _a;
         this.name = name;
         this._relationships = [];
         this.description = definition === null || definition === void 0 ? void 0 : definition.description;
-        this.tags = ((_a = definition === null || definition === void 0 ? void 0 : definition.tags) !== null && _a !== void 0 ? _a : []).concat(["Element"]).concat(defaultTags);
+        this.tags = ((_a = definition === null || definition === void 0 ? void 0 : definition.tags) !== null && _a !== void 0 ? _a : []).concat(['Element']).concat(defaultTags);
     }
     get canonicalName() {
-        return this.name.toLowerCase();
+        return (0, change_case_1.camelCase)(this.name);
     }
     uses(otherElement, definition) {
         const relationship = new Relationship(this, otherElement, definition);
@@ -20,10 +21,10 @@ class Element {
         return this._relationships;
     }
     getRelationshipsInHierarchy() {
-        return this._relationships.concat(this.getChildElements().flatMap(element => element.getRelationshipsInHierarchy()));
+        return this._relationships.concat(this.getChildElements().flatMap((element) => element.getRelationshipsInHierarchy()));
     }
     getChildElementNames(path) {
-        const result = Array.from(this.getChildElements()).flatMap(reference => {
+        const result = Array.from(this.getChildElements()).flatMap((reference) => {
             const currentPath = `${path ? path : '' + this.name}.${reference.name}`;
             return [currentPath, ...reference.getChildElementNames(currentPath)];
         });
@@ -45,44 +46,14 @@ class Relationship {
         this.destination = destination;
         this.description = definition === null || definition === void 0 ? void 0 : definition.description;
         this.technology = definition === null || definition === void 0 ? void 0 : definition.technology;
-        this.tags = ((_a = definition === null || definition === void 0 ? void 0 : definition.tags) !== null && _a !== void 0 ? _a : []).concat(["Relationship"]);
+        this.tags = ((_a = definition === null || definition === void 0 ? void 0 : definition.tags) !== null && _a !== void 0 ? _a : []).concat(['Relationship']);
     }
 }
 exports.Relationship = Relationship;
-class Reference {
-    constructor(name) {
-        this.name = name;
-        this._references = new Map();
-    }
-    get canonicalName() {
-        return this.name.toLowerCase();
-    }
-    referenceChild(name, createChild) {
-        let reference = this._references.get(name);
-        if (!reference) {
-            reference = createChild(name);
-            this._references.set(name, reference);
-        }
-        return reference;
-    }
-    get references() {
-        return Array.from(this._references.values());
-    }
-    getChildElementNames(path) {
-        const result = Array.from(this._references.values()).flatMap(reference => {
-            const currentPath = `${path ? path : '' + this.name}.${reference.name}`;
-            return [currentPath, ...reference.getChildElementNames(currentPath)];
-        });
-        return result;
-    }
-}
-exports.Reference = Reference;
 class Group {
     constructor(name) {
         this.name = name;
     }
-    addToGroup(groupCollection, groupMember) {
-    }
 }
 exports.Group = Group;
 //# sourceMappingURL=core.js.map

package/src/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../../../../libs/c4-model/src/core.ts"],"names":[],"mappings":";;;AAAA,6CAAuC;AAWvC,MAAsB,OAAO;IAMzB,YACoB,IAAY,EAC5B,cAAwB,EAAE,EAC1B,UAAuB;;QAFP,SAAI,GAAJ,IAAI,CAAQ;QAHxB,mBAAc,GAAmB,EAAE,CAAA;QAOvC,IAAI,CAAC,WAAW,GAAG,UAAU,aAAV,UAAU,uBAAV,UAAU,CAAE,WAAW,CAAA;QAC1C,IAAI,CAAC,IAAI,GAAG,CAAC,MAAA,UAAU,aAAV,UAAU,uBAAV,UAAU,CAAE,IAAI,mCAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAA;IAChF,CAAC;IAED,IAAW,aAAa;QACpB,OAAO,IAAA,uBAAS,EAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC/B,CAAC;IAEM,IAAI,CAAC,YAAqB,EAAE,UAAiC;QAChE,MAAM,YAAY,GAAG,IAAI,YAAY,CAAC,IAAI,EAAE,YAAY,EAAE,UAAU,CAAC,CAAA;QACrE,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,YAAY,CAAC,CAAA;IAC1C,CAAC;IAED,IAAW,aAAa;QACpB,OAAO,IAAI,CAAC,cAAc,CAAA;IAC9B,CAAC;IAIM,2BAA2B;QAC9B,OAAO,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,2BAA2B,EAAE,CAAC,CAAC,CAAA;IAC1H,CAAC;IAEM,oBAAoB,CAAC,IAAa;QACrC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,SAAS,EAAE,EAAE;YACrE,MAAM,WAAW,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,IAAI,IAAI,SAAS,CAAC,IAAI,EAAE,CAAA;YACvE,OAAO,CAAC,WAAW,EAAE,GAAG,SAAS,CAAC,oBAAoB,CAAC,WAAW,CAAC,CAAC,CAAA;QACxE,CAAC,CAAC,CAAA;QACF,OAAO,MAAM,CAAA;IACjB,CAAC;CACJ;AAzCD,0BAyCC;AAED,MAAsB,gBAAiB,SAAQ,OAAO;IAGlD,YAAY,IAAY,EAAE,cAAwB,EAAE,EAAE,UAAiC;QACnF,KAAK,CAAC,IAAI,EAAE,WAAW,EAAE,UAAU,CAAC,CAAA;QACpC,IAAI,CAAC,UAAU,GAAG,UAAU,aAAV,UAAU,uBAAV,UAAU,CAAE,UAAU,CAAA;IAC5C,CAAC;CACJ;AAPD,4CAOC;AAED,MAAa,YAAY;IAKrB,YACoB,MAAe,EACf,WAAoB,EACpC,UAAiC;;QAFjB,WAAM,GAAN,MAAM,CAAS;QACf,gBAAW,GAAX,WAAW,CAAS;QAGpC,IAAI,CAAC,WAAW,GAAG,UAAU,aAAV,UAAU,uBAAV,UAAU,CAAE,WAAW,CAAA;QAC1C,IAAI,CAAC,UAAU,GAAG,UAAU,aAAV,UAAU,uBAAV,UAAU,CAAE,UAAU,CAAA;QACxC,IAAI,CAAC,IAAI,GAAG,CAAC,MAAA,UAAU,aAAV,UAAU,uBAAV,UAAU,CAAE,IAAI,mCAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,cAAc,CAAC,CAAC,CAAA;IACjE,CAAC;CACJ;AAdD,oCAcC;AAED,MAAa,KAAK;IACd,YAAmC,IAAY;QAAZ,SAAI,GAAJ,IAAI,CAAQ;IAAG,CAAC;CAItD;AALD,sBAKC"}

package/src/generateDiagrams.d.ts

@@ -0,0 +1,7 @@
+import { BuildModelOptions } from './model';
+import { Views } from './views';
+export interface GenerateDiagramsOptions<TRoot> extends BuildModelOptions {
+    views: (catalog: TRoot) => Views;
+    outputDir: string;
+}
+export declare function generateDiagrams<TRoot>(options: GenerateDiagramsOptions<TRoot>): Promise<string[]>;

package/src/generateDiagrams.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateDiagrams = generateDiagrams;
+const tslib_1 = require("tslib");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const testcontainers_1 = require("testcontainers");
+const model_1 = require("./model");
+const structurizrDslWriter_1 = require("./structurizrDslWriter");
+function generateDiagrams(options) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const { views: viewsFactory, outputDir } = options, buildOptions = tslib_1.__rest(options
+        // a) Build model + catalog
+        , ["views", "outputDir"]);
+        // a) Build model + catalog
+        const { model, catalog } = yield (0, model_1.buildModelWithCatalog)(buildOptions);
+        // b) Build views from catalog via callback
+        const views = viewsFactory(catalog);
+        // c) Generate DSL string
+        const dsl = new structurizrDslWriter_1.StructurizrDSLWriter(model, views).write();
+        // d) Write DSL to a temp directory (resolve symlinks so Docker bind mounts work on macOS)
+        const tmpDir = yield fs.promises.mkdtemp(path.join(fs.realpathSync(os.tmpdir()), 'c4-diagrams-'));
+        yield fs.promises.writeFile(path.join(tmpDir, 'workspace.dsl'), dsl, 'utf8');
+        // e) Run Structurizr CLI container to export .mmd files
+        yield new testcontainers_1.GenericContainer('structurizr/structurizr')
+            .withBindMounts([{ source: tmpDir, target: '/workspace', mode: 'rw' }])
+            .withCommand(['export', '-w', '/workspace/workspace.dsl', '-f', 'mermaid', '-o', '/workspace'])
+            .withWaitStrategy(testcontainers_1.Wait.forOneShotStartup())
+            .start();
+        // f) Copy .mmd files to outputDir
+        yield fs.promises.mkdir(outputDir, { recursive: true });
+        const tmpFiles = yield fs.promises.readdir(tmpDir);
+        const mmdFiles = tmpFiles.filter((f) => f.endsWith('.mmd'));
+        for (const file of mmdFiles) {
+            yield fs.promises.copyFile(path.join(tmpDir, file), path.join(outputDir, file));
+        }
+        const generatedFiles = mmdFiles.map((f) => path.join(outputDir, f));
+        // g) For each .mmd file, render to .png via minlag/mermaid-cli container
+        for (const file of mmdFiles) {
+            const baseName = path.basename(file, '.mmd');
+            const pngFile = `${baseName}.png`;
+            yield new testcontainers_1.GenericContainer('minlag/mermaid-cli')
+                .withBindMounts([{ source: tmpDir, target: '/data', mode: 'rw' }])
+                .withCommand(['-i', `/data/${file}`, '-o', `/data/${pngFile}`])
+                .withWaitStrategy(testcontainers_1.Wait.forOneShotStartup())
+                .start();
+            yield fs.promises.copyFile(path.join(tmpDir, pngFile), path.join(outputDir, pngFile));
+            generatedFiles.push(path.join(outputDir, pngFile));
+        }
+        // h) Return all generated file paths
+        return generatedFiles;
+    });
+}
+//# sourceMappingURL=generateDiagrams.js.map

package/src/generateDiagrams.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateDiagrams.js","sourceRoot":"","sources":["../../../../libs/c4-model/src/generateDiagrams.ts"],"names":[],"mappings":"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"}

package/src/index.d.ts

@@ -1,3 +1,8 @@
-export * from './lib/model';
-export * from './lib/views';
-export * from './lib/structurizrDslWriter';
+export * from './model';
+export * from './person';
+export * from './softwareSystem';
+export * from './container';
+export * from './component';
+export * from './views';
+export * from './structurizrDslWriter';
+export * from './generateDiagrams';

package/src/index.js

@@ -1,7 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
-tslib_1.__exportStar(require("./lib/model"), exports);
-tslib_1.__exportStar(require("./lib/views"), exports);
-tslib_1.__exportStar(require("./lib/structurizrDslWriter"), exports);
+tslib_1.__exportStar(require("./model"), exports);
+tslib_1.__exportStar(require("./person"), exports);
+tslib_1.__exportStar(require("./softwareSystem"), exports);
+tslib_1.__exportStar(require("./container"), exports);
+tslib_1.__exportStar(require("./component"), exports);
+tslib_1.__exportStar(require("./views"), exports);
+tslib_1.__exportStar(require("./structurizrDslWriter"), exports);
+tslib_1.__exportStar(require("./generateDiagrams"), exports);
 //# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/c4-model/src/index.ts"],"names":[],"mappings":";;;AAAA,sDAA2B;AAC3B,sDAA2B;AAC3B,qEAA0C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/c4-model/src/index.ts"],"names":[],"mappings":";;;AAAA,kDAAuB;AACvB,mDAAwB;AACxB,2DAAgC;AAChC,sDAA2B;AAC3B,sDAA2B;AAC3B,kDAAuB;AACvB,iEAAsC;AACtC,6DAAkC"}

package/src/{lib/model.d.ts → model.d.ts}

@@ -1,13 +1,22 @@
 import { Group } from './core';
-import { ReferencedSoftwareSystem, SoftwareSystem, SoftwareSystemDefinition } from './softwareSystem';
-import { Person, PersonDefinition, ReferencedPerson } from './person';
+import { SoftwareSystem, SoftwareSystemDefinition } from './softwareSystem';
+import { Person, PersonDefinition } from './person';
+export type CatalogKeyOf<TRoot, TModule> = {
+    [K in keyof TRoot]: TRoot[K] extends TModule ? K : never;
+}[keyof TRoot];
+export type Dependencies<TRoot, TModule> = Omit<TRoot, CatalogKeyOf<TRoot, TModule>>;
+export interface C4Module<TRoot, TLocal> {
+    readonly key: CatalogKeyOf<TRoot, TLocal>;
+    registerDefinitions(model: Model): TLocal;
+    buildRelationships(local: TLocal, dependencies: Dependencies<TRoot, TLocal>): void;
+}
 interface DefineSoftwareSystem {
     defineSoftwareSystem(name: string, definition?: SoftwareSystemDefinition): SoftwareSystem;
 }
 interface DefinePerson {
     definePerson(name: string, definition?: PersonDefinition): Person;
 }
-export declare class ModelGroup extends Group<SoftwareSystem | Person> implements DefineSoftwareSystem, DefinePerson {
+export declare class ModelGroup extends Group implements DefineSoftwareSystem, DefinePerson {
     readonly name: string;
     private readonly model;
     private softwareSystems;
@@ -26,15 +35,11 @@ export declare class Model {
     name: string;
     constructor(name: string);
     private softwareSystems;
-    private referencedSoftwareSystems;
     private people;
-    private referencedPeople;
     private groups;
     defineSoftwareSystem(name: string, definition?: SoftwareSystemDefinition): SoftwareSystem;
-    addGroup(groupName: string): Group<SoftwareSystem | Person> & ModelDefinitions;
-    referenceSoftwareSystem(name: string): ReferencedSoftwareSystem;
+    addGroup(groupName: string): Group & ModelDefinitions;
     definePerson(name: string, definition?: PersonDefinition): Person;
-    referencePerson(name: string): ReferencedPerson;
     validate(): void;
     getPeople(): ReadonlyArray<Person>;
     getSoftwareSystems(): ReadonlyArray<SoftwareSystem>;
@@ -42,5 +47,14 @@ export declare class Model {
     getSoftwareSystemsNotInGroups(): ReadonlyArray<SoftwareSystem>;
     getGroups(): ReadonlyArray<ModelGroup>;
 }
-export declare function buildModel(modelName: string, globPath?: string): Promise<Model>;
+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/{lib/model.js → model.js}

@@ -1,12 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildModel = exports.Model = exports.ModelGroup = void 0;
+exports.Model = exports.ModelGroup = void 0;
+exports.buildModelWithCatalog = buildModelWithCatalog;
+exports.buildModel = buildModel;
 const tslib_1 = require("tslib");
 const glob_1 = require("glob");
 const path_1 = require("path");
 const core_1 = require("./core");
 const softwareSystem_1 = require("./softwareSystem");
 const person_1 = require("./person");
+// TODO: This will be a Group of type <SoftwareSystem | Person> if that is added back in
 class ModelGroup extends core_1.Group {
     constructor(name, model) {
         super(name);
@@ -37,19 +40,18 @@ class Model {
     constructor(name) {
         this.name = name;
         this.softwareSystems = new Map();
-        this.referencedSoftwareSystems = new Map();
         this.people = new Map();
-        this.referencedPeople = new Map();
         this.groups = new Map();
     }
     defineSoftwareSystem(name, definition) {
         if (this.softwareSystems.has(name)) {
-            throw Error(`A SoftwareSystem named '${name}' is defined elsewhere in this Model. A SoftwareSystem can be defined only once, but can be referenced multiple times.`);
+            throw Error(`A SoftwareSystem named '${name}' is defined elsewhere in this Model. A SoftwareSystem can be defined only once.`);
         }
         const system = new softwareSystem_1.SoftwareSystem(name, definition);
         this.softwareSystems.set(name, system);
         return system;
     }
+    // TODO:Should be a Group<SoftwareSystem | Person> if that is added back in
     addGroup(groupName) {
         let group = this.groups.get(groupName);
         if (!group) {
@@ -58,46 +60,15 @@ class Model {
         }
         return group;
     }
-    referenceSoftwareSystem(name) {
-        let system = this.referencedSoftwareSystems.get(name);
-        if (!system) {
-            system = new softwareSystem_1.ReferencedSoftwareSystem(name);
-            this.referencedSoftwareSystems.set(name, system);
-        }
-        return system;
-    }
     definePerson(name, definition) {
         if (this.people.has(name)) {
-            throw Error(`A Person named '${name}' is defined elsewhere in this Model. A Person can be defined only once, but can be referenced multiple times.`);
+            throw Error(`A Person named '${name}' is defined elsewhere in this Model. A Person can be defined only once.`);
         }
         const person = new person_1.Person(name, definition);
         this.people.set(name, person);
         return person;
     }
-    referencePerson(name) {
-        let person = this.referencedPeople.get(name);
-        if (!person) {
-            person = new person_1.ReferencedPerson(name);
-            this.referencedPeople.set(name, person);
-        }
-        return person;
-    }
-    validate() {
-        const undefinedSoftwareSystems = Array.from(this.referencedSoftwareSystems.keys()).filter(name => !this.softwareSystems.has(name));
-        if (undefinedSoftwareSystems.length > 0) {
-            throw Error(`SoftwareSystems named '${undefinedSoftwareSystems.join("', '")}' are referenced but not defined.`);
-        }
-        const undefinedPeople = Array.from(this.referencedPeople.keys()).filter(name => !this.people.has(name));
-        if (undefinedPeople.length > 0) {
-            throw Error(`People named '${undefinedPeople.join("', '")}' are referenced but not defined.`);
-        }
-        const definedElements = Array.from(this.softwareSystems.values()).flatMap(system => system.getChildElementNames());
-        const referencedElements = Array.from(this.referencedSoftwareSystems.values()).flatMap(system => system.getChildElementNames());
-        const undefinedElements = referencedElements.filter(name => !definedElements.includes(name));
-        if (undefinedElements.length > 0) {
-            throw Error(`Elements named '${undefinedElements.join("', '")}' are referenced but not defined.`);
-        }
-    }
+    validate() { }
     getPeople() {
         return Array.from(this.people.values());
     }
@@ -105,39 +76,53 @@ class Model {
         return Array.from(this.softwareSystems.values());
     }
     getPeopleNotInGroups() {
-        const peopleInGroups = Array.from(this.groups.values()).flatMap(group => group.getPeople());
-        return Array.from(this.people.values()).filter(person => !peopleInGroups.includes(person));
+        const peopleInGroups = Array.from(this.groups.values()).flatMap((group) => group.getPeople());
+        return Array.from(this.people.values()).filter((person) => !peopleInGroups.includes(person));
     }
     getSoftwareSystemsNotInGroups() {
-        const systemsInGroups = Array.from(this.groups.values()).flatMap(group => group.getSoftwareSystems());
-        return Array.from(this.softwareSystems.values()).filter(system => !systemsInGroups.includes(system));
+        const systemsInGroups = Array.from(this.groups.values()).flatMap((group) => group.getSoftwareSystems());
+        return Array.from(this.softwareSystems.values()).filter((system) => !systemsInGroups.includes(system));
     }
     getGroups() {
         return Array.from(this.groups.values());
     }
 }
 exports.Model = Model;
-function buildModel(modelName, globPath = 'c4.dsl.ts') {
-    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+function buildModelWithCatalog() {
+    return tslib_1.__awaiter(this, arguments, void 0, function* (options = {}) {
+        const { modelName = 'model', globPath = 'c4.dsl.ts', searchRoot = __dirname } = options;
         const model = new Model(modelName);
-        const result = yield (0, glob_1.glob)(`**/${globPath}`, { cwd: __dirname });
+        const result = yield (0, glob_1.glob)(`**/${globPath}`, { cwd: searchRoot });
         if (result.length === 0) {
             throw new Error(`No ${globPath} files found`);
         }
-        for (const file of result) {
-            const moduleFile = (0, path_1.join)(__dirname, file);
-            console.log(`Accumulating model from ${moduleFile}`);
-            const module = yield Promise.resolve(`${moduleFile}`).then(s => require(s));
-            if (typeof module.buildModel === 'function') {
-                module.buildModel(model);
-            }
-            else {
-                console.log(`${file} does not contain the method 'buildModel'`);
+        const modules = yield Promise.all(result.map((file) => Promise.resolve(`${(0, path_1.join)(searchRoot, file)}`).then(s => require(s))));
+        const registrations = [];
+        const rootCatalog = {};
+        // Phase 1: each module registers its own definitions; results are nested under the module's key
+        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`);
         }
-        model.validate();
-        return model;
+        // Phase 2: each module receives its own slice (local) and every other module's slice (dependencies) to build relationships
+        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 };
+    });
+}
+function buildModel() {
+    return tslib_1.__awaiter(this, arguments, void 0, function* (options = {}) {
+        return (yield buildModelWithCatalog(options)).model;
     });
 }
-exports.buildModel = buildModel;
 //# sourceMappingURL=model.js.map