Files¶
apps/server stores folders and files and every version of a file. It is a Hono app on Bun
(src/app.ts) over SQLite (bun:sqlite with Drizzle, src/db/schema.ts) and a folder of blobs;
both live in the data folder, so copying that folder backs up everything.
SQLite rather than PostgreSQL: one process and one folder to run, nothing else to install, the
same database the desktop app can use locally, and the same choice as firsttris/sekretaer, which
Schreibzeug is meant to join. While several people edit, their changes go through the relay in memory;
the database sees a save every few seconds, which one writer at a time handles easily.
bun:sqlite is synchronous, so the repository functions are too: a function that does not await
is not interleaved with other requests, and a transaction must not await (src/db/database.ts).
Data¶
| Table | What it holds |
|---|---|
nodes |
Folders and files in one tree (parent_id, null is the root of the owner's files, owner_id whose they are; see accounts). A file has mime, size and its newest version. |
versions |
The saved states of a file, thinned out with age: number, size, the SHA-256 of its bytes, and kept when someone chose to keep it. |
media |
Which image belongs to which file: the file and the SHA-256 of an image put into it while it was edited. |
shares |
Who else may open a node, with edit or view; see accounts. |
invites |
Links that share a node: a random token, the role, when it expires. |
pending_shares |
Shares with an address that has no account yet, taken over at its first sign-in; see accounts. |
access_tokens |
Personal access tokens for MCP clients: only their SHA-256, name, scope, expiry, last use; see the MCP server. |
The bytes are in the blob store (src/blobs.ts), under data/blobs/ab/abcdef… by their SHA-256:
the same bytes are stored once, and a blob is written to a temporary name and renamed, so a crash
never leaves half a blob under a real key. Images put into a document while it is edited go there
too, named after their hash (src/files/media.ts), and media notes the file each one was put
into; once saved, the Office file holds them itself.
Names are unique per folder (at the top level per owner), ignoring case, as on macOS and Windows (a partial unique index on
name_key among nodes outside the trash; the server keeps name_key as the lowercased name, because
SQLite's own lower() only knows ASCII and would let "Übersicht" and "übersicht" stand side by side).
Times are stored as milliseconds. Names must not contain / \ : * ? " < > | or control
characters, so every file can be downloaded under its name on every system
(packages/files-api/src/schemas.ts).
Saving adds a version. Concurrent saves of one file lock its row and get consecutive numbers.
Versions¶
The editor saves a few seconds after each change (AUTOSAVE_DELAY in
packages/editor-core/src/session-progress.ts), so a day's work makes hundreds of versions. After
every save and restore the server thins out the file's older ones (src/files/thinning.ts), as
Nextcloud does:
| Age | What stays |
|---|---|
| up to a day | every version |
| up to 30 days | the newest per hour |
| up to a year | the newest per day |
| older | the newest per week |
The newest version always stays, and so does every version someone chose to keep ("Version
behalten" in the versions dialog, PATCH /files/:id/versions/:number with { "kept": true }, for
those who may edit), and every version saved to an archive: the sent invoice, the signed contract. With SCHREIBZEUG_VERSIONS=all every
version stays (installation).
A thinned-out version's row goes at once; its bytes stay in the blob store until the collection
(src/blob-collection.ts), which runs every six hours and removes the blobs that no version and no
image refers to and that were stored more than an hour ago. A save stores its bytes before it writes
their row, and storing bytes that are already there renews their time, so the collection never takes
the blob of a save under way.
Trash¶
Trashing a node sets trashed_at on it and on everything below it with the same time, and marks it
as trash_root. Everywhere else "not in the trash" is then a single column. The trash lists the
roots; restoring one clears what was trashed with it, while what had been trashed before stays in
the trash. A restore fails when the old folder is itself in the trash or the name has been taken
again.
API¶
All under /api; bodies are JSON unless noted. Every route but /health, /info, Better Auth's
/auth/*, GET /invites/:token and DELETE /sessions (only with a token from Kontext,
Kontext) needs a session or a personal access token and acts for its user (accounts,
MCP server). Errors are
{ "error": { "kind", "message" } }, with kind one of not_found (404), invalid (400),
unauthorized (401), forbidden (403: the role is too weak), not_a_folder (422), name_taken and conflict (409), too_large (413),
internal (500), from POST /files/import also link_expired (410) and upstream_failed (502), and from
POST /files/:id/archive also upstream_failed and upstream_refused (502).
Only the uploads (POST /files, PUT /files/:id/content, POST /files/:id/media, POST /files/:id/archive) take bodies up to
SCHREIBZEUG_MAX_UPLOAD_MB. Better Auth's /auth/* answers a body over 64 KB with 413 before it
reads it, and every other route one over 16 MB (src/limits.ts): Bun's own limit is sized for the
uploads, and Better Auth reads a JSON body whole before it checks who is asking.
Every node in an answer carries role, what the user may do with it: owner, edit or view.
| Route | What it does |
|---|---|
GET /nodes?parent=root\|<id> |
A folder: the folder, its path from the root (for a shared folder, from the folder that was shared), its children (folders first, by name) |
GET /nodes/:id |
One node |
PATCH /nodes/:id |
Rename (name; needs edit and the folder it lies in, sharing) and/or move (parentId, owner only) |
POST /nodes/:id/trash |
Move into the trash |
POST /nodes/:id/restore |
Bring back from the trash |
GET /trash, GET /recent |
What is in the trash; files by last change (both only the user's own) |
GET /storage |
How much room there is, below |
GET /search?q= |
Nodes whose name contains q, ignoring case: the user's own and what lies in or below what is shared with them, files first, at most 50 |
GET /nodes/:id/shares |
Who the node is shared with (owner only) |
PUT /nodes/:id/shares |
Share with the account behind email, or change its role (edit, view) |
DELETE /nodes/:id/shares/:userId |
Take a share back |
GET /shared |
What others shared with the user, with ownerName |
GET /nodes/:id/invites |
The node's links that still hold (owner only) |
POST /nodes/:id/invites |
A new link (role, days: 1, 7 or 30) |
DELETE /nodes/:id/invites/:token |
Delete a link |
GET /invites/:token |
What a link shares (nodeName, kind, ownerName, role, expiresAt); no session needed |
POST /invites/:token/accept |
Accept a link: a share with its role, never weaker than one the user has |
POST /folders |
New folder (parentId, name) |
POST /files |
Upload (multipart: file, optional parentId) |
POST /files/import |
A copy of the file behind another app's link as a new file (url, optional name, parentId), below |
POST /files/blank |
New file (parentId, name, format: docx, xlsx, pptx, or md and txt, which are empty) |
GET /files/:id/content[?version=n] |
The bytes of the newest or a given version, as a download (Content-Disposition: attachment, X-Content-Type-Options: nosniff) |
PUT /files/:id/content |
Save: the body becomes a new version; from a shared session with x-schreibzeug-session-save (409 when that session is gone; the edit role is checked first, so someone without it gets 404/403 whatever the session's state), see collaboration. With If-Match: "<sha256>" only while the newest version's content has that SHA-256, else 409 (the text editor, Markdown and text files); a malformed one is 400 |
GET /files/:id/versions |
All versions, newest first |
POST /files/:id/media |
Store an image put into the file while editing (PNG, JPEG, GIF, BMP, by its first bytes); answers its name, <sha256>.<ext>. Needs edit |
GET /files/:id/media/:name |
That image, for everyone who may see the file; only images put into this file, never another blob by its hash; with X-Content-Type-Options: nosniff |
POST /files/:id/copy |
A copy of the newest version, named "… (Kopie).docx", next to the original when the user may add there, otherwise in their own files |
POST /files/:id/versions/:number/restore |
Make an older version the newest again (as a new version; the ones in between stay) |
PATCH /files/:id/versions/:number |
{ "kept": true } keeps a version from being thinned out, false lets it go again (edit) |
POST /files/:id/archive |
Sends the newest version to the archive as PDF/A and/or the file itself, and keeps it (edit), below |
GET /health |
{ "ok": true } |
GET /info |
{ "mode": "server" }, with oidc: { name } when a sign-in provider is set embedOrigin when a site may frame the app (Kontext) and archive: { name? } when documents can be saved to an archive; the desktop app's local server answers { "mode": "local", "rootName" } (desktop app). No session needed |
More routes, described where they belong:
| Route | Where |
|---|---|
GET /tokens, POST /tokens, DELETE /tokens/:id |
Personal access tokens, only with a session (MCP server) |
POST /files/:id/agent, GET /files/:id/outline |
A job for the open editor (MCP server) |
GET /collab/:fileId (WebSocket) |
The editing session of a file (collaboration) |
GET /agent/:fileId (WebSocket) |
An open editor taking jobs (MCP server) |
DELETE /sessions |
Kontext signs someone out everywhere (Kontext) |
/mcp (outside /api) |
The MCP endpoint (MCP server) |
Storage¶
GET /api/storage answers what the user's own files take and how much room is left
(src/files/storage.ts, src/disk.ts):
usage: the sizes of their versions, split intofiles(the newest version of every file outside the trash),versions(the older ones that thinning left) andtrash(every version of what lies there). These are the files' sizes: the blob store keeps the same bytes once, so the disk may hold less. A shared file counts for its owner.disk:freeandtotalof the drive that holds the data folder (statfs;freeis what an unprivileged process may still write, without the blocks reserved for root), asked anew each time;nullwhen the system does not say. Every signed-in account sees it: they share the drive.uploadLimit:SCHREIBZEUG_MAX_UPLOAD_MBin bytes.
The app shows it at the foot of the navigation (a bar that turns yellow from 80 % and red from
95 %, as Kontext's mailbox ring, and what the user's files take) and in the settings, split as
above (apps/web/src/storage, apps/web/src/settings/storage-section.tsx). With less than 1 GB
free, or less than the upload limit when that is larger, a notice above every file page says that
saves may soon fail (apps/web/src/lib/storage.ts); a share of the drive would not do, as 5 % of
a large one is still plenty. The desktop app's local server answers the same route with the drive
of its folder and no usage, and the app shows only that notice (desktop app).
Opening a file from another app¶
Another app can hand over a file with a link, such as an archive's "Öffnen mit Schreibzeug" button.
It opens /open?url=<link>&name=<file name> in the web app (both URL-encoded); the page asks to
sign in first if needed, has the server fetch the file (POST /api/files/import) and opens the
new file in its editor. Schreibzeug edits a copy in the user's files; the original stays in the
other app. The archive's admin sets the address as https://<schreibzeug>/open?url={url}&name={name}.
The server only fetches links on an origin listed in SCHREIBZEUG_IMPORT_ORIGINS
(installation); without it the route answers 404 and fetches
nothing. A link must be http(s), without user name or password, and on exactly one of those
origins (src/files/import.ts), so nobody can make the server fetch addresses in its own network.
Redirects are not followed. The download may take 60 seconds and at most
SCHREIBZEUG_MAX_UPLOAD_MB, counted as the bytes come, not by Content-Length. Then the file is
stored as an upload is.
The name is name when it is a valid name, else the one in the answer's Content-Disposition,
else "Datei"; a name without a known extension gets the one of the Content-Type. When it is
taken in the folder, the file becomes "Name (2).ext", "Name (3).ext" and so on.
| Answer | When |
|---|---|
201 with the new node |
Stored |
404 not_found |
SCHREIBZEUG_IMPORT_ORIGINS is not set |
403 forbidden |
The link's origin is not allowed |
410 link_expired |
The other app answered 404 or 410: the link has expired or the file was deleted |
413 too_large |
Larger than SCHREIBZEUG_MAX_UPLOAD_MB |
502 upstream_failed |
Not reachable, too slow, a redirect or another error |
Saving to an archive¶
A server can be set up with an archive that keeps finished documents as unalterable originals,
such as a sent offer or a signed contract, e.g. Belegt, a
self-hosted archive for GoBD. Then the "Datei" menu of every editor that can make a PDF (documents,
spreadsheets, presentations, PDFs) has "Im Archiv ablegen …" (In <name> ablegen … with
SCHREIBZEUG_ARCHIVE_NAME) for those who may edit the file. The dialog sends the saved version as
PDF/A, the same the "Als PDF/A herunterladen" item makes
(PDF and printing), and on request the Office file itself;
afterwards it links to each new document in the archive. Changes not saved yet are saved first,
so the archive gets a stored version, and that version is then kept: thinning never
removes what the archive holds.
The browser renders the PDF/A and sends it with the version's number to
POST /api/files/:id/archive (multipart: pdf, original=true, version). The server checks the
PDF lightly (it starts with %PDF-, at most SCHREIBZEUG_MAX_UPLOAD_MB), takes the original from
the blob store, and sends each file as a document of its own to <archive>/api/dokumente
(multipart field datei, Authorization: Bearer <SCHREIBZEUG_ARCHIVE_TOKEN>, 60 seconds each;
src/files/archive.ts). Redirects are not followed, so the token only reaches
SCHREIBZEUG_ARCHIVE_URL; it never goes to the browser, into an answer or into the log. The
archive answers each document with JSON holding its id; its page is
<archive>/dokumente/<id>. The answer to the browser is
{ "version", "documents": [{ "kind": "pdf" | "original", "name", "id", "url" }] }. Each upload is
a new document in the archive, also when the same version goes twice.
Edit is needed rather than view, as the version gets kept. In the archive the token needs the right "schreiben" (write); one that may only read is refused.
| Answer | When |
|---|---|
201 |
In the archive; the version is kept |
400 invalid |
Nothing chosen, or the body is no PDF |
403 forbidden, 404 not_found |
The user may only look at the file, or not at all; 404 also without SCHREIBZEUG_ARCHIVE_URL and _TOKEN |
409 conflict |
Someone saved a newer version in between; archiving again sends that one |
413 too_large |
Larger than SCHREIBZEUG_MAX_UPLOAD_MB, or the archive answered 413 |
502 upstream_refused |
The archive answered 401 or 403: the admin must check the token |
502 upstream_failed |
Not reachable, too slow, a redirect, an answer without id or another error |
When the PDF went and the original then fails, the message says the PDF is in the archive, and the version is kept.
Templates¶
"Neu → Aus Vorlage …" (apps/web/src/files/template-dialog.tsx) starts a file from a template:
- Built in (
packages/ooxml/src/templates.ts): a letter after DIN 5008, an offer, an invoice with what § 14 UStG asks of one, a calculation (formulas for the totals and the tax, euro formats), a project plan and a presentation. They are written as Office XML there; square brackets mark what to fill in. - Own templates: every document, spreadsheet and presentation in a folder named "Vorlagen" at the top of the user's files. Nothing else needs setting up, on a server as on the computer.
The new file is the template's bytes uploaded under the name given (POST /files), so the API
needs nothing of its own for it and an own template stays as it is.
Running it¶
| Variable | Default |
|---|---|
SCHREIBZEUG_DATA_DIR |
data: the database schreibzeug.db, the blobs in blobs/, the generated auth-secret |
PORT |
3000 |
SCHREIBZEUG_MAX_UPLOAD_MB |
512 |
SCHREIBZEUG_IMPORT_ORIGINS |
unset: no file is fetched from a link, above |
SCHREIBZEUG_ARCHIVE_URL, SCHREIBZEUG_ARCHIVE_TOKEN, SCHREIBZEUG_ARCHIVE_NAME |
unset: nothing is saved to an archive, above |
SCHREIBZEUG_OPEN_SIGNUP, SCHREIBZEUG_AUTH_SECRET, SCHREIBZEUG_TRUSTED_ORIGINS, SCHREIBZEUG_TRUSTED_PROXIES |
see accounts |
SCHREIBZEUG_URL, SCHREIBZEUG_EMBED_ORIGIN, OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_NAME |
see Schreibzeug in Kontext |
SCHREIBZEUG_WEB_DIR |
unset: the API only. The built web app (apps/web/dist, after bun run build) to serve beside it, so one address serves the app and the API (every file with X-Content-Type-Options: nosniff, so a browser never takes it for another type); the desktop app opens that address |
The image tristanteu/schreibzeug (docker/Dockerfile) has the server and the built web app with
its engine, with the data in /data (SCHREIBZEUG_WEB_DIR=/app/web, port 3000). Actions →
Release publishes it on Docker Hub and as ghcr.io/speicherstadt/schreibzeug when a v* tag is
pushed; to build it yourself, docker build -f docker/Dockerfile .
(installation).
bun run server starts it with reload; it applies the migrations in apps/server/drizzle on
start. After a change to the schema, bun run --filter @schreibzeug/server db:generate writes the next
migration. drizzle-kit 0.31 quotes the expressions of a SQLite index as column names; check
generated indexes on expressions (as nodes_name_per_parent in 0000_init.sql, fixed by hand).
Tests¶
apps/server/test/files.test.ts signs up an account and runs the app with app.request() and Hono's typed test client
against a real SQLite file: each test file gets a temporary data folder of its own
(test/harness.ts), removed afterwards. Vitest runs on Bun (bun --bun vitest), which bun:sqlite
needs. The E2E server starts on an empty e2e/.data; the screenshots pin their dates in its
database through a small Bun script (e2e/sqlite.ts), since Playwright runs on Node.
apps/server/test/media.test.ts covers images stored while editing, storage.test.ts what
/storage counts, units.test.ts the settings,
names and small helpers. Templates: apps/web/src/files/templates.test.ts (which files count, the
names) and e2e/templates.spec.ts (a file from a built-in and from an own template, opened in its
editor). e2e/files.spec.ts goes through the file list as a person does.
Opening from a link: apps/server/test/import.test.ts against a Bun server on a free port as the
other app (allowed origins, redirects, limits, expired links, names), and e2e/open.spec.ts with
a stand-in archive (e2e/fake-archive.ts), signing in first included. Saving to an archive:
apps/server/test/archive.test.ts against a stand-in archive on a free port (the token only in the
Authorization header and never in an answer or the log, redirects, refused tokens, limits, the
original, the kept version), apps/web/src/editor/archive.test.ts (save first, the steps, the
texts) and e2e/save-to-archive.spec.ts with the same stand-in archive as above (a PDF/A and the
original in the archive, a refused token).