# ajalt/mordant architecture

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

- Interactive diagram: https://gitdiagram.com/ajalt/mordant
- Repository: https://github.com/ajalt/mordant

## Overview

This project is a Kotlin multiplatform library called Mordant, whose purpose is to provide a comprehensive set of tools for rendering styled text in terminal environments. It includes ANSI colorful output, Markdown rendering, terminal widgets (such as tables, panels, animations, etc.), and even extensions for coroutine-based animations. The source tree shows that the project is highly modular, with several submodules (for different platforms and functionalities), a dedicated build configuration (using Gradle with Kotlin DSL), build convention scripts in buildSrc, extensive tests, samples, and CI/CD configurations.

##### Main Components
- Build and Infrastructure Layer:
- The Gradle build system (build.gradle.kts, gradle.properties, settings.gradle.kts) and the buildSrc folder, which contains convention scripts and custom Gradle configuration files.
- CI/CD workflows located in the .github/workflows directory, as well as auxiliary files like mkdocs.yml (documentation) and scripts (for generating tables, etc.).
- Core Library Modules:
- The primary library module “mordant”, which contains the multiplatform core code (organized into commonMain, jvmMain, iosMain, jsMain, nativeMain, etc.).
- Other submodules such as “mordant-coroutines”, “mordant-markdown”, “mordant-omnibus”, and various JVM-specific modules (mordant-jvm-ffm, mordant-jvm-graal-ffi, mordant-jvm-jna) – each implemented as separate Gradle projects with their own source sets.
- Platform-Specific Implementations:
- Within the “mordant” and other modules, note the division into source sets for different targets (jvmMain, iosMain, jsMain, linuxMain, macosMain, mingwMain, and more). These represent the platform-specific implementations or adaptations.
- API and Internal Layers:
- Each module generally contains an API definition (often in an “api” directory) and the implementation. You may want to display this as a separation between public interfaces and platform-specific or internal implementations.
- Sample Applications and Tests:
- The “samples” folder contains various demonstrator projects (detection, drawing, hexviewer, markdown, progress, select, table, tour) that illustrate how to use the library.
- The “test” folder (and tests within each module) highlight the testing infrastructure, including specific CI tests for GraalVM and Proguard.

##### Relationships and Interactions
- For example, the samples depend on the libraries (mordant and its extensions).
- Platform-specific source sets inherit from commonMain, indicating the flow of cross-platform code to specific implementations.
- The build system and CI/CD configuration drive the entire build and deployment process.
- That several modules share a common API and are interrelated by naming conventions; for instance, “mordant-coroutines” and “mordant-markdown” extend the functionality of the core module.

##### Architectural Patterns and Design Principles
- Modularity: The project cleanly separates concerns across multiple Gradle subprojects and source sets (common vs. platform-specific).
- Multiplatform Strategy: The use of numerous source sets under each module illustrates how shared (commonMain) code interacts with platform-specific implementations.
- Layer Separation: Distinguish between the public API (the exported API files) and the internal implementation details, such as rendering, input handling, and terminal abstractions.
- Extensibility: Additional functionalities (like animations and Markdown rendering) are separated into their own modules, making the library extensible.

##### Relevant Technologies and Tools
- Kotlin Multiplatform tools, Gradle (with Kotlin DSL), and GitHub Actions for CI/CD.
- Mention the use of external repositories (e.g., Maven Central, Sonatype for snapshots) and tools for documentation (MkDocs).

- Build infrastructure (e.g., Gradle scripts, CI/CD configurations),
- Core modules (shared code),
- Platform-specific modules,
- Samples and tests.
- Optionally, include details such as API vs. internal implementations inside the modules if desired.

##### Final Assembly
- Next, illustrate the core library modules along with their shared common code and platform splits.
- Extension modules that further enhance functionalities (e.g., Markdown, coroutines).

## Diagram (Mermaid)

```mermaid
graph TB
    %% Build & Infrastructure Subgraph
    subgraph "Build & Infrastructure"
        B1["Build.gradle.kts"]:::build
        B2["Gradle.properties"]:::build
        B3["Settings.gradle.kts"]:::build
        B4["buildSrc"]:::build
        B5["buildSrc Conventions"]:::build
        C1["Workflow: build.yml"]:::build
        C2["Workflow: gradle-wrapper-validation.yml"]:::build
        C3["Workflow: release.yml"]:::build
        D1["MkDocs Configuration"]:::build
        D2["Script: generate_cellwidth_table.py"]:::build
        D3["Script: generate_emoji_sequence_table.py"]:::build
    end

    %% Core Modules Subgraph
    subgraph "Core Modules"
        M1["mordant API"]:::core
        M2["mordant Source Sets (commonMain, jvmMain, iosMain, etc.)"]:::core
    end

    %% Extensions Subgraph
    subgraph "Extensions"
        E1["mordant-coroutines API"]:::extension
        E2["mordant-coroutines Source Sets (commonMain)"]:::extension
        E3["mordant-markdown API"]:::extension
        E4["mordant-markdown Source Sets (commonMain)"]:::extension
        E5["mordant-omnibus API"]:::extension
        E6["mordant-omnibus Source Sets (commonMain)"]:::extension
        E7["mordant-jvm-ffm API"]:::extension
        E8["mordant-jvm-ffm Source Sets (jvmMain)"]:::extension
        E9["mordant-jvm-graal-ffi API"]:::extension
        E10["mordant-jvm-graal-ffi Source Sets (jvmMain)"]:::extension
        E11["mordant-jvm-jna API"]:::extension
        E12["mordant-jvm-jna Source Sets (jvmMain)"]:::extension
    end

    %% Samples & Tests Subgraph
    subgraph "Samples & Tests"
        S1["Samples"]:::sample
        T1["Tests"]:::sample
        T2["GraalVM Tests"]:::sample
        T3["Proguard Tests"]:::sample
    end

    %% Connections from Build & Infrastructure to Core Modules
    B1 -->|"builds"| M1
    B2 -->|"builds"| M1
    B3 -->|"builds"| M1
    B4 -->|"configures"| M1
    B5 -->|"configures"| M1

    C1 -->|"triggers"| M1
    C2 -->|"triggers"| M1
    C3 -->|"triggers"| M1

    D1 -->|"supports"| M1
    D2 -->|"supports"| M1
    D3 -->|"supports"| M1

    %% Internal structure of Core Modules
    M1 -->|"implements"| M2

    %% Core Modules extend functionality to Extensions
    M1 -->|"extends"| E1
    M1 -->|"extends"| E3
    M1 -->|"extends"| E5
    M1 -->|"extends"| E7
    M1 -->|"extends"| E9
    M1 -->|"extends"| E11

    %% Each Extension module: API provides implementation in Source Sets
    E1 -->|"provides"| E2
    E3 -->|"provides"| E4
    E5 -->|"provides"| E6
    E7 -->|"provides"| E8
    E9 -->|"provides"| E10
    E11 -->|"provides"| E12

    %% Samples & Tests depend on Core and Extensions
    M1 -->|"usedBy"| S1
    E1 -->|"usedBy"| S1
    E3 -->|"usedBy"| S1
    E5 -->|"usedBy"| S1
    E7 -->|"usedBy"| S1
    E9 -->|"usedBy"| S1
    E11 -->|"usedBy"| S1

    M1 -->|"testedBy"| T1
    E1 -->|"testedBy"| T1
    E3 -->|"testedBy"| T1
    E5 -->|"testedBy"| T1

    T1 -->|"includes"| T2
    T1 -->|"includes"| T3

    %% Styles
    classDef build fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef core fill:#cce5ff,stroke:#003366,stroke-width:2px;
    classDef extension fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef sample fill:#fff2cc,stroke:#996600,stroke-width:2px;

    %% Click Events for Build & Infrastructure
    click B1 "https://github.com/ajalt/mordant/blob/master/build.gradle.kts"
    click B2 "https://github.com/ajalt/mordant/blob/master/gradle.properties"
    click B3 "https://github.com/ajalt/mordant/blob/master/settings.gradle.kts"
    click B4 "https://github.com/ajalt/mordant/tree/master/buildSrc/"
    click B5 "https://github.com/ajalt/mordant/blob/master/buildSrc/src/main/kotlin/mordant-mpp-conventions.gradle.kts"
    click C1 "https://github.com/ajalt/mordant/blob/master/.github/workflows/build.yml"
    click C2 "https://github.com/ajalt/mordant/blob/master/.github/workflows/gradle-wrapper-validation.yml"
    click C3 "https://github.com/ajalt/mordant/blob/master/.github/workflows/release.yml"
    click D1 "https://github.com/ajalt/mordant/blob/master/mkdocs.yml"
    click D2 "https://github.com/ajalt/mordant/blob/master/scripts/generate_cellwidth_table.py"
    click D3 "https://github.com/ajalt/mordant/blob/master/scripts/generate_emoji_sequence_table.py"

    %% Click Events for Core Modules
    click M1 "https://github.com/ajalt/mordant/blob/master/mordant/api/mordant.api"
    click M2 "https://github.com/ajalt/mordant/tree/master/mordant/src/commonMain"

    %% Click Events for Extensions
    click E1 "https://github.com/ajalt/mordant/blob/master/mordant-coroutines/api/mordant-coroutines.api"
    click E2 "https://github.com/ajalt/mordant/tree/master/mordant-coroutines/src/commonMain"
    click E3 "https://github.com/ajalt/mordant/blob/master/mordant-markdown/api/mordant-markdown.api"
    click E4 "https://github.com/ajalt/mordant/tree/master/mordant-markdown/src/commonMain"
    click E5 "https://github.com/ajalt/mordant/blob/master/mordant-omnibus/api/mordant-omnibus.api"
    click E6 "https://github.com/ajalt/mordant/tree/master/mordant-omnibus/src/commonMain"
    click E7 "https://github.com/ajalt/mordant/blob/master/mordant-jvm-ffm/api/mordant-jvm-ffm.api"
    click E8 "https://github.com/ajalt/mordant/tree/master/mordant-jvm-ffm/src/jvmMain"
    click E9 "https://github.com/ajalt/mordant/blob/master/mordant-jvm-graal-ffi/api/mordant-jvm-graal-ffi.api"
    click E10 "https://github.com/ajalt/mordant/tree/master/mordant-jvm-graal-ffi/src/jvmMain"
    click E11 "https://github.com/ajalt/mordant/blob/master/mordant-jvm-jna/api/mordant-jvm-jna.api"
    click E12 "https://github.com/ajalt/mordant/tree/master/mordant-jvm-jna/src/jvmMain"

    %% Click Events for Samples & Tests
    click S1 "https://github.com/ajalt/mordant/tree/master/samples/"
    click T1 "https://github.com/ajalt/mordant/tree/master/test/"
    click T2 "https://github.com/ajalt/mordant/tree/master/test/graalvm"
    click T3 "https://github.com/ajalt/mordant/tree/master/test/proguard"
```
