# sitandr/conchord architecture

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

- Interactive diagram: https://gitdiagram.com/sitandr/conchord
- Repository: https://github.com/sitandr/conchord

## Overview

##### Project’s Nature
- Conchord is a Typst package aimed at string-instrument chord generation and rendering.
- It leverages a WebAssembly (WASM) module to generate chord tab strings and uses multiple modules to render chords and tabs.

##### Major Components
- Core Library Module: File “lib.typ” acts as the central entry point that aggregates and exposes functionality.
- Chord Generation Module:
– Files in the “gen” directory (e.g., “gen/gen.typ” and “gen/conchord_gen.wasm”) implement the WASM-based music theory engine that generates chord tab strings.
– Functions like get-chords, n-best, and get-chord are part of this module.
- Chord Rendering Module:
– This includes the “smart-chord” function and related chordgen functions.
- Tabs Rendering Module:
– Located in the “tabs” directory (with files such as “tabs/drawing.typ”, “tabs/gen.typ”, “tabs/tabs.typ”), this module implements the DSL for rendering tablature.
– It supports various features like duration, bars, ties, slides, bends, vibratos, and even custom content.
- Reference & Documentation:
– The “reference” directory holds documentation (e.g., “reference/reference.typ” and “reference/reference.pdf”) that details the API and chord naming rules.
- Examples:
– The “examples” folder contains numerous Typst example scripts, which illustrate how to use chord generation, chord drawing, tab features, and even integration of chord libraries within complete song documents.

##### Relationships/Interactions
- User Code (written in Typst using Conchord) invokes high-level functions (e.g., smart-chord, new-chordgen, overchord) from the Core Library.
- When a chord needs to be generated, the call flows from a rendering function (such as smart-chord) to the chord generation functions (get-chords) in the Gen module.
- The Gen module sends data to the WASM engine (“conchord_gen.wasm”), which returns all possible chord variants.
- A parallel flow exists for handling tablature where user-written tab strings are parsed by the Tabs module and rendered accordingly.
- Reference documentation supports developers by explaining naming conventions and low-level design choices.

##### Architectural Patterns & Technologies
- Modular Structure – Each major functional area is separated into its own directory, promoting separation of concerns.
- WASM Integration – Use of the WASM engine for runtime chord generation adds an additional layer external to the typical Typst rendering process.
- Extensibility – The package is designed so that users can either use built-in functions (e.g., smart-chord) or create custom chord rendering (using new-chordgen).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Nodes
    U["User DSL Code"]:::user
    CL["Core Library"]:::core

    subgraph "Chord Generation Module"
        CGT["Typ Interface"]:::gen
        WE(("WASM Engine")):::wasm
    end

    subgraph "Chord Rendering Module"
        CR1["Draw Chord"]:::render
        CR2["Sheet"]:::render
        CR3["Smart Chord"]:::render
    end

    subgraph "Tabs Rendering Module"
        TD["Drawing"]:::tabs
        TG["Gen"]:::tabs
        TT["Tabs"]:::tabs
    end

    D["Documentation"]:::doc
    E["Examples"]:::doc

    %% Relationships
    U -->|"invokes"| CL
    CL -->|"calls"| CGT
    CGT -->|"sendsDataTo"| WE
    WE -->|"returnsChordsTo"| CR3
    CGT -->|"sendsChordsTo"| CR1
    CGT -->|"sendsChordsTo"| CR2
    CL -->|"calls"| CR1
    CL -->|"calls"| CR2
    CL -->|"calls"| CR3
    CL -->|"triggers"| TD
    CL -->|"triggers"| TG
    CL -->|"triggers"| TT
    CL -->|"providesInfo"| D
    CL -->|"providesInfo"| E
    U -->|"providesDSLInput"| TD

    %% Styles
    classDef user fill:#ffccff,stroke:#333,stroke-width:2px;
    classDef core fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef gen fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef wasm fill:#e2f0d9,stroke:#333,stroke-width:2px,stroke-dasharray: 5, 5;
    classDef render fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef tabs fill:#d1ecf1,stroke:#333,stroke-width:2px;
    classDef doc fill:#fff3cd,stroke:#333,stroke-width:2px;

    %% Click Events
    click CL "https://github.com/sitandr/conchord/blob/main/lib.typ"
    click CGT "https://github.com/sitandr/conchord/blob/main/gen/gen.typ"
    click WE "https://github.com/sitandr/conchord/blob/main/gen/conchord_gen.wasm"
    click CR1 "https://github.com/sitandr/conchord/blob/main/chords/draw-chord.typ"
    click CR2 "https://github.com/sitandr/conchord/blob/main/chords/sheet.typ"
    click CR3 "https://github.com/sitandr/conchord/blob/main/chords/smart-chord.typ"
    click TD "https://github.com/sitandr/conchord/blob/main/tabs/drawing.typ"
    click TG "https://github.com/sitandr/conchord/blob/main/tabs/gen.typ"
    click TT "https://github.com/sitandr/conchord/blob/main/tabs/tabs.typ"
    click D "https://github.com/sitandr/conchord/blob/main/reference/reference.typ"
    click E "https://github.com/sitandr/conchord/tree/main/examples"
```
