June 5, 2026 5 min read TypeScript fork

siyuan

Abstract

A privacy-first, self-hosted, fully open source personal knowledge management software, written in typescript and golang.

Forked from siyuan-note/siyuan

The Problem

SiYuan solves the problem of personal knowledge management (PKM) for users who want full control over their data. Most PKM tools are either closed-source, cloud-only, or both, which means your notes live on someone else's server. SiYuan is a self-hosted, open-source alternative that keeps your data local or on infrastructure you control.

What This Does

SiYuan is a privacy-first, self-hosted personal knowledge management system. It is a fork of the popular siyuan-note/siyuan project (46k+ stars). The repository contains a full application: a rich-text editor with block-based note-taking, a Go-based kernel that handles data persistence and a REST API, and an Electron shell for desktop deployment.

The codebase is split into two main projects: app/ (the TypeScript/React frontend) and kernel/ (the Go backend). The frontend handles the editor UI, while the kernel manages the data layer, including the database and file system operations. A Dockerfile is present for containerized deployment.

How It Is Wired

The application starts in the frontend. The entry point is app/electron/main.js for the desktop app, which loads app/appearance/boot/index.html. From there, app/src/index.ts is the main frontend module, importing 27 modules and being imported by 80.

The frontend communicates with the Go kernel via a REST API. The kernel, built from kernel/go.mod, handles file persistence and data operations. The API surface is documented in API.md.

The module graph shows a clear hub-and-spoke pattern. app/src/constants is the central hub, imported by 198 modules. app/src/util/fetch (imported by 160 modules) handles HTTP calls to the kernel. These are high-blast-radius modules—changes to them ripple across the entire frontend.

There are 240 modules inside circular dependencies. This means some import cycles exist (e.g., app/src/util/fetch.ts participates in one), which can complicate refactoring and testing. The app/src/protyle/util/hasClosest function is a utility with 134 importers and zero dependencies, making it a stable leaf node.

The kernel side has 236 Go files. The exact data flow from frontend to disk is not fully mapped in this analysis, but the REST API over HTTP is the primary boundary between the two projects.

How To Use It

Setup (from the README and Dockerfile):

# Clone the repository
git clone https://github.com/moses-y/siyuan

# For development, you'll need both Node and Go toolchains
cd app && npm install
cd ../kernel && go mod download

# Or build the Docker image
docker build -t siyuan .

Running it: The README documents Docker hosting as the simplest path:

docker run -v /path/to/data:/home/siyuan/data -p 6806:6806 siyuan

The kernel exposes its API on port 6806. For desktop use, the Electron app (app/electron/main.js) is the entry point. The README also documents installation packages for Windows, macOS, and Linux.

Real-World Use

A typical deployment is a small team or individual running SiYuan in Docker on a home server or VPS. With the data volume mounted, notes persist across container restarts. The web interface is accessible via the mapped port, and the REST API allows integration with other tools. For example, a script could push meeting notes into a specific notebook using the API documented in API.md.

Code Health & Issues

Static analysis (not opinion) found 709 issues across 5 categories:

High - Import cycle members (19 instances): app/src/util/fetch.ts, app/src/protyle/util/compatibility.ts, app/src/index.ts participate in circular imports. This complicates refactoring and can cause initialization-order bugs.
High - Deep nesting (19 instances): app/src/constants.ts, app/src/index.ts, app/src/protyle/util/compatibility.ts have control flow nested up to 7 levels deep.
High - Oversized files (9 instances): app/src/constants.ts is 824 lines. High fan-in plus large size means changes there have wide blast radius.
High - Hub modules (7 instances): app/src/constants.ts (198 dependents) and app/src/util/fetch.ts (160 dependents) are the riskiest files to modify.
Medium - High branching density (6 instances): app/src/util/fetch.ts has 45 branch points over 135 lines.

Additional health audit findings:

High - Unpinned GitHub Actions: .github/workflows uses mutable tags (e.g., @v4.1.2, @master) instead of commit SHAs. A moved tag could compromise CI secrets.
Med - No least-privilege token: Workflows referencing secrets don't declare permissions, so the token inherits repo defaults.
Med - No dependency update bot: No Dependabot or Renovate configured.
Med - Mutable Docker base images: node:21, golang:1.25-alpine, alpine:latest in the Dockerfile.
Med - No dependency vulnerability scan in CI.
Med - Large binaries in repo: app/pandoc/pandoc-windows-amd64.zip is 36.4MB; 7 blobs over 5MB total.
Med - persist-credentials: false not set on checkout in .github/workflows/cd.yml.
Med - No non-root USER in Dockerfile.
Med - Test coverage is minimal: 1 test file against 622 source files (ratio 0.002).
Low - No job timeouts in workflows.

The Bottom Line

This is a mature, feature-complete PKM application with a solid architecture: a clean split between a Go kernel and a TypeScript frontend. The main risks are the hub modules with high fan-in, circular imports, and CI/CD hygiene issues (unpinned actions, mutable base images, no dependency scanning). The test coverage is effectively nonexistent, so changes to core modules carry real regression risk. If you need a self-hosted PKM system and accept the maintenance burden, this is a strong candidate—but treat the lack of tests as a known hazard before making deep changes.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

2,143 files

Markdown393
TypeScript295
CSS260
Go236
JavaScript80
SCSS51

ReactExpressDocker

Module dependencies

The 10 most depended-upon modules of 372, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_app_src_constants["constants"] n1_app_src_util_fetch["fetch"] n2__src_protyle_util_hasClosest["hasClosest"] n3_c_protyle_util_compatibility["compatibility"] n4_app_src_util_functions["functions"] n5_app_src_index["index"] n6_p_src_protyle_util_selection["selection"] n7_app_src_dialog_message["message"] n8_app_src_util_escape["escape"] n9_app_src_util_pathName["pathName"] n0_app_src_constants --> n4_app_src_util_functions n7_app_src_dialog_message --> n0_app_src_constants n5_app_src_index --> n0_app_src_constants n5_app_src_index --> n1_app_src_util_fetch n5_app_src_index --> n9_app_src_util_pathName n5_app_src_index --> n7_app_src_dialog_message n5_app_src_index --> n3_c_protyle_util_compatibility n5_app_src_index --> n4_app_src_util_functions n3_c_protyle_util_compatibility --> n6_p_src_protyle_util_selection n3_c_protyle_util_compatibility --> n1_app_src_util_fetch n3_c_protyle_util_compatibility --> n0_app_src_constants n6_p_src_protyle_util_selection --> n2__src_protyle_util_hasClosest n6_p_src_protyle_util_selection --> n0_app_src_constants n1_app_src_util_fetch --> n0_app_src_constants n9_app_src_util_pathName --> n1_app_src_util_fetch n9_app_src_util_pathName --> n8_app_src_util_escape n9_app_src_util_pathName --> n4_app_src_util_functions n9_app_src_util_pathName --> n6_p_src_protyle_util_selection classDef cyc stroke:#ef4444,stroke-width:2px; class n1_app_src_util_fetch,n3_c_protyle_util_compatibility,n5_app_src_index,n6_p_src_protyle_util_selection,n9_app_src_util_pathName cyc;

Dependencies

11 of 151 declared dependencies are a major version behind. Resolved 31 of 151 against the registry.

Package	Declared	Latest	Behind
`@types/node`	^18.13.0	26.2.0	8 major
`electron`	40.9.1	43.4.0	3 major
`html-loader`	^2.1.2	5.1.0	3 major
`typescript`	^4.7.4	7.0.2	3 major
`webpack-cli`	^4.10.0	7.2.2	3 major
`globals`	^15.12.0	17.11.0	2 major
`@eslint/js`	^9.24.0	10.0.1	1 major
`esbuild-loader`	^3.0.1	4.5.0	1 major

Open in Code Brain → See its neighbourhood →

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high1

medium8

low1

Pin third-party GitHub Actions to a commit SHAhigh11 occurrences

.github/workflows

KSXGitHub/github-actions-deploy-aur@v4.1.2, pozetroninc/github-action-get-latest-release@master, sergeysova/jq-action@v2, ncipollo/release-action@v1

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Declare least-privilege permissions for GITHUB_TOKENmedium2 occurrences

.github/workflows/auto_aur_release_stable.yml

2 workflow(s) declare no permissions, 2 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

2 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium3 occurrences

Dockerfile

node:21, golang:1.25-alpine, alpine:latest (mutable tag)

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Move large binaries to Git LFS or out of the repositorymedium7 occurrences

app/pandoc/pandoc-windows-amd64.zip

7 blobs over 5MB: pandoc-windows-amd64.zip 36.4MB, pandoc-darwin-arm64.zip 34.0MB, pandoc-linux-arm64.zip 33.3MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Set persist-credentials: false on checkoutmedium

.github/workflows/cd.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Expand the test suite; it cannot cover this codebasemedium

1 test files against 622 source files (ratio 0.002)

A reviewer reads "has tests" and assumes a safety net that covers two files out of eighty-five, which is how untested paths ship behind a green badge.

Fix: Add tests for the highest fan-in modules first.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/auto_aur_release_stable.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.

View on GitHub All Projects