From 87af3f12c168aade6333ac9125154a5391b02abe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nikola=20Perovi=C4=87?= <46610174+Fooftilly@users.noreply.github.com> Date: Sun, 20 Sep 2026 23:08:49 +0200 Subject: [PATCH 1/3] docs: add screenshots and diagrams to wiki --- docs/wiki/Architecture.md | 14 ++++++++++++++ docs/wiki/Getting-Started.md | 3 +++ docs/wiki/Home.md | 9 +++++++++ docs/wiki/Offline-and-Sync.md | 22 ++++++++++++++++++++++ docs/wiki/README.md | 13 +++++++++++++ docs/wiki/Research-Network.md | 17 +++++++++++++++++ docs/wiki/User-Guide.md | 5 +++++ docs/wiki/Workspace-Tabs-and-Split-View.md | 17 +++++++++++++++++ 8 files changed, 100 insertions(+) diff --git a/docs/wiki/Architecture.md b/docs/wiki/Architecture.md index 0871122d..e3f7862e 100644 --- a/docs/wiki/Architecture.md +++ b/docs/wiki/Architecture.md @@ -2,6 +2,20 @@ PRKS is a local-first research application with a Python backend, SQLite persistence, managed files on disk, and a vanilla-JavaScript single-page frontend. +```mermaid +flowchart LR + U[Browser / PWA] -->|HTTP / API| S[PRKS threaded HTTP server] + S --> G[LibraryAccessGate] + G --> DB[(SQLite library)] + G --> F[Managed files] + G --> I[Derived indexes / caches] + U --> LS[(Browser local store)] + LS <-->|durable ops + reconciliation| S +``` + +The diagram separates canonical server storage from browser-local durable intent and from rebuildable derived indexes. + + ## Runtime shape At a high level: diff --git a/docs/wiki/Getting-Started.md b/docs/wiki/Getting-Started.md index a86bc38e..ca9b1d12 100644 --- a/docs/wiki/Getting-Started.md +++ b/docs/wiki/Getting-Started.md @@ -2,6 +2,9 @@ PRKS is designed to run locally. The normal installation uses Python and SQLite directly; Docker is optional. +![PRKS public-domain demo library](https://raw.githubusercontent.com/Fooftilly/PRKS/master/docs/screenshots/folders.png) + + ## Requirements PRKS currently requires Python 3.12 or newer and the exact Python package versions pinned in `requirements.txt`. The application validates the Python environment before it performs database recovery, migrations, storage binding, or server startup. diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md index cf7bae5e..6e085a8d 100644 --- a/docs/wiki/Home.md +++ b/docs/wiki/Home.md @@ -4,6 +4,15 @@ PRKS (Personal Research Knowledge System) is a local research library for organi The wiki is the orientation layer for users and contributors. It explains how the major parts fit together without replacing the repository's detailed implementation documents. +## PRKS at a glance + +| Library | Work / PDF | People | +| --- | --- | --- | +| ![PRKS folder showing public-domain research works](https://raw.githubusercontent.com/Fooftilly/PRKS/master/docs/screenshots/folders.png) | ![PRKS Work view with Origin of Species open in the PDF reader](https://raw.githubusercontent.com/Fooftilly/PRKS/master/docs/screenshots/work.png) | ![PRKS People library](https://raw.githubusercontent.com/Fooftilly/PRKS/master/docs/screenshots/people.png) | + +These screenshots are generated from the repository's synthetic/public-domain demo library rather than a real personal research collection. + + ## Start here - [Getting Started](Getting-Started.md) — install, run, Docker, testing mode, and storage basics. diff --git a/docs/wiki/Offline-and-Sync.md b/docs/wiki/Offline-and-Sync.md index a8e0fa01..81414881 100644 --- a/docs/wiki/Offline-and-Sync.md +++ b/docs/wiki/Offline-and-Sync.md @@ -2,6 +2,28 @@ PRKS is progressively becoming local-first. The core rule is that durable user intent and offline read caching are separate systems. +```mermaid +sequenceDiagram + participant U as User + participant UI as PRKS UI + participant L as Durable local store + participant S as PRKS server + participant DB as Canonical SQLite state + + U->>UI: Edit supported data + UI->>L: Persist operation first + L-->>UI: Project pending intent + UI-->>U: Show saved/pending state + L->>S: Sync when reachable + S->>DB: Validate + apply + DB-->>S: Canonical revision + S-->>L: Acknowledge / reconcile + L-->>UI: Project canonical result +``` + +A disposable offline read projection is separate from this durable mutation path. + + ## Three different mechanisms ### Disposable read cache/projection diff --git a/docs/wiki/README.md b/docs/wiki/README.md index 2bc48c46..baa09451 100644 --- a/docs/wiki/README.md +++ b/docs/wiki/README.md @@ -24,3 +24,16 @@ When a wiki page summarizes one of those areas, link to the authoritative docume `.github/workflows/publish-wiki.yml` mirrors this directory to the GitHub Wiki after changes land on `master`. `README.md` itself is source-maintenance guidance and is not published as a Wiki page. GitHub creates the backing `PRKS.wiki.git` repository only after the Wiki has been initialized once. If it does not exist yet, create an initial Home page in the repository's Wiki UI, then run the **Publish Wiki** workflow manually. After that, merges that touch `docs/wiki/**` publish automatically. + + +## Visual documentation + +Use visuals when they explain a workflow or architecture faster than prose: + +- repository demo screenshots must come from synthetic/public-domain test data; +- screenshots should be referenced from stable repository URLs so they render in both `docs/wiki/` and the published GitHub Wiki; +- prefer Mermaid for architecture/data-flow diagrams that benefit from version-controlled text diffs; +- keep diagrams small and conceptual rather than mirroring implementation line-by-line; +- do not publish screenshots from a real personal research library. + +The canonical promotional screenshot pipeline lives under `scripts/seed_demo_library.py`, `scripts/capture_demo_screenshots.py`, and `docs/screenshots/`. diff --git a/docs/wiki/Research-Network.md b/docs/wiki/Research-Network.md index d62b680a..090afa04 100644 --- a/docs/wiki/Research-Network.md +++ b/docs/wiki/Research-Network.md @@ -2,6 +2,23 @@ PRKS includes structured research entities in addition to ordinary library metadata. +```mermaid +flowchart LR + W[Works / sources] -->|research-note mentions| A[Arguments / Stances] + A -->|evidence / source| W + W -->|research-note mentions| C[Concepts] + C -->|parent hierarchy| C + A -->|supports / opposes / qualifies| P[Positions] + A -->|responds to| A2[Other Arguments] + P --> G[Research Graph] + A --> G + C --> G + W --> G +``` + +The graph is a projection of canonical research relationships; it is not a separate graph database. + + ## Concepts Concepts represent research ideas/categories and can participate in hierarchical/related structures. Concept list/detail pages can be used alongside Works in the workspace. diff --git a/docs/wiki/User-Guide.md b/docs/wiki/User-Guide.md index cd4774b0..25737473 100644 --- a/docs/wiki/User-Guide.md +++ b/docs/wiki/User-Guide.md @@ -2,6 +2,11 @@ PRKS organizes research around Works and the entities connected to them. The interface is deliberately closer to a research workspace than to a file manager: a PDF or video can carry bibliographic metadata, research notes, people/roles, tags, progress, annotations, and links into the research network. +![PRKS Work detail with managed PDF](https://raw.githubusercontent.com/Fooftilly/PRKS/master/docs/screenshots/work.png) + +The screenshots in this guide use the public-domain demo library maintained by the repository. + + ## Works A Work is the central research item. A Work may represent a managed PDF, an online/video source, or another supported research item. diff --git a/docs/wiki/Workspace-Tabs-and-Split-View.md b/docs/wiki/Workspace-Tabs-and-Split-View.md index 85e62e27..71ec070e 100644 --- a/docs/wiki/Workspace-Tabs-and-Split-View.md +++ b/docs/wiki/Workspace-Tabs-and-Split-View.md @@ -2,6 +2,23 @@ PRKS keeps a strip of in-app tabs under the top ribbon. Stacked mode shows one page at a time. Split view shows Main on the left and a Secondary area on the right that can itself be split further, up to 4 panes on screen at once (Main plus 3 Secondary). PRKS remembers your open tabs and split layout between sessions on this browser/device. That memory is local to the browser profile; there is no server-side workspace synchronization in this version. +```mermaid +flowchart TB + Tabs[Open PRKS tabs] --> Main[Main pane
owns browser URL] + Tabs --> Secondary[Secondary tree
recursive splits] + Tabs --> Parked[Parked tabs
not currently mounted] + Secondary --> S1[Secondary pane] + Secondary --> S2[Secondary pane] + S1 --> S3[Optional nested split] + + Main -. per-tab .-> C1[TabContext] + S1 -. per-tab .-> C2[TabContext] + S2 -. per-tab .-> C3[TabContext] +``` + +Each visible pane has its own TabContext; parked tabs remain open without necessarily keeping their page resources mounted. Main is a permanent root pane beside the Secondary tree — nested splits live only under Secondary. + + ## Workspace tabs Opening supported destinations creates or reuses PRKS tabs. Tabs can be switched, reordered, closed, or parked. From 241359ae298fe0d8324b2c01fbe7e97241294cf2 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 21 Sep 2026 13:58:24 +0000 Subject: [PATCH 2/3] docs: align research-network diagram with schema MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Split Work↔Argument edges into note mentions vs evidence/source, replace the nonexistent Concept→Position link with concept hierarchy, and show Main beside the Secondary tree rather than nesting splits under Main. Co-authored-by: Nikola Perović --- docs/wiki/Research-Network.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/wiki/Research-Network.md b/docs/wiki/Research-Network.md index 090afa04..21637dcc 100644 --- a/docs/wiki/Research-Network.md +++ b/docs/wiki/Research-Network.md @@ -7,7 +7,7 @@ flowchart LR W[Works / sources] -->|research-note mentions| A[Arguments / Stances] A -->|evidence / source| W W -->|research-note mentions| C[Concepts] - C -->|parent hierarchy| C + C -->|parent of| C2[Child Concepts] A -->|supports / opposes / qualifies| P[Positions] A -->|responds to| A2[Other Arguments] P --> G[Research Graph] From 87c5da1c39744d0ac6e7c41419064026ff6d62aa Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 21 Sep 2026 14:01:42 +0000 Subject: [PATCH 3/3] docs: include holds in research-network diagram MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Align the Argument→Position Mermaid edge label with the page text (support / oppose / qualify / hold). Co-authored-by: Nikola Perović --- docs/wiki/Research-Network.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/wiki/Research-Network.md b/docs/wiki/Research-Network.md index 21637dcc..225df91b 100644 --- a/docs/wiki/Research-Network.md +++ b/docs/wiki/Research-Network.md @@ -8,7 +8,7 @@ flowchart LR A -->|evidence / source| W W -->|research-note mentions| C[Concepts] C -->|parent of| C2[Child Concepts] - A -->|supports / opposes / qualifies| P[Positions] + A -->|supports / opposes / qualifies / holds| P[Positions] A -->|responds to| A2[Other Arguments] P --> G[Research Graph] A --> G