# seemanteng/ling-mapper architecture

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

- Interactive diagram: https://gitdiagram.com/seemanteng/ling-mapper
- Repository: https://github.com/seemanteng/ling-mapper

## Overview

Ling Mapper turns an essay question and response into a validated, clause-level argument graph, then displays it for review. The primary path is the local web interface (or batch extraction) through two-stage Claude extraction and contract validation to graph output and the browser viewer. Supporting product branches cover record preparation and scoring, plus explicitly exploratory source-passage graphs, alignment, and findings. The README documents these capabilities; source excerpts are partial, so uncertain exploratory wiring is left unconnected.

Main entry points: [`src/argument_graph/student_graph.py`](https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/student_graph.py) (Two-stage extraction), [`src/argument_graph/graph_schema.py`](https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/graph_schema.py) (Graph contract), [`src/argument_graph/web.py`](https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/web.py) (Local web interface), [`src/argument_graph/loaders/persuade.py`](https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/loaders/persuade.py) (PERSUADE importer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extract["Student extraction"]
  node_web["Local web interface<br/>[web.py]"]
  node_extractor["Two-stage extraction<br/>[student_graph.py]"]
  node_contract["Graph contract<br/>[graph_schema.py]"]
end

subgraph group_records["Records and scoring"]
  node_records_schema["Record schemas<br/>[schemas.py]"]
  node_persuade["PERSUADE importer<br/>[persuade.py]"]
  node_span_recovery["Span recovery<br/>[spans.py]"]
  node_data_prep["Record preparation<br/>[prepare_data.py]"]
  node_gum["GUM importer<br/>[gum.py]"]
  node_scorer["Graph evaluation<br/>[evaluate.py]"]
end

subgraph group_explore["Exploratory analysis"]
  node_source_fetch["Source retrieval<br/>[fetch_sources.py]"]
  node_source_graph["Source graph<br/>[source_graph.py]"]
  node_alignment["Student-source alignment<br/>[align.py]"]
  node_findings["Alignment findings<br/>[findings.py]"]
  node_source_viewer["Source graph viewer"]
  node_findings_viewer["Findings viewer"]
end

subgraph group_review["Graph review"]
  node_viewer["Graph viewer"]
end

node_essay_author(("Essay submitter"))
node_claude{{"Anthropic Claude"}}

node_essay_author -->|"submits essay"| node_web
node_web -->|"runs extraction"| node_extractor
node_extractor -->|"requests annotations"| node_claude
node_extractor -->|"validates graph"| node_contract
node_web -->|"renders result"| node_viewer
node_persuade -->|"recovers spans"| node_span_recovery
node_persuade -->|"creates records"| node_records_schema
node_data_prep -->|"imports records"| node_persuade
node_gum -->|"creates records"| node_records_schema
node_gum -->|"adapts relation schema"| node_contract
node_scorer -->|"derives edge scores"| node_contract
node_viewer -->|"shows violations"| node_contract
node_alignment -->|"aligns student graphs"| node_extractor
node_findings -->|"analyzes alignments"| node_alignment
node_source_viewer -->|"renders source graphs"| node_source_graph
node_findings_viewer -.->|"renders findings"| node_findings

click node_web "https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/web.py"
click node_extractor "https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/student_graph.py"
click node_contract "https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/graph_schema.py"
click node_records_schema "https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/schemas.py"
click node_persuade "https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/loaders/persuade.py"
click node_span_recovery "https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/spans.py"
click node_data_prep "https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/prepare_data.py"
click node_gum "https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/loaders/gum.py"
click node_scorer "https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/evaluate.py"
click node_viewer "https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/render_graph_html.py"
click node_source_fetch "https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/fetch_sources.py"
click node_source_graph "https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/source_graph.py"
click node_alignment "https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/align.py"
click node_findings "https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/findings.py"
click node_source_viewer "https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/render_source_html.py"
click node_findings_viewer "https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/render_findings_html.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_web,node_extractor,node_contract toneBlue
class node_records_schema,node_persuade,node_span_recovery,node_data_prep,node_gum,node_scorer toneAmber
class node_source_fetch,node_source_graph,node_alignment,node_findings,node_source_viewer,node_findings_viewer toneMint
class node_viewer toneRose
class node_essay_author,node_claude toneIndigo
```

## Components

### Student extraction

- [Local web interface](https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/web.py): `src/argument_graph/web.py`
- [Two-stage extraction](https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/student_graph.py): `src/argument_graph/student_graph.py`
- [Graph contract](https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/graph_schema.py): `src/argument_graph/graph_schema.py`

### Records and scoring

- [Record schemas](https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/schemas.py): `src/argument_graph/schemas.py`
- [PERSUADE importer](https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/loaders/persuade.py): `src/argument_graph/loaders/persuade.py`
- [Span recovery](https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/spans.py): `src/argument_graph/spans.py`
- [Record preparation](https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/prepare_data.py): `src/argument_graph/prepare_data.py`
- [GUM importer](https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/loaders/gum.py): `src/argument_graph/loaders/gum.py`
- [Graph evaluation](https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/evaluate.py): `src/argument_graph/evaluate.py`

### Exploratory analysis

- [Source retrieval](https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/fetch_sources.py): `src/argument_graph/fetch_sources.py`
- [Source graph](https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/source_graph.py): `src/argument_graph/source_graph.py`
- [Student-source alignment](https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/align.py): `src/argument_graph/align.py`
- [Alignment findings](https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/findings.py): `src/argument_graph/findings.py`
- [Source graph viewer](https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/render_source_html.py): `src/argument_graph/render_source_html.py`
- [Findings viewer](https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/render_findings_html.py): `src/argument_graph/render_findings_html.py`

### Graph review

- [Graph viewer](https://github.com/seemanteng/ling-mapper/blob/main/src/argument_graph/render_graph_html.py): `src/argument_graph/render_graph_html.py`

### Other components

- **Essay submitter**
- **Anthropic Claude**

## Connections

- Essay submitter → Local web interface: submits essay (evidence: `README.md`)
- Local web interface → Two-stage extraction: runs extraction (evidence: `src/argument_graph/web.py`)
- Two-stage extraction → Anthropic Claude: requests annotations (evidence: `README.md`)
- Two-stage extraction → Graph contract: validates graph (evidence: `src/argument_graph/student_graph.py`)
- Local web interface → Graph viewer: renders result (evidence: `src/argument_graph/web.py`)
- PERSUADE importer → Span recovery: recovers spans (evidence: `src/argument_graph/loaders/persuade.py`)
- PERSUADE importer → Record schemas: creates records (evidence: `src/argument_graph/loaders/persuade.py`)
- Record preparation → PERSUADE importer: imports records (evidence: `src/argument_graph/prepare_data.py`)
- GUM importer → Record schemas: creates records (evidence: `src/argument_graph/loaders/gum.py`)
- GUM importer → Graph contract: adapts relation schema (evidence: `src/argument_graph/loaders/gum.py`)
- Graph evaluation → Graph contract: derives edge scores (evidence: `src/argument_graph/evaluate.py`)
- Graph viewer → Graph contract: shows violations (evidence: `src/argument_graph/render_graph_html.py`)
- Student-source alignment → Two-stage extraction: aligns student graphs (evidence: `src/argument_graph/align.py`)
- Alignment findings → Student-source alignment: analyzes alignments (evidence: `src/argument_graph/findings.py`)
- Source graph viewer → Source graph: renders source graphs (evidence: `src/argument_graph/render_source_html.py`)
- Findings viewer → Alignment findings: renders findings
