# cairnepal/hg-skill architecture

> Architecture diagram of the GitHub repository cairnepal/hg-skill, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cairnepal/hg-skill
- Repository: https://github.com/cairnepal/hg-skill

## Overview

HeritageGraph Skills turns heritage documents, text, and tabular records into ontology-grounded RDF Turtle. Users ingest and preprocess data, extract and validate a LinkML Container, resolve entity URIs (optionally with curator review), map resolved records to RDF, then run SHACL validation. The README documents this staged workflow and run artifacts; sampled code shows selected ingestion, scanning, validation, resolution, mapping, and workspace behavior. The pipeline runner and SHACL validator are listed but unsampled, so their internal calls are not inferred.

Main entry points: [`skills/common/run_workspace.py`](https://github.com/cairnepal/hg-skill/blob/main/skills/common/run_workspace.py) (Run Workspace), [`schemas/HeritageGraph.shacl.ttl`](https://github.com/cairnepal/hg-skill/blob/main/schemas/HeritageGraph.shacl.ttl) (Quality Shapes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingestion and Extraction"]
  node_ingest["Raw Ingestor"]
  node_pdf["PDF Ingestion"]
  node_tabular["Tabular Ingestion"]
  node_scanner["Heritage Scanner"]
  node_extract["Container Extraction"]
  node_extraction_validation["Extraction Validation"]
  node_extracted["Extracted Container"]
end

subgraph group_resolution["Entity Resolution"]
  node_resolution["Resolution Runner"]
  node_gazetteer["Gazetteer Matching"]
  node_getty["Getty Lookup"]
  node_lux["LUX Lookup"]
  node_wikidata["Wikidata Lookup"]
  node_review["Review Queue"]
  node_resolved["Resolved Records"]
end

subgraph group_mapping["RDF Mapping"]
  node_mapper["RDF Mapper"]
  node_mapping_rules["Mapping Rules"]
  node_graph["RDF Graph"]
end

subgraph group_validation["Validation and Output"]
  node_shacl["SHACL Validation"]
  node_shapes["Quality Shapes"]
  node_report["Validation Report"]
  node_output["Validated RDF"]
end

subgraph group_runtime["Run Management"]
  node_orchestrator["Pipeline Runner"]
  node_workspace[("Run Workspace<br/>[run_workspace.py]")]
end

node_source(("Heritage Sources"))
node_vocabularies[("External Authorities")]
node_curator(("Human Curator"))

node_source -->|"ingests"| node_ingest
node_ingest -->|"dispatches"| node_pdf
node_ingest -->|"dispatches"| node_tabular
node_ingest -->|"scans with"| node_scanner
node_ingest -->|"prepares input"| node_extracted
node_ingest -.->|"records artifacts"| node_workspace
node_extracted -->|"feeds"| node_extract
node_extract -->|"validates with"| node_extraction_validation
node_extraction_validation -->|"validates"| node_extracted
node_extracted -->|"resolves"| node_resolution
node_resolution -->|"matches with"| node_gazetteer
node_resolution -->|"queries"| node_getty
node_resolution -->|"queries"| node_lux
node_resolution -->|"queries"| node_wikidata
node_getty -->|"queries"| node_vocabularies
node_lux -->|"queries"| node_vocabularies
node_resolution -->|"stages candidates"| node_review
node_curator -->|"reviews"| node_review
node_review -->|"curates matches"| node_resolved
node_resolution -->|"writes"| node_resolved
node_resolved -->|"maps"| node_mapper
node_mapper -.->|"uses rules"| node_mapping_rules
node_mapper -->|"emits"| node_graph
node_graph -->|"validates"| node_shacl
node_shacl -->|"checks against"| node_shapes
node_shacl -->|"writes report"| node_report
node_shacl -->|"conforms as"| node_output
node_orchestrator -->|"runs stages"| node_resolution
node_orchestrator -->|"runs stages"| node_mapper
node_orchestrator -->|"runs stages"| node_shacl
node_orchestrator -.->|"uses runs"| node_workspace
node_workspace -->|"tracks artifacts"| node_extracted
node_workspace -->|"tracks artifacts"| node_resolved
node_workspace -->|"tracks artifacts"| node_graph
node_workspace -->|"tracks artifacts"| node_report

click node_shapes "https://github.com/cairnepal/hg-skill/blob/main/schemas/HeritageGraph.shacl.ttl"
click node_workspace "https://github.com/cairnepal/hg-skill/blob/main/skills/common/run_workspace.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ingest,node_pdf,node_tabular,node_scanner,node_extract,node_extraction_validation,node_extracted toneBlue
class node_resolution,node_gazetteer,node_getty,node_lux,node_wikidata,node_review,node_resolved,node_vocabularies toneAmber
class node_mapper,node_mapping_rules,node_graph toneMint
class node_shacl,node_shapes,node_report,node_output toneRose
class node_orchestrator,node_workspace,node_source,node_curator toneIndigo
```

## Components

### Ingestion and Extraction

- **Raw Ingestor**
- **PDF Ingestion**
- **Tabular Ingestion**
- **Heritage Scanner**
- **Container Extraction**
- **Extraction Validation**
- **Extracted Container**

### Entity Resolution

- **Resolution Runner**
- **Gazetteer Matching**
- **Getty Lookup**
- **LUX Lookup**
- **Wikidata Lookup**
- **Review Queue**
- **Resolved Records**

### RDF Mapping

- **RDF Mapper**
- **Mapping Rules**
- **RDF Graph**

### Validation and Output

- **SHACL Validation**
- [Quality Shapes](https://github.com/cairnepal/hg-skill/blob/main/schemas/HeritageGraph.shacl.ttl): `schemas/HeritageGraph.shacl.ttl`
- **Validation Report**
- **Validated RDF**

### Run Management

- **Pipeline Runner**
- [Run Workspace](https://github.com/cairnepal/hg-skill/blob/main/skills/common/run_workspace.py): `skills/common/run_workspace.py`

### Other components

- **Heritage Sources**
- **External Authorities**
- **Human Curator**

## Connections

- Heritage Sources → Raw Ingestor: ingests (evidence: `README.md`)
- Raw Ingestor → PDF Ingestion: dispatches
- Raw Ingestor → Tabular Ingestion: dispatches
- Raw Ingestor → Heritage Scanner: scans with
- Raw Ingestor → Extracted Container: prepares input (evidence: `README.md`)
- Raw Ingestor → Run Workspace: records artifacts
- Extracted Container → Container Extraction: feeds (evidence: `README.md`)
- Container Extraction → Extraction Validation: validates with (evidence: `README.md`)
- Extraction Validation → Extracted Container: validates
- Extracted Container → Resolution Runner: resolves (evidence: `README.md`)
- Resolution Runner → Gazetteer Matching: matches with
- Resolution Runner → Getty Lookup: queries
- Resolution Runner → LUX Lookup: queries
- Resolution Runner → Wikidata Lookup: queries
- Getty Lookup → External Authorities: queries
- LUX Lookup → External Authorities: queries
- Resolution Runner → Review Queue: stages candidates
- Human Curator → Review Queue: reviews (evidence: `README.md`)
- Review Queue → Resolved Records: curates matches
- Resolution Runner → Resolved Records: writes (evidence: `README.md`)
- Resolved Records → RDF Mapper: maps (evidence: `README.md`)
- RDF Mapper → Mapping Rules: uses rules
- RDF Mapper → RDF Graph: emits (evidence: `README.md`)
- RDF Graph → SHACL Validation: validates (evidence: `README.md`)
- SHACL Validation → Quality Shapes: checks against (evidence: `README.md`)
- SHACL Validation → Validation Report: writes report (evidence: `README.md`)
- SHACL Validation → Validated RDF: conforms as (evidence: `README.md`)
- Pipeline Runner → Resolution Runner: runs stages (evidence: `README.md`)
- Pipeline Runner → RDF Mapper: runs stages (evidence: `README.md`)
- Pipeline Runner → SHACL Validation: runs stages (evidence: `README.md`)
- Pipeline Runner → Run Workspace: uses runs
- Run Workspace → Extracted Container: tracks artifacts (evidence: `README.md`)
- Run Workspace → Resolved Records: tracks artifacts (evidence: `README.md`)
- Run Workspace → RDF Graph: tracks artifacts (evidence: `README.md`)
- Run Workspace → Validation Report: tracks artifacts (evidence: `README.md`)