glam/MERMAID_GENERATORS_EXPLAINED.md

# Mermaid Diagram Generators - Source and Purpose

## Your Questions Answered

### Q1: Were these solely generated by the LinkML repo?

**NO** - You have **TWO sources**:

| File Type | Generator | Source |
|-----------|-----------|--------|
| 21 × `.md` files | `gen-mermaid-class-diagram` | ✅ **LinkML official** (from LinkML repo) |
| 1 × `.mmd` file (working) | `owl_to_mermaid.py` | ❌ **Custom script** (local project) |
| 1 × `.mmd` ER diagram | `gen-erdiagram` | ✅ **LinkML official** (from LinkML repo) |

**Details**:

1. **LinkML Official Generators** (installed via `pip install linkml`):
   - `gen-mermaid-class-diagram` → Creates 21 `.md` files (one per class)
   - `gen-erdiagram` → Creates 1 `.mmd` ER diagram (all classes)

2. **Custom Project Script** (in `scripts/owl_to_mermaid.py`):
   - Parses OWL/Turtle RDF
   - Generates single `.mmd` file with all classes
   - **Workaround** for when LinkML generators don't meet specific needs

---

### Q2: Which represents the total ontology overview?

**Answer**: The **Entity-Relationship Diagram** is the total overview:

```
schemas/20251121/uml/erdiagram/custodian_multi_aspect_20251122_171249.mmd
```

**Why this is the "total ontology overview"**:
- ✅ Shows **ALL 35 classes** in one diagram
- ✅ Shows **ALL properties** for each class
- ✅ Shows **relationships** between classes
- ✅ Generated directly from `01_custodian_name_modular.yaml`
- ✅ **Single comprehensive view** (not 21 separate files)

**Generated by**: `gen-erdiagram -f mermaid 01_custodian_name_modular.yaml`

---

## Complete Breakdown

### Source: `01_custodian_name_modular.yaml`

This schema file generates **THREE types** of Mermaid outputs:

#### 1. ER Diagram ✅ **TOTAL ONTOLOGY OVERVIEW**

**Generator**: `gen-erdiagram -f mermaid` (LinkML official)

**Output**: Single comprehensive diagram
```
schemas/20251121/uml/erdiagram/custodian_multi_aspect_20251122_171249.mmd
```

**Size**: 8KB, 173 lines, 35 classes

**What it shows**:
- All classes as entities
- All properties per class
- Relationships between classes
- Property types (date, string, etc.)

**Example content**:
```mermaid
erDiagram
Custodian {
    uriorcurie hc_id  
    datetime created  
    datetime modified  
}
CustodianLegalStatus {
    date dissolution_date  
    string reconstruction_method  
}
... (33 more classes)
```

**Use case**: **This is your "total ontology overview"** - open this in Mermaid Live Editor or GitHub to see everything at once.

---

#### 2. Individual Class Diagrams (21 × `.md` files)

**Generator**: `gen-mermaid-class-diagram -d output_dir` (LinkML official)

**Output**: 21 Markdown files with embedded Mermaid diagrams
```
schemas/20251121/uml/mermaid/Custodian.md
schemas/20251121/uml/mermaid/CustodianLegalStatus.md
schemas/20251121/uml/mermaid/CustodianName.md
... (18 more)
```

**What it shows**:
- One class per file
- Properties for that class
- Relationships to OTHER classes (with clickable links)
- Cardinality (0..1, 1, *, etc.)

**Example content** (`Custodian.md`):
```markdown
```mermaid
 classDiagram
    class Custodian
      Custodian : hc_id
      Custodian : created
      Custodian : modified
      Custodian --> "*" CustodianAppellation : appellations
      Custodian --> "0..1" CustodianLegalStatus : legal_status
` ``
```

**Use case**: **Interactive exploration** - click between related classes, focus on one class at a time. Best for GitHub documentation.

---

#### 3. Comprehensive Class Diagram (1 × `.mmd` file) ⚠️ Custom

**Generator**: `owl_to_mermaid.py` (custom script, NOT LinkML)

**Output**: Single `.mmd` file with all classes
```
schemas/20251121/uml/mermaid/custodian_multi_aspect_20251122_155319.mmd
```

**Size**: 1.6KB

**What it shows**:
- All classes in `classDiagram` syntax (NOT ER diagram)
- Inheritance relationships (subClassOf)
- **No properties** (class names only)

**Example content**:
```mermaid
classDiagram
    class Custodian {
    }
    class CustodianLegalStatus {
    }
    ... (35 classes with inheritance arrows)
```

**Use case**: Quick overview of class hierarchy. Less detailed than ER diagram.

**Note**: Recent runs produced empty files (0 bytes) - only the 155319 timestamp works.

---

## Comparison Table

| Diagram Type | Generator | Source | Classes | Properties | Relationships | File Count | Total Overview? |
|--------------|-----------|--------|---------|------------|---------------|------------|-----------------|
| **ER Diagram** | `gen-erdiagram` | LinkML | 35 | ✅ All | ✅ Yes | 1 | ✅ **YES** |
| Individual `.md` | `gen-mermaid-class-diagram` | LinkML | 1 per file | ✅ Per class | ✅ Yes | 21 | ❌ No (fragmented) |
| Comprehensive `.mmd` | `owl_to_mermaid.py` | Custom | 35 | ❌ No | ✅ Inheritance | 1 | ⚠️ Partial (no properties) |

---

## Recommended Usage

### For "Total Ontology Overview" → Use ER Diagram

```bash
# View in Mermaid Live Editor
cat schemas/20251121/uml/erdiagram/custodian_multi_aspect_20251122_171249.mmd

# Copy content to: https://mermaid.live

# Or push to GitHub and view in browser (auto-renders)
```

**This is the definitive "total ontology overview"** because:
- ✅ Shows ALL classes
- ✅ Shows ALL properties
- ✅ Shows ALL relationships
- ✅ Single file, comprehensive view

---

### For Interactive Exploration → Use Individual `.md` Files

```bash
# Navigate class by class
cat schemas/20251121/uml/mermaid/index_20251122_171316.md

# Open in VS Code or GitHub
code schemas/20251121/uml/mermaid/Custodian.md
```

**Best for**:
- GitHub documentation
- Clicking between related classes
- Focus on one class at a time

---

## Generation Commands (for Reference)

### 1. Generate ER Diagram (Total Overview)

```bash
cd schemas/20251121/linkml
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

gen-erdiagram -f mermaid 01_custodian_name_modular.yaml \
  > ../uml/erdiagram/custodian_multi_aspect_${TIMESTAMP}.mmd
```

**Output**: `custodian_multi_aspect_20251122_171249.mmd` (8KB)

---

### 2. Generate Individual Class Diagrams

```bash
cd schemas/20251121/linkml

gen-mermaid-class-diagram -d ../uml/mermaid 01_custodian_name_modular.yaml
```

**Output**: 21 `.md` files in `../uml/mermaid/` (overwrites existing)

---

### 3. Generate Comprehensive Class Diagram (Custom)

```bash
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

python3 scripts/owl_to_mermaid.py \
  schemas/20251121/rdf/custodian_multi_aspect_20251122_155319.owl.ttl \
  schemas/20251121/uml/mermaid/custodian_multi_aspect_${TIMESTAMP}.mmd
```

**Output**: Single `.mmd` file (class names + inheritance only)

---

## Summary

**Q1: Were these solely generated by the LinkML repo?**

**A1**: NO - You have:
- ✅ LinkML official: `gen-mermaid-class-diagram` (21 `.md` files) + `gen-erdiagram` (1 ER `.mmd`)
- ❌ Custom script: `owl_to_mermaid.py` (1 comprehensive `.mmd`)

**Q2: Which represents the total ontology overview?**

**A2**: **The ER Diagram** at:
```
schemas/20251121/uml/erdiagram/custodian_multi_aspect_20251122_171249.mmd
```

This is the **definitive total overview** showing all 35 classes with properties and relationships in a single diagram.

---

**Key Takeaway**: Use the **ER diagram** for total overview, use the **21 `.md` files** for interactive exploration.