The Mapping Global China Knowledge Graph what it is, how it is built, and how the maps plug into it

The graph is built and it is real

44,781 nodes and 118,205 edges over 5,622 documents, every one of them carrying provenance back to a character span in a source document. It rebuilds daily today, on a local machine.

The map link is deterministic, not fuzzy

The pipeline ingested the platform's own /viz dataset rows and kept their ids, so a map point and its graph node share the same id. Resolution is a table lookup, not a name match. Section 04 is the one to read closely.

Everything demonstrated so far runs locally

A local FastAPI /kg service over a SQLite copy of the graph, sitting behind the real frontend. Nothing is on the live platform yet. Section 07 is the build list.

One decision gates the rest

Option A, a standalone kg.* schema keyed by research-kg's own text node ids, or Option B, keyed to global.entity_registry through a bridge. You own that call, and the API work in 07 branches on it.

The map shows where things are. The knowledge graph shows how they connect. The AI guide lets you ask across both. Project lead's framing

That framing is the useful mental model for the whole system. The maps answer where; the graph answers how these things are related, and on whose authority. The two are joined by a bridge table rather than by inference, which is what makes the round trip between them cheap and exact.

Node types

Twelve types share one id space. Entities, the documents they were found in, and the reified claims and events extracted from those documents all live in the same node table.

• Country
• Organization
• Person
• Project
• Framework
• Sector
• Document
• Claim
• Impact
• Event
• Theme
• Tag

Provenance is not optional

Every node, edge and claim carries the same block: the source document, the character span inside it, the verbatim evidence sentence, the extractor, the model, and a confidence score. Nothing enters the graph without it. That is what lets the frontend render a "From the source" citation next to every single row it displays, and what makes the graph usable as research output rather than as a suggestion engine.

Cross-lingual by construction

Chinese and English mentions of the same entity resolve to the same node. A user searching in either language reaches the same neighbourhood, and evidence extracted from a Chinese-language source hangs off the same node as evidence extracted from an English one.

%%{init:{"theme":"base","themeVariables":{"background":"#F1F4F5","primaryColor":"#E3E9EB","primaryTextColor":"#12191F","primaryBorderColor":"#7E8F98","lineColor":"#5F7079","secondaryColor":"#F6E3C4","secondaryBorderColor":"#C8801C","tertiaryColor":"#FAFBFB","tertiaryBorderColor":"#B6C2C7","clusterBkg":"#FAFBFB","clusterBorder":"#B6C2C7","textColor":"#12191F","edgeLabelBackground":"#F1F4F5","fontFamily":"ui-monospace, SFMono-Regular, Menlo, monospace","fontSize":"13px"}}}%%
flowchart LR
  subgraph SRC["sources"]
    direction TB
    S1["MFA press-conference corpus"]
    S2["~21 academic papers, by DOI"]
    S3["/viz structured datasets"]
    S4["MGC blog + stories adapter"]
  end
  SRC --> A["a. GLiNER multilingual NER
entity mentions"]
  A --> B["b. closed-vocabulary LLM pass, DeepSeek
9 relation types, reified claims, dated events"]
  B --> C{"c. NLI entailment gate, mDeBERTa
score = raw_confidence x entailment"}
  C -- "below 0.5" --> X["discarded"]
  C -- "0.5 and above" --> D["d. cross-lingual resolution
BGE-M3 + alias table, zh and en merged"]
  D --> E["e. PMI co-mention edges
Leiden communities"]
  E --> G[("nodes, edges, claims
mentions, map_link")]
  CK[("LLM checkpoint
key: kind, doc_id,
model, prompt_version")] -. "replayed docs cost 0" .-> B
  B -. "write-through" .-> CK

Checkpointed and resumable

The LLM cache keys on (kind, doc_id, model, prompt_version). A full rebuild therefore replays every already-extracted document for free, and only new or changed documents cost anything, on the order of $0.0003 per document. This is the property that makes the "reset and rebuild" cadence in section 06 defensible rather than wasteful, and it is also why an interrupted run can simply be restarted.

What has been ingested

• The MFA press-conference corpus.
• ~21 academic papers, pulled by DOI with full text.
• The platform's own /viz structured datasets: ports, energy, investments, infrastructure, BRI, state visits and the rest. These are the rows that make the map link deterministic.
• MGC website blog and story content, via a new adapter that ingests Research Briefs from Directus alongside Global China Stories.

Edge tiers

Every edge declares which tier it belongs to. The tier is the honest label for how much the edge should be trusted, and it is the natural axis for filtering in a UI.

%%{init:{"theme":"base","themeVariables":{"background":"#F1F4F5","primaryColor":"#E3E9EB","primaryTextColor":"#12191F","primaryBorderColor":"#7E8F98","lineColor":"#5F7079","secondaryColor":"#F6E3C4","secondaryBorderColor":"#C8801C","tertiaryColor":"#FAFBFB","tertiaryBorderColor":"#B6C2C7","clusterBkg":"#FAFBFB","clusterBorder":"#B6C2C7","textColor":"#12191F","edgeLabelBackground":"#F1F4F5","fontFamily":"ui-monospace, SFMono-Regular, Menlo, monospace","fontSize":"13px"}}}%%
flowchart TB
  subgraph CORE["kg.* core, keyed by text node_id"]
    direction LR
    DOC["documents"]
    NOD["nodes"]
    MEN["node_mentions"]
    EDG["edges"]
    CLM["claims"]
    EVT["events
Event nodes + edges"]
    ALI["aliases"]
  end
  subgraph BRG["bridges"]
    direction LR
    ML["map_link
source_dataset, source_row_id
node_id, entity_id, is_primary"]
    NM["node_map
node_id to entity_id
the Option B bridge"]
  end
  subgraph WH["warehouse"]
    direction LR
    VIZ["/viz dataset rows
the map's own ids"]
    REG["global.entity_registry
entity_id uuid"]
  end
  DOC -- "source_doc_id" --> EDG
  DOC --> MEN
  NOD -- "src_id, dst_id" --> EDG
  NOD --> MEN
  ALI -- "zh and en surfaces" --> NOD
  CLM -- "reified as edges" --> EDG
  EVT -- "HAS_PARTICIPANT
OCCURRED_IN" --> EDG
  VIZ --> ML
  NOD --> ML
  NOD --> NM
  NM -. "Option B" .-> REG
  ML -. "reserved entity_id" .-> REG

The schema decision: Option A or Option B

The graph is keyed by research-kg's own text node ids, things like proj:gwadar-port and country:PAK. The warehouse is keyed by global.entity_registry(entity_id uuid). Those two id spaces have to meet somewhere, and where they meet is your call.

Three known reconciliation snags under Option B

1. research-kg's Project and Framework entities, Gwadar, CPEC, BRI and their kin, are not in entity_registry. Expect a propose-new path, not a match.
2. Two resolvers are in play, and two resolvers can over-merge or under-merge relative to each other.
3. The press corpus and the papers are not yet bridged into global.documents.

This is worth stating plainly, because it is the part most likely to be assumed harder than it is: there is no fuzzy matching between the map and the graph, and no name lookup. The pipeline ingested the platform's /viz dataset rows directly, so a map point and its knowledge-graph node share the same id. The bridge table just makes that lookup explicit and indexable.

The bridge table

map_link maps (source_dataset, source_row_id) → node_id, plus a reserved entity_id column for Option B, plus is_primary. It currently holds 8,441 rows across 8,302 map points, covering the /viz layers. The two counts differ because a point can legitimately carry more than one node.

The primary-node rule

For a given (dataset, row_id), the node that represents that point is the source node of the edge, typically the Project, Person or Organization. Two exceptions matter:

• Conflict events invert it: the represented node is the destination Impact node.
• Investments can map to several nodes at once, one per co-investor Organization. This is why /kg/resolve returns a list rather than a single node.

The requirement for wiring a layer

Country selection is the one case that does not go through a row id. A country resolves via its node id, country:<ISO3>. Note the country: prefix: passing a bare ISO3 will not resolve.

The frontend path, already built

The pattern exists on the frontend branch and has been exercised against the local /kg service. A click yields a descriptor, the descriptor resolves to node ids, and the node id opens the panel. What is left is handing that descriptor over from each layer's click handler:

%%{init:{"theme":"base","themeVariables":{"background":"#F1F4F5","primaryColor":"#E3E9EB","primaryTextColor":"#12191F","primaryBorderColor":"#7E8F98","lineColor":"#5F7079","secondaryColor":"#F6E3C4","secondaryBorderColor":"#C8801C","tertiaryColor":"#FAFBFB","tertiaryBorderColor":"#B6C2C7","clusterBkg":"#FAFBFB","clusterBorder":"#B6C2C7","textColor":"#12191F","actorBkg":"#E3E9EB","actorBorder":"#7E8F98","actorTextColor":"#12191F","actorLineColor":"#8E9AA0","signalColor":"#5F7079","signalTextColor":"#12191F","labelBoxBkgColor":"#F6E3C4","labelBoxBorderColor":"#C8801C","labelTextColor":"#12191F","noteBkgColor":"#F6E3C4","noteBorderColor":"#C8801C","noteTextColor":"#12191F","sequenceNumberColor":"#FFFFFF","fontFamily":"ui-monospace, SFMono-Regular, Menlo, monospace","fontSize":"13px"}}}%%
sequenceDiagram
  autonumber
  actor U as User
  participant M as Map layer
  participant H as useKgResolve
  participant K as /kg service
  participant P as RelationshipsPanel

  U->>M: click a map point
  M->>H: deriveMapPoint feature, family
  Note over M,H: yields dataset + row_id,
the /viz row id scheme
  H->>K: GET /kg/resolve with dataset + row_id
  K-->>H: list of node_id, empty list if unmapped
  H->>K: GET /kg/entity/{node_id}
  K-->>P: center + edges + neighbours, all with provenance
  P->>U: relations, claims, events, network graph
  Note over P,U: every row carries a
From the source citation

The panel itself is RelationshipsPanel: typed relations, claims, events, and a d3-force network graph, each row carrying its own "From the source" citation block with the verbatim evidence sentence.

The round trip

The lead's "View connections" and "Show on map" are not two features. They are one table read in two directions: forward from (dataset, row_id) to a node, backward from a node to the map rows that carry its coordinates.

%%{init:{"theme":"base","themeVariables":{"background":"#F1F4F5","primaryColor":"#E3E9EB","primaryTextColor":"#12191F","primaryBorderColor":"#7E8F98","lineColor":"#5F7079","secondaryColor":"#F6E3C4","secondaryBorderColor":"#C8801C","tertiaryColor":"#FAFBFB","tertiaryBorderColor":"#B6C2C7","clusterBkg":"#FAFBFB","clusterBorder":"#B6C2C7","textColor":"#12191F","edgeLabelBackground":"#F1F4F5","fontFamily":"ui-monospace, SFMono-Regular, Menlo, monospace","fontSize":"13px"}}}%%
flowchart LR
  MP["map point
dataset, row_id"] -- "View connections
map_link, forward" --> KN["KG node
node_id"]
  KN -- "Show on map
map_link, backward" --> MP

To wire a layer

1. Confirm the layer serves /viz row ids. If it is served by the other platform API, repoint it first.
2. Have the click handler pass {dataset, row_id} into the panel, via deriveMapPoint.
3. Let useKgResolve do the rest. Treat an empty list as "no graph coverage for this point" and hide the entry point rather than showing an empty panel.

Provenance on every row

Relations, claims and events all carry source_doc_id, url, title, published_date, evidence_text and the character span. That block is what CitationBlock renders, and it is why a result list can be read as sourced research rather than as model output.

The relevance filter

Id conventions

Worth being explicit, because it changes with the schema decision. Today, under Option A, the {id} in these routes is a text node id, proj:gwadar-port or country:PAK. Under Option B, those same ids become entity_registry uuids. Same routes, same shapes, different key space.

The daily job, as it runs today

A daily job rebuilds the graph, regenerates map_link, and refreshes the served snapshot. It currently runs locally, as a macOS launchd agent with a tmux runner as fallback.

Budget

The spend cap is cumulative and persisted, not per-run, and it is a hard stop. It is currently set to $20 for the local runs. At steady state the pipeline costs roughly $2–9 a month.

The production shape

The design for production is to run the same pipeline as an mgc-hub enrichment module on a systemd timer, with an acceptance gate in front of promotion: the run only becomes visible (via a materialized-view refresh) if the provenance, anomaly and NLI checks pass. A bad run leaves yesterday's graph served rather than publishing itself. That gate is the difference between a cron job and a service.

1. Load the graph into the warehouse Postgres

   The handoff package ships postgres_kg_schema.sql, a pgvector-ready kg.* DDL; mgc_kg_data.sql.gz, a 21 MB SQL dump of nodes, edges, claims, documents, mentions and aliases; and map_link.sql.

   Decide Option A or Option B first (section 03), because step 2 depends on the answer.

2. Deploy the /kg endpoints into the production mgc-api

   They exist on branch feat/kg-endpoints, PR #43, written for the Option B entity_registry shape. If you go Option A, repoint their joins at kg.node_map / kg.nodes.

3. Ship the frontend panel and copilot

   Branch feat/kg-relationships-panel, PR #175. Point its /kg proxy at the deployed API, then wire each map layer's click to pass {dataset, row_id} into the panel (section 04).

4. Deploy

   At that point the map-to-graph round trip is live on the platform rather than on a laptop.

Five pre-ship risks the review flagged

Clone kg-handoff/. It is the technical package, meant to be self-sufficient:

For the full design rationale behind any of this, including the production cadence, the serving layer and the website integration, the design/system/ docs are the source of truth.