Dockery/Trilium
1
0
Fork 0
mirror of https://github.com/zadam/trilium.git synced 2025-11-07 13:56:11 +01:00
Code Issues Packages Projects Releases Activity

docs(dev): integrate architecture guide

Browse Source
This commit is contained in:
Elian Doran
2025-11-04 17:24:38 +02:00
parent 58ac325634
commit 7369f9d532
14 changed files with 392 additions and 315 deletions
Download Patch File Download Diff File Expand all files Collapse all files

133
docs/Developer Guide/!!!meta.json vendored
View File

@@ -35,6 +35,20 @@
"value": "developer-guide",
"isInheritable": false,
"position": 30
},
{
"type": "relation",
"name": "internalLink",
"value": "T2W7WCZrYZBU",
"isInheritable": false,
"position": 40
},
{
"type": "relation",
"name": "internalLink",
"value": "cxfTSHIUQtt2",
"isInheritable": false,
"position": 50
}
],
"format": "markdown",
@@ -450,14 +464,14 @@
{
"type": "relation",
"name": "internalLink",
"value": "h8AsuFjSD4fB",
"value": "DSkl8C325tEC",
"isInheritable": false,
"position": 10
},
{
"type": "relation",
"name": "internalLink",
"value": "DSkl8C325tEC",
"value": "h8AsuFjSD4fB",
"isInheritable": false,
"position": 20
},
@@ -781,6 +795,60 @@
"format": "markdown",
"dataFileName": "API.md",
"attachments": []
},
{
"isClone": false,
"noteId": "Vk4zD1Iirarg",
"notePath": [
"jdjRLhLV3TtI",
"MhwWMgxwDTZL",
"Vk4zD1Iirarg"
],
"title": "Arhitecture Decision Records",
"notePosition": 40,
"prefix": null,
"isExpanded": false,
"type": "text",
"mime": "text/html",
"attributes": [
{
"type": "relation",
"name": "internalLink",
"value": "Jg7clqogFOyD",
"isInheritable": false,
"position": 20
}
],
"format": "markdown",
"dataFileName": "Arhitecture Decision Records.md",
"attachments": []
},
{
"isClone": false,
"noteId": "QW1MB7RZB5Gf",
"notePath": [
"jdjRLhLV3TtI",
"MhwWMgxwDTZL",
"QW1MB7RZB5Gf"
],
"title": "Security Architecture",
"notePosition": 50,
"prefix": null,
"isExpanded": false,
"type": "text",
"mime": "text/html",
"attributes": [
{
"type": "label",
"name": "shareAlias",
"value": "security-architecture",
"isInheritable": false,
"position": 20
}
],
"format": "markdown",
"dataFileName": "Security Architecture.md",
"attachments": []
}
]
},
@@ -1555,7 +1623,7 @@
"tM3rIZQzlum4"
],
"title": "Deleted notes",
"notePosition": 70,
"notePosition": 50,
"prefix": null,
"isExpanded": false,
"type": "text",
@@ -1589,7 +1657,7 @@
"oLhKpfi2kGON"
],
"title": "Demo document",
"notePosition": 80,
"notePosition": 60,
"prefix": null,
"isExpanded": false,
"type": "text",
@@ -1623,7 +1691,7 @@
"TiUll0Osoaz6"
],
"title": "Entities",
"notePosition": 90,
"notePosition": 70,
"prefix": null,
"isExpanded": false,
"type": "text",
@@ -1657,7 +1725,7 @@
"UzRirf46Xi46"
],
"title": "Hidden notes",
"notePosition": 100,
"notePosition": 80,
"prefix": null,
"isExpanded": false,
"type": "text",
@@ -1691,7 +1759,7 @@
"m2W35hwSDUeh"
],
"title": "Icons",
"notePosition": 110,
"notePosition": 90,
"prefix": null,
"isExpanded": false,
"type": "text",
@@ -1700,14 +1768,14 @@
{
"type": "relation",
"name": "internalLink",
"value": "oLhKpfi2kGON",
"value": "PXzm2t3sCdsP",
"isInheritable": false,
"position": 10
},
{
"type": "relation",
"name": "internalLink",
"value": "PXzm2t3sCdsP",
"value": "oLhKpfi2kGON",
"isInheritable": false,
"position": 20
},
@@ -1732,7 +1800,7 @@
"TLXJwBDo8Rdv"
],
"title": "Internationalisation / Translations",
"notePosition": 120,
"notePosition": 100,
"prefix": null,
"isExpanded": false,
"type": "text",
@@ -1867,7 +1935,7 @@
"Usiyzn9C4WFv"
],
"title": "Launchers",
"notePosition": 130,
"notePosition": 110,
"prefix": null,
"isExpanded": false,
"type": "text",
@@ -1894,7 +1962,7 @@
"qjQNyaYXSNWu"
],
"title": "Note Revisions",
"notePosition": 140,
"notePosition": 120,
"prefix": null,
"isExpanded": false,
"type": "text",
@@ -1928,7 +1996,7 @@
"7RBJMqVz2EsJ"
],
"title": "Note Types",
"notePosition": 150,
"notePosition": 130,
"prefix": null,
"isExpanded": false,
"type": "text",
@@ -2262,7 +2330,7 @@
"6dC7ha5vjqqS"
],
"title": "Options",
"notePosition": 160,
"notePosition": 140,
"prefix": null,
"isExpanded": false,
"type": "text",
@@ -2327,7 +2395,7 @@
"W0msUwLxm40d"
],
"title": "Printing and exporting to PDF",
"notePosition": 170,
"notePosition": 150,
"prefix": null,
"isExpanded": false,
"type": "text",
@@ -2368,7 +2436,7 @@
"UvXpeSqfYc6d"
],
"title": "Protected entities",
"notePosition": 180,
"notePosition": 160,
"prefix": null,
"isExpanded": false,
"type": "text",
@@ -2423,7 +2491,7 @@
"vphziLmQeQHY"
],
"title": "Share",
"notePosition": 190,
"notePosition": 170,
"prefix": null,
"isExpanded": false,
"type": "text",
@@ -2457,7 +2525,7 @@
"n9wYW9nUTynV"
],
"title": "Synchronisation",
"notePosition": 200,
"notePosition": 180,
"prefix": null,
"isExpanded": false,
"type": "text",
@@ -2521,7 +2589,7 @@
"k7RavjuXQt8z"
],
"title": "Syntax highlighting",
"notePosition": 210,
"notePosition": 190,
"prefix": null,
"isExpanded": false,
"type": "text",
@@ -2555,7 +2623,7 @@
"7BCukQTCm7fv"
],
"title": "Themes",
"notePosition": 220,
"notePosition": 200,
"prefix": null,
"isExpanded": false,
"type": "text",
@@ -2712,6 +2780,25 @@
"attachments": [],
"dirFileName": "Testing",
"children": [
{
"isClone": false,
"noteId": "ETeT5YO61DAW",
"notePath": [
"jdjRLhLV3TtI",
"dtKC3FmoWOrv",
"ETeT5YO61DAW"
],
"title": "Unit tests",
"notePosition": 10,
"prefix": null,
"isExpanded": false,
"type": "text",
"mime": "text/html",
"attributes": [],
"format": "markdown",
"dataFileName": "Unit tests.md",
"attachments": []
},
{
"isClone": false,
"noteId": "C5MUQczZ5R9N",
@@ -2721,7 +2808,7 @@
"C5MUQczZ5R9N"
],
"title": "Integration testing",
"notePosition": 10,
"notePosition": 20,
"prefix": null,
"isExpanded": false,
"type": "text",
@@ -2748,7 +2835,7 @@
"bIfKwfCnqpeI"
],
"title": "Test database",
"notePosition": 20,
"notePosition": 30,
"prefix": null,
"isExpanded": false,
"type": "text",
@@ -2775,7 +2862,7 @@
"w6gMvKh0UAVT"
],
"title": "End-to-end tests",
"notePosition": 30,
"notePosition": 40,
"prefix": null,
"isExpanded": false,
"type": "text",

13
docs/Developer Guide/Developer Guide.md vendored
View File

@@ -1,4 +1,15 @@
# Developer Guide
This documentation is intended for developers planning to implement new features or maintain the Trilium Notes application, as it describes the architecture of the application.
For the user-facing documentation, including how to write scripts and the various APIs, consult the [user guide](https://docs.triliumnotes.org/user-guide/) instead.
For the user-facing documentation, including how to write scripts and the various APIs, consult the [user guide](https://docs.triliumnotes.org/user-guide/) instead.
### Quick links
* <a class="reference-link" href="Developer%20Guide/Environment%20Setup.md">Environment Setup</a>
* <a class="reference-link" href="Developer%20Guide/Project%20Structure.md">Project Structure</a>
### External links
* The [Trilium Notes website](https://triliumnotes.org/), for a quick presentation of the application.
* [User Guide](https://docs.triliumnotes.org/user-guide/), to understand the concepts of the application itself.
* [GitHub Repository (TriliumNext/Trilium)](https://github.com/TriliumNext/Trilium/)

7
docs/Developer Guide/Developer Guide/Architecture.md vendored
View File

@@ -15,7 +15,10 @@ Trilium Notes is a hierarchical note-taking application built as a TypeScript mo
* **Runtime**: Node.js (backend), Browser/Electron (frontend)
* **Language**: TypeScript, JavaScript
* **Database**: SQLite (better-sqlite3)
* **Build Tools**: Vite, ESBuild, pnpm
* **Build Tools**:
* Client: Vite,
* Server: ESBuild (bundling)
* Package manager: pnpm
* **UI Framework**: Custom widget-based system (vanilla HTML, CSS & JavaScript + jQuery), in the process of converting to React/Preact.
* **Rich Text**: CKEditor 5 (customized)
* **Code Editing**: CodeMirror 6
@@ -26,7 +29,7 @@ Trilium Notes is a hierarchical note-taking application built as a TypeScript mo
Trilium follows a **client-server architecture** even in desktop mode, where Electron runs both the backend server and frontend client within the same process.
```mermaid
```
graph TB
subgraph Frontend
Widgets[Widgets<br/>System]

2
docs/Developer Guide/Developer Guide/Architecture/API.md vendored
View File

@@ -43,7 +43,7 @@ Located at: `apps/server/src/etapi/`
**Example:**
```sh
```
curl -H "Authorization: YOUR_TOKEN" \
https://trilium.example.com/etapi/notes/noteId
```

62
docs/Developer Guide/Developer Guide/Architecture/Arhitecture Decision Records.md vendored Normal file
View File

@@ -0,0 +1,62 @@
# Arhitecture Decision Records
## 🚀 Future milestones
* [Mobile](https://github.com/TriliumNext/Trilium/issues/7447)
* [Multi-user](https://github.com/TriliumNext/Trilium/issues/4956)
## Aug 2025 - present: Port the client to React
- [x] [Type widgets](https://github.com/TriliumNext/Trilium/pull/7044)
- [x] [Collections](https://github.com/TriliumNext/Trilium/pull/6837)
- [x] [Various widgets](https://github.com/TriliumNext/Trilium/pull/6830)
- [x] [Floating buttons](https://github.com/TriliumNext/Trilium/pull/6811)
- [x] [Settings](https://github.com/TriliumNext/Trilium/pull/6660)
## Aug 2025 - Move away from NX
We took the decision of moving away from the NX monorepo tool, due to:
* Various issues with the cache, especially after an update of the NX dependencies which required periodical `nx reset` to get rid of.
* Various issues with memory and CPU consumption along the way, due to the NX daemon (including it remaining as a background process after closing the IDE).
* On Windows, almost always there was a freeze on every second build.
* Various hacks that were needed to achieve what we needed (especially for artifacts since NX would not copy assets if they were in `.gitignore` for some arbitrary reason and requiring a patch that made it difficult to maintain across updates).
As a result, we decided to switch to… nothing. Why?
* `pnpm` (which we were already using) covers the basic needs of a monorepo via workspaces on its own.
* Our client-side solution, Vite already supports navigating through projects without requiring built artifacts. This makes the build process slightly faster (especially cold starts) at a slighter bigger RAM consumption.
* ESBuild, on the server-side, also seems happy to go across projects without an issue.
Apart from this:
* In dev mode, the server now runs directly using `tsx` and not built and then run. This means that it'll run much faster.
* We're back to an architecture where the `server` and the `desktop` host their own Vite instance as a middleware. What this means that there is no `client:dev` and no separate port to handle.
* This makes it possible to easily test on mobile in dev mode, since there's a single port to access.
* The downside is that the initial start up time is longer while Vite is spinning up. Nevertheless, it's still slightly faster than it used to be anyway.
* No more asset copying, which should also improve performance.
* No more messing around with the native dependency of `better-sqlite3` that caused those dreaded mismatches when running between server and desktop. We have (hopefully) found a permanent solution for it that involves no user input.
* A decent solution was put in place to allow easier development on NixOS for the desktop application.
* The desktop version has also gained back the ability to automatically refresh the client when a change is made, including live changes for React components.
Migration steps, as a developer:
1. In VS Code, uninstall the NX Console unless you plan to use it for other projects.
2. Remove `.nx` at project level.
3. It's ideal to clean up all your `node_modules` in the project (do note that it's not just the top-level one, but also in `apps/client`, `apps/server`, `apps/desktop`, etc.).
4. Run a `pnpm i` to set up the new dependencies and the installation
5. Instead of `nx run server:serve`, now you can simply run `pnpm dev` while in `apps/server`, or `pnpm server:start` while in the root.
6. When first starting the server, it will take slightly longer than usual to see something on the screen since the dependencies are being rebuilt. Those are later cached so subsequent runs should work better. If you end up with a white screen, simply refresh the page a few times until it shows up correctly.
## Apr 2025: NX-based monorepo
* Goal: Restructure the application from a mix where the client was a subfolder within the server and other dependencies such as <a class="reference-link" href="../Dependencies/CKEditor.md">CKEditor</a> were scattered in various repositories to a monorepo powered by NX.
* [Initial discussion](https://github.com/TriliumNext/Trilium/issues/4941)
* [Relevant PR](https://github.com/TriliumNext/Notes/pull/1773)
## Dec 2024: Front-end conversion to TypeScript
* [Relevant PRs on GitHub](https://github.com/TriliumNext/Notes/pulls?q=is%3Apr+is%3Aclosed+%22Port+frontend+to+TypeScript%22)
## Apr 2024: Back-end conversion to TypeScript
* [Relevant PRs on GitHub](https://github.com/TriliumNext/Notes/pulls?q=is%3Apr+%22convert+backend+to+typescript%22)

79
docs/Developer Guide/Developer Guide/Architecture/Security Architecture.md vendored Normal file
View File

@@ -0,0 +1,79 @@
# Security Architecture
### Encryption System
**Per-Note Encryption:**
* Notes can be individually protected
* AES-128-CBC encryption for encrypted notes.
* Separate protected session management
**Protected Session:**
* Time-limited access to protected notes
* Automatic timeout
* Re-authentication required
* Frontend: `protected_session.ts`
* Backend: `protected_session.ts`
### Authentication
**Password Auth:**
* PBKDF2 key derivation
* Salt per installation
* Hash verification
**OpenID Connect:**
* External identity provider support
* OAuth 2.0 flow
* Configurable providers
**TOTP (2FA):**
* Time-based one-time passwords
* QR code setup
* Backup codes
### Authorization
**Single-User Model:**
* Desktop: single user (owner)
* Server: single user per installation
**Share Notes:**
* Public access without authentication
* Separate Shaca cache
* Read-only access
### CSRF Protection
**CSRF Tokens:**
* Required for state-changing operations
* Token in header or cookie
* Validation middleware
### Input Sanitization
**XSS Prevention:**
* DOMPurify for HTML sanitization
* CKEditor content filtering
* CSP headers
**SQL Injection:**
* Parameterized queries only
* Better-sqlite3 prepared statements
* No string concatenation in SQL
### Dependency Security
**Vulnerability Scanning:**
* Renovate bot for updates
* npm audit integration
* Override vulnerable sub-dependencies

2
docs/Developer Guide/Developer Guide/Concepts/Entities.md vendored
View File

@@ -3,7 +3,7 @@
Trilium's data model is based on five core entities:
```mermaid
```
graph TD
Note[Note<br/>BNote]
Branch[Branch<br/>BBranch]

2
docs/Developer Guide/Developer Guide/Documentation.md vendored
View File

@@ -1,5 +1,5 @@
# Documentation
There are multiple types of documentation for Trilium:<img class="image-style-align-right" src="api/images/GUwY9NTWQZlI/Documentation_image.png" width="205" height="162">
There are multiple types of documentation for Trilium:<img class="image-style-align-right" src="api/images/45okJ9xpVO32/Documentation_image.png" width="205" height="162">
* The _User Guide_ represents the user-facing documentation. This documentation can be browsed by users directly from within Trilium, by pressing <kbd>F1</kbd>.
* The _Developer's Guide_ represents a set of Markdown documents that present the internals of Trilium, for developers.

46
docs/Developer Guide/Developer Guide/Testing.md vendored
View File

@@ -1,4 +1,48 @@
# Testing
### Test Organization
**Parallel Tests** (can run simultaneously):
* Client tests
* Package tests
* E2E tests (isolated databases)
**Sequential Tests** (shared resources):
* Server tests (shared database)
* CKEditor plugin tests
### Test Frameworks
* **Vitest** - Unit and integration tests
* **Playwright** - E2E tests
* **Happy-DOM** - DOM testing environment
## Test locations
```
apps/
├── server/
│ └── src/**/*.spec.ts # Server tests
├── client/
│ └── src/**/*.spec.ts # Client tests
└── server-e2e/
│ └── tests/**/*.spec.ts # E2E tests
└── desktop/
└── e2e
└── tests/**/*.spec.ts # E2E tests
```
## Running tests
At project root:
```
pnpm test:all # All tests
pnpm test:parallel # Fast parallel tests
pnpm test:sequential # Sequential tests only
```
## Unit testing and integration testing
Using `vitest`, there are some unit and integration tests done for both the client and the server.
@@ -27,4 +71,4 @@ These integration tests are run alongside unit tests.
## End-to-end testing
See <a class="reference-link" href="Testing/End-to-end%20tests.md">e2e tests</a>.
See <a class="reference-link" href="Testing/End-to-end%20tests.md">End-to-end tests</a>.

13
docs/Developer Guide/Developer Guide/Testing/End-to-end tests.md vendored
View File

@@ -1,6 +1,15 @@
# End-to-end tests
* This tests both the client and the server, by running the server and then using Playwright to query the state of the page.
* These can be found in `apps/server-e2e` and `apps/desktop/e2e`.
**Server E2E:**
* Tests the entire ETAPI.
* Tests WebSocket functionality
**Desktop E2E:**
* Playwright with Electron
* Tests some basic functionality such as creating a new document.
These can be found in `apps/server-e2e` and `apps/desktop/e2e`.
## First-time run

7
docs/Developer Guide/Developer Guide/Testing/Unit tests.md vendored Normal file
View File

@@ -0,0 +1,7 @@
# Unit tests
At project level:
* `pnpm server:test`
* `pnpm client:test`
Unit tests are stored in the same directory as the source code being tested, with the `.spec.ts` suffix.