Research Network
Relevant source files
The following files were used as context for generating this wiki page:
The Research Network is a structured system for organizing knowledge through interconnected entities and visual relationships. It allows you to connect Research Notes to formal semantic structures including Concepts, Positions, and Arguments/Stances. These relationships are projected into a read-only visual map known as the Research Graph.
Sources: README.md:12-14, README.md:121-124
Core Entities
The network consists of four primary entity types that define the structure of research data.
Concepts
Concepts represent atomic ideas or subjects. They support hierarchical organization through parent-child relationships and can have multiple aliases for improved searchability.
Positions
Positions represent specific claims, theses, or viewpoints within a field of study.
Arguments and Stances
Arguments provide the reasoning or evidence for or against a Position or another Argument. A "Stance" is a specialized kind of Argument used to express a specific relationship (e.g., opposing or supporting) to a target.
Structural Relationships
The system maintains canonical links between these entities:
- Concept Hierarchy: Connects subconcepts to parent concepts.
- Argument Targets: Links arguments to the Positions or Arguments they address.
- Argument Sources: Connects arguments to the specific Works (PDFs or videos) that contain the evidence.
- Note Mentions: Derived references where entities are cited within Markdown research notes using
[[type:id]]syntax.
Sources: backend/research_network.py:1-40, backend/research_graph.py:252-270, README.md:11-14
Architecture and Data Flow
The Research Network uses a multi-layered approach to manage and display knowledge.
The diagram above shows the flow from persisted data in SQLite to the visual graph rendering in the browser.
Sources: backend/research_network.py, backend/research_graph.py:18-35, backend/research_index.py
Persistence
Canonical data for Concepts, Positions, and Arguments is stored in the main SQLite database. The research_network.py module provides functions for creating, updating, and deleting these records.
Indexing
The PRKSResearchIndex module manages a derived index of mentions found in research notes. It scans Markdown content for wiki-style links and stores them in a separate prks_research_index.db file. This index is rebuildable and not required for backups.
Sources: backend/research_index.py:10-25, backend/research_graph.py:340-355
Research Graph
The Research Graph is a read-only visual projection of the Research Network. It uses Cytoscape.js to render nodes and edges representing the state of the library.
Graph Components
| Component | Description |
|---|---|
| Nodes | Represent entities: Works, Concepts, Positions, Arguments, and People (optional). |
| Edges | Represent relationships: concept_parent, argument_target, argument_source, and mentions. |
| Inspector | A side panel that displays metadata for the currently selected node or edge. |
| Toolbar | Provides controls for Find, Fit, Reset layout, and filtering entity types. |
Sources: backend/research_graph.py:38-70, frontend-app/src/features/research-graph/ResearchGraphRoute.vue:50-100, frontend/js/components/research-graph.js:20-45
Data Projection Logic
The ResearchGraphBuilder enforces strict bounds on graph size to ensure browser performance.
- MAX_GRAPH_NODES: 2,500
- MAX_GRAPH_EDGES: 7,500
If these limits are exceeded, the builder raises a GraphTooLargeError. The builder normalizes IDs by prefixing them with their type (e.g., concept:C-1) to prevent collisions between different entity types sharing the same record ID.
Sources: backend/research_graph.py:19-25, backend/research_graph.py:126-140
Relationship Types in Graph
The builder extracts specific edge types for visualization:
| Edge Type | Source | Target | Label/Metadata |
|---|---|---|---|
concept_parent | Child Concept | Parent Concept | "Parent" |
argument_position | Argument | Position | Verdict (Supports/Opposes) |
argument_argument | Argument | Argument | Verdict (Supports/Opposes) |
argument_source | Argument | Work | Page numbers |
mentions_concept | Work | Concept | Mention count |
mentions_argument | Work | Argument | Mention count |
work_author | Person | Work | "Author" (if people included) |
Sources: backend/research_graph.py:252-320, backend/research_graph.py:465-485
Implementation Details
Node Structure
Nodes are serialized into a flat structure for the frontend. Every node includes:
id: Namespaced identifier (e.g.,work:W-1).record_id: The raw database ID.type: The entity type.label: Display name (e.g., Work title or Concept name).route: The application internal hash for navigation.
Sources: backend/research_graph.py:38-65
Privacy and Security
The Research Graph is a metadata-only projection. The ResearchGraphBuilder excludes sensitive content such as full research note text or entity descriptions from the graph snapshot to minimize data exposure in the visual interface.
Sources: backend/research_graph.py:15-17, backend/research_graph.py:530-545
Conclusion
The Research Network transforms isolated research notes into a structured knowledge base. By combining formal relationships (arguments, positions) with derived references (note mentions), it provides both a rigorous semantic framework and a flexible discovery tool through the visual Research Graph.