> ## Documentation Index
> Fetch the complete documentation index at: https://docs.docwriter.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> Understand the server owned document and agent edit flow.

## Server owned documents

Each open text tab has a Yjs document owned by the Hocuspocus server. Browsers are synchronized clients. Server tools that change an open tab use a Hocuspocus direct connection to the same document.

## Persistence

Every Yjs update is appended to SQLite with the original transaction origin. The server also flushes the serialized plain text to the workspace file.

The `yjs_updates` table stores each raw update in the `payload` column. The `tabs` table keeps tab order and the active tab. Other tables store rules, reviewers, recent actions, usage counts, provider session entries, and conversation events. The `kv` table stores values such as `sessionId`, `agentSettings`, and each tab's `last_seen` text.

Comments and review rounds live inside the tab Yjs document, so they arrive in the same synchronized update stream as text. There is no JSON state mirror.

The server flushes serialized text to the workspace file for Git and portability. Serialization removes AI provenance formatting and keeps the source text unchanged.

## Agent flow

The render route streams one provider query over server sent events. The prompt names open tabs and includes changes since each tab was last seen. The agent calls `read_doc` when it needs full content.

`edit_doc` changes the live Yjs document and adds a pending review round in one transaction. Hocuspocus sends that update to every connected browser.

The document tool server routes open tab paths through a Hocuspocus direct connection. Scratch paths use normal file operations under `.docwriter/agent/scratch/`. A server mutation must never use a replayed temporary Yjs document because the temporary document is not connected to live clients.

The stream emits tool start, tool result, assistant text, and final result events. The browser uses the events for the agent dock, while document content continues through WebSocket synchronization.

## Review flow

Accept and reject requests run on the live server document. Accept applies a bounded paragraph edit and removes the review round. Reject removes the round without replaying a client side merge.

The client undo manager tracks user typing and user origin review actions. Agent origin transactions are excluded.

Accept uses the edit operation saved with the review round. It deletes and reinserts only the affected paragraphs when possible. A full write operation can replace the whole document when no bounded edit exists.

The browser sends Accept and Reject to `/api/document`, then waits for the Yjs update from the server. It does not disconnect or perform a separate three way merge.

## External file reconciliation

When a tab is opened, the server replays the saved Yjs updates. A newer disk file with different content can replace an older update log after the modification time check. Watch mode sends a reload event, and the browser remounts the active Yjs client from the server.

Each server process has an instance identifier. After a restart, the browser discards clients created for the old process before opening new WebSocket connections.

## Shared origins

`AGENT_ORIGIN`, `USER_ORIGIN`, and `SYSTEM_ORIGIN` are shared constants. Do not redefine them in client or server modules.