# mod-construction/mod-dlm architecture

> Architecture diagram of the GitHub repository mod-construction/mod-dlm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mod-construction/mod-dlm
- Repository: https://github.com/mod-construction/mod-dlm

## Overview

##### Project Type and Purpose
- This is an open-source Domain-Specific Language (DSL) library and code-generation tool (“mod-dlm”) written in TypeScript.
- Its purpose is to let AEC-industry users describe prefab building elements via a schema, then automatically generate:
- RESTful CRUD APIs (OpenAPI/Redocly docs)
- Client libraries (TypeScript-Fetch, Python, Java/Spring, Go, etc.)
- Server stubs (e.g. FastAPI)
- It ships as an npm package, plus generator configurations, mustache templates, and GitHub Actions workflows to produce language-specific SDKs and docs.

##### File-Structure Analysis
- src/
- index.ts – public entry point & CLI-style invocation
- createApiDocs.ts – generate OpenAPI specs & HTML docs (uses Redocly)
- types/ – Zod/TypeScript schemas for DSL (common, entities, API types)
- utils/ – helper functions for file I/O, templating, config loading
- generator-configs/ – YAML configurations per generator (python-fastapi, spring, typescript-fetch) plus mustache template directories
- openapi/ + openapitools.json – OpenAPI Generator configuration
- template/apidoc.html – custom HTML template for API docs
- package.json, tsconfig.json – build scripts, dependencies
- .github/workflows – CI to generate docs, clients, servers, publish to npm/PyPI/GitHub Packages

##### Key README Insights
- Features: DSL definitions → automatic CRUD API generation → multi-language support
- Usage examples show importing the library in a TS project and validating DSL instances

##### Main Components & Their Interactions
A. Developer Interface
- CLI or programmatic API (index.ts)
- Accepts DSL definitions (JS/TS objects or external YAML)
B. DSL Module
- Zod-based schemas (src/types) define PrefabElement and sub-schemas
- Validation logic
C. Code-Generation Engine
- Loads generator-config YAML (generator-configs/)
- Invokes Mustache template renderer against DSL AST/JSON
- Outputs language-specific code (clients, servers)
D. OpenAPI/Docs Generator
- createApiDocs.ts uses the DSL schema + OpenAPI generator config
- Produces OpenAPI JSON/YAML, then HTML via Redocly/template/apidoc.html
E. Configuration & Templates
- generator-config files guide codegen (package names, file paths, etc.)
- Mustache templates for each target language
F. CI/CD Workflows
- GitHub Actions trigger generation, testing, publishing to npm/PyPI
G. Output Artifacts
- npm package (@mod-construction/mod-dlm)
- Python package (mod-dlm-server)
- Generated client SDKs & server stubs in respective languages
- Hosted API docs

##### Architectural Patterns & Principles
- Plugin/Template-Driven Architecture: decouples core engine from language targets
- Single Responsibility: separate modules for parsing, templating, docs, utils
- Layered Flow:
1. Input (DSL definitions) →
2. Validation (Zod schemas) →
3. Transformation (JSON/AST) →
4. Codegen (Mustache + generator-configs) →
5. Artifact output (files, docs)
- Config-over-Code: behavior driven by YAML + templates

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Interface
    Dev["Developer / CLI"]:::internal
    click Dev "https://github.com/mod-construction/mod-dlm/blob/main/src/index.ts"

    %% Core DSL Module
    subgraph "Core DSL Module"
        direction TB
        Schemas(("Zod Schemas (src/types)")):::cylinder
        click Schemas "https://github.com/mod-construction/mod-dlm/tree/main/src/types"
        Common(("Common Schemas")):::cylinder
        click Common "https://github.com/mod-construction/mod-dlm/tree/main/src/types/common"
        Entities(("Entity Schemas")):::cylinder
        click Entities "https://github.com/mod-construction/mod-dlm/tree/main/src/types/entities"
        APItypes(("API Types")):::cylinder
        click APItypes "https://github.com/mod-construction/mod-dlm/tree/main/src/types/api"
    end

    %% Code-Generation Engine
    Engine["Code-Generation Engine"]:::internal
    Utils["Engine Helpers (utils)"]:::internal
    click Utils "https://github.com/mod-construction/mod-dlm/blob/main/src/utils/utils.ts"

    %% Generator Configs + Templates
    subgraph "Generator Configs + Mustache Templates"
        direction TB
        Configs(("Generator Configurations")):::cylinder
        click Configs "https://github.com/mod-construction/mod-dlm/tree/main/generator-configs"
        PyCfg(("Python FastAPI Config")):::cylinder
        click PyCfg "https://github.com/mod-construction/mod-dlm/blob/main/generator-configs/python-fastapi-generator-config.yml"
        SpringCfg(("Spring Config")):::cylinder
        click SpringCfg "https://github.com/mod-construction/mod-dlm/blob/main/generator-configs/spring-generator-config.yml"
        TSFetchCfg(("TypeScript-Fetch Config")):::cylinder
        click TSFetchCfg "https://github.com/mod-construction/mod-dlm/blob/main/generator-configs/typescript-fetch-generator-config.yml"
        Templates{{"Mustache Templates"}}:::document
        click Templates "https://github.com/mod-construction/mod-dlm/tree/main/generator-configs/template"
        FastApiTpl(("FastAPI Templates")):::document
        click FastApiTpl "https://github.com/mod-construction/mod-dlm/tree/main/generator-configs/template/fastapi"
        SpringTpl(("Spring Templates")):::document
        click SpringTpl "https://github.com/mod-construction/mod-dlm/tree/main/generator-configs/template/spring"
    end

    %% OpenAPI & Docs Generator
    Docs["OpenAPI & Docs Generator"]:::internal
    click Docs "https://github.com/mod-construction/mod-dlm/blob/main/src/createApiDocs.ts"
    OpenApiCfg(("OpenAPI Generator Configuration")):::cylinder
    click OpenApiCfg "https://github.com/mod-construction/mod-dlm/blob/main/openapi/openapitools.json"
    ApiDocTpl{{"API Docs Template"}}:::document
    click ApiDocTpl "https://github.com/mod-construction/mod-dlm/blob/main/template/apidoc.html"

    %% Output Artifacts
    subgraph "Output Artifacts"
        direction TB
        Npm["npm Package (@mod-construction/mod-dlm)"]:::output
        PyPkg["Python Package (mod-dlm-server)"]:::output
        SDKs["Generated Client SDKs & Server Stubs"]:::output
        DocsOut["Hosted API Docs"]:::output
    end

    %% CI/CD Workflows
    subgraph "CI/CD (GitHub Actions)"
        direction TB
        CI["Workflow Orchestration"]:::internal
        ADocWF["API Docs Workflow"]:::internal
        click ADocWF "https://github.com/mod-construction/mod-dlm/blob/main/.github/workflows/apidoc.yml"
        GenClientWF["Client Generation Workflow"]:::internal
        click GenClientWF "https://github.com/mod-construction/mod-dlm/blob/main/.github/workflows/generateClients.yml"
        GenServerWF["Server Generation Workflow"]:::internal
        click GenServerWF "https://github.com/mod-construction/mod-dlm/blob/main/.github/workflows/generateServers.yml"
        PublishWF["Publish Workflow"]:::internal
        click PublishWF "https://github.com/mod-construction/mod-dlm/blob/main/.github/workflows/publish.yml"
        ReleaseWF["Release Workflow"]:::internal
        click ReleaseWF "https://github.com/mod-construction/mod-dlm/blob/main/.github/workflows/release.yml"
    end

    %% Relationships
    Dev -->|provides DSL| Schemas
    Schemas -->|validated AST| Engine
    Utils -->|helpers| Engine
    Engine -->|loads configs| Configs
    PyCfg -->|feeds| Engine
    SpringCfg -->|feeds| Engine
    TSFetchCfg -->|feeds| Engine
    Templates -->|used by| Engine
    FastApiTpl -->|used by| Engine
    SpringTpl -->|used by| Engine
    Engine -->|generates code| Npm
    Engine -->|generates code| PyPkg
    Engine -->|generates code| SDKs

    Schemas -->|schema definitions| Docs
    OpenApiCfg -->|configures| Docs
    ApiDocTpl -->|template| Docs
    Docs -->|generates| DocsOut

    CI -->|triggers| Engine
    CI -->|triggers| Docs
    ADocWF -->|invokes| Docs
    GenClientWF -->|invokes| Engine
    GenServerWF -->|invokes| Engine
    PublishWF -->|publishes| Npm
    PublishWF -->|publishes| PyPkg
    ReleaseWF -->|releases| SDKs
    ReleaseWF -->|releases| DocsOut

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef cylinder fill:#ADD8E6,stroke:#000,stroke-width:1px,shape:cylinder
    classDef document fill:#ADD8E6,stroke:#000,stroke-width:1px,shape:rect
    classDef output fill:#FFD580,stroke:#000,stroke-width:1px
```
