Where the graph data lives
Thoughtlines keeps imported source records, local research, and application views distinct. The graph used for analysis is a rebuildable projection over those records, not a second hand-edited copy of the research.
Reviewed 14 October 2026 · Prototype documentationThis page describes the data path and its boundaries. For node meanings and the collection workflow, see the companion pages.
The data path
The upper row holds preserved inputs. The middle row reconciles identities and graph relationships. The bottom row shows the canonical graph used by readers and analysis, alongside raw source diagnostics.
Storage and ownership
| Material | Where it lives | Authoritative record |
|---|---|---|
| InPhO acquisition | data/acquisition/ locally; verified ZIP outside Git; manifest in data/artifacts.json | Original captured responses and batch identity. Re-import never overwrites local interpretation. |
| Staged source index | data/database/atlas.sqlite | Rebuildable SQLite tables for source records, source relation occurrences, and capture lookup. It is an index, not the authoritative backup. |
| Editorial research | data/local/ and pinned JSON snapshots under data/derived/atlas/, data/derived/treatments/, and data/derived/treatment-relations/ | Versioned identities, entities, claims, citations, treatments, dates, drafts, collection plans, receipts, and review state. Manifests select exact validated snapshots. |
| Navigation output | data/derived/navigation/ or assembled by the local server | Disposable graph projection. Rebuild it from staged InPhO data and the pinned local bundle; do not edit it as source data. |
| Published story snapshot | web/stories/ | A bounded read-only bundle and rendered article, derived from a selected active graph snapshot. The story catalog indexes these outputs; publication does not change the atlas. |
Git preserves the editorial inputs and small immutable snapshots. Recovery verifies the external source archive and those snapshot checksums before rebuilding a fresh SQLite database and graph. A collection groups existing graph IDs; it does not own a separate copy of each node.
One identity, several source records
Augustine example
InPhO has inpho:entity:2569 (“Augustine of Hippo”) and inpho:entity:4180 (“Saint Augustine”). Explicit identity assignments map both to local:entity:augustine. The unified graph contains one Augustine node with both source IDs. Its incoming and outgoing source occurrences point to that canonical node, while each edge retains its original_source, original_target, record ID, capture and locator.
That is a graph merge, not deletion of either InPhO record. Relations made into self-loops solely by this identity reconciliation are omitted from the unified navigation graph; the source occurrence remains inspectable in staging.
Node type and relationship meaning remain separate from identity. A source association is an imported, unassessed connection; a treatment’s participant/idea/work links describe its structure; a sourced treatment-to-treatment relation may represent a historical response or influence. Shared ideas or graph proximity alone do not create such a historical claim.
What applications read
Research and collection analysis
atlas.unified.build_graph joins staged source occurrences to local records, resolves identity aliases, and checks endpoints. atlas.node_review.traversal_graph then excludes removed nodes and incident edges. Frontier planning, worklists, research history, and coverage should start here.
Explorer and record pages
The local server supplies an active canonical snapshot; public builds supply a pinned, allowlisted JSON release. Both use the same browser query engine for search, neighborhoods and expansion, and the same layouts, grouping, filters and sourced record cards. The raw atlas.neighborhood query remains available for source diagnostics.
The record view and collection dashboard read the unified graph and saved workflow artifacts. Reader caches refresh when local snapshot pins or editorial files change; public snapshots refresh only when a new release is published. Story companions read a bounded exported snapshot and require no live database or LLM; the article and its data remain stable until explicitly revised. The Explorer can show that graph together with a source neighborhood, then apply timeline, type-lane, fading, or compact-group display rules. Those layout rules do not rewrite graph identity or evidence.
Review status is an overlay: pruning removes a node and its incident edges from current active views and future traversal. Source captures, local records, and historical run receipts remain saved, so restoration can recover the same connections.
Practical rules for new features
| Task | Use this boundary |
|---|---|
| Rank or traverse ideas and thinkers | Use the active canonical traversal graph. Normalize supplied IDs through its alias map before counting nodes or paths. |
| Inspect an exact InPhO claim | Use its source record or raw neighborhood; preserve the source ID, occurrence, capture and locator. |
| Add a treatment | Save validated local research and citations. Resolve all endpoints and dates, then rebuild the unified projection. |
| Hide or restore a node | Change review visibility, then derive a fresh active graph. Do not delete the imported or editorial record. |
| Build a public read-only site | Export an allowlisted active graph/view snapshot. Explorer, record details and Collections share their interfaces and query/display code with static providers. Overview and shared navigation are the next consolidation steps. Private research providers and mutation services stay local. |
For executable detail see atlas/unified.py, atlas/node_review.py, atlas/neighborhood.py, atlas/explorer.py, and docs/BACKUP_AND_RECOVERY.md. The ontology and model pages define what the records mean; this page describes where they flow.