People & Roles
Relevant source files
The following files were used as context for generating this wiki page:
People & Roles represent the human entities and their specific contributions to research materials within the Personal Research Knowledge System (PRKS). The system tracks biographical data, expertise, and structured relationships between people and research works, such as authorship or editorial contributions. Sources: README.md:3-8, frontend/index.html:105-121
Person Entity and Profile
A Person in PRKS is a central entity identified by a unique ID and a set of biographical fields. The system provides tools to manage profiles, including biological dates, portrait images, and links to external encyclopedias like Wikipedia or the Stanford Encyclopedia of Philosophy. Sources: frontend/index.html:436-455, frontend/js/components/people.js:296-309
Biographical Data Management
The system includes specialized logic for handling birth and death dates, supporting both AD and BC years. Dates can be recorded as year-only or full calendar dates. Sources: frontend/js/components/people.js:23-95
- Year-only formats: Supports "1903" or "-428" (for 428 BC).
- Full dates: Supports "DD/MM/YYYY" format, where the year segment can be negative for BC dates.
- Display Logic: The system converts stored ISO-like strings into human-readable text, such as "15 March 384 BC".
Sources: frontend/js/components/people.js:65-98
Person Profile Fields
The standard person profile consists of the following data points used for rendering person cards and facilitating search:
| Field | Description | Type |
|---|---|---|
first_name | Primary name(s), including middle names. | String |
last_name | Family name (Required). | String |
aliases | Alternative names or common transliterations. | String |
about | Encyclopedic biography describing expertise and significance. | String |
birth_date | Date or year of birth (supports BC). | String |
death_date | Date or year of death (supports BC). | String |
image_url | Direct URL to a static portrait raster image. | String (URL) |
links_other | Markdown-formatted list of additional external links. | String |
Sources: frontend/js/components/people.js:311-331, frontend/js/components/people.js:636-640
Roles and Relationships
Roles define the specific nature of a connection between a Person and a Work. These relationships are structural, allowing the system to recompute flattened credit strings (e.g., "Primary Author") from individual links. Sources: frontend/js/work-role-state.js:8-17
Supported Role Types
PRKS supports the following specific role types for linking people to files:
- Author: Primary creator of the content.
- Editor: Responsible for revising or preparing the work for publication.
- Reviewer: Provided formal evaluation of the work.
- Translator: Translated the work from another language.
- Introduction/Foreword/Afterword: Contributed supplemental sections.
- Mentioned: Referenced within the text content.
Sources: frontend/js/work-role-state.js:23-26, frontend/index.html:105-115
Effective Link Overlay
The system maintains an "effective" list of links by merging acknowledged server state with pending local operations. This ensures that when you add or remove a link offline, the UI updates immediately. Sources: frontend/js/work-role-state.js:107-148
The diagram shows how the system computes the current visible state of person-work relationships by overlaying local intents on top of the server-verified record.
Sources: frontend/js/work-role-state.js:124-162
Offline and Sync Architecture
People-related mutations in PRKS are designed as local-first, durable operations. This allows the user to create persons, edit profiles, or change group memberships without an active server connection. Sources: AGENTS.md:144-156, frontend/js/components/people.js:114-135
Mutation Handling
When you perform a mutation (e.g., saving a profile edit), the system follows a durable path:
- Draft Creation: The editor captures changes in a profile draft.
- Durable Write: The intent is written to a local IndexedDB queue.
- Local-First Update: The UI reflects the change immediately using the pending overlay.
- Sync Reconciliation: Once a connection is restored, the coordinator sends the intent to the server and patches the local cache with the final acknowledged record.
Sources: frontend/js/components/people.js:527-548, frontend/js/work-role-state.js:246-271
Offline State Application
The user interface restricts certain actions based on connectivity status, specifically those that are not yet durable. Sources: frontend/js/components/people.js:145-161
The sequence illustrates the durable mutation lifecycle where the user receives feedback immediately, and server synchronization occurs asynchronously.
Sources: frontend/js/components/people.js:779-843, AGENTS.md:158-164
Summary
People & Roles provide the social and professional context for research data in PRKS. By utilizing a durable, local-first architecture for profiles and a structural relationship model for roles, the system ensures that human contributions are tracked accurately even in offline environments. Effective credit recomputation and biological date parsing further support the system's goal of maintaining a comprehensive research library. Sources: README.md:3-8, frontend/js/work-role-state.js:164-177