Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

docs(storage): document local persistence layout (#612)

XZH5ae3f9a4eb5a
diff --git a/README.md b/README.md
index 57e6ece07..733828460 100644
--- a/README.md
+++ b/README.md
@@ -268,7 +268,7 @@ with the access URL and the results of your checks.
The [Agent Setup guide](docs-for-user/AGENT_SETUP.md) covers the full flow, including non-interactive CLI configuration. To install it yourself, choose one of the paths below.
-DeepTutor ships four installation paths. They all share one runtime-home layout: private settings live in `data/user/settings/` under the directory you launch from (or under `DEEPTUTOR_HOME` / `deeptutor start --home` if you set one explicitly). For the full app, the recommended flow is **pick a runtime-home directory → install → `deeptutor init` → `deeptutor start`**.
+DeepTutor ships four installation paths. They all share one runtime-home layout: private settings live in `data/user/settings/` under the directory you launch from (or under `DEEPTUTOR_HOME` / `deeptutor start --home` if you set one explicitly). See [Local Data Persistence](./docs-for-user/DATA_STORAGE.md) for the complete storage layout, database support, and backup notes. For the full app, the recommended flow is **pick a runtime-home directory → install → `deeptutor init` → `deeptutor start`**.
### One-Command Docker Trial
diff --git a/docs-for-user/DATA_STORAGE.md b/docs-for-user/DATA_STORAGE.md
new file mode 100644
index 000000000..00e42103e
--- /dev/null
+++ b/docs-for-user/DATA_STORAGE.md
@@ -0,0 +1,75 @@
+# Local Data Persistence
+
+DeepTutor's default installation does not require PostgreSQL, MySQL, or another
+database server. Durable state is written below one runtime-home directory, so
+a deployment has one tree to mount, inspect, and back up. Some state is stored
+in SQLite, while settings, generated artifacts, knowledge-base indexes, caches,
+and imported source files remain ordinary files.
+
+## Where Data Lives
+
+The runtime home is the directory from which you start DeepTutor. Set
+`DEEPTUTOR_HOME` or pass `deeptutor start --home` / `deeptutor init --home` to
+choose another directory. In the published container, the same tree is mounted
+at `/app/data`.
+
+The default admin scope uses this layout:
+
+| Path | Contents |
+| --- | --- |
+| `data/user/settings/` | JSON/YAML settings and provider credentials |
+| `data/user/chat_history.db` | SQLite sessions, messages, turns, notebook, and practice data |
+| `data/user/.runtime/` | Private runtime state such as `workspaces.sqlite3` |
+| `data/user/workspace/` | Default Content Workspace and generated artifacts |
+| `data/user/logs/` | Application logs |
+| `data/knowledge_bases/` | Knowledge-base indexes and versioned source data |
+| `data/parse_cache/` | Shared document-parse cache |
+| `data/users/<user-id>/` | Per-user workspace roots when local multi-user auth is enabled |
+| `data/partners/<partner-id>/` | Synthetic Partner workspaces |
+| `data/system/` | Accounts, grants, audit records, indexes, and owner credentials |
+
+A selected Content Workspace can be outside `data/user`. In that case its
+private learning state is under `<workspace>/.deeptutor/data/`, while account
+settings, credentials, Memory, and workspace registrations remain in the
+runtime home. Run `deeptutor workspace show` to print the selected workspace
+path.
+
+## Database Support
+
+SQLite is the supported local backend. There is no supported PostgreSQL or
+MySQL connection setting; setting `DATABASE_URL` or a similar environment
+variable does not redirect DeepTutor storage.
+
+PocketBase is an optional integration configured through
+`data/user/settings/integrations.json`. It stores supported session collections
+in PocketBase, but it is not a PostgreSQL adapter and does not move all runtime
+state into PocketBase. Settings, credentials, knowledge-base indexes, parse
+caches, logs, and workspace artifacts remain in the runtime tree. Current
+PocketBase mode is single-user; leave `integrations.pocketbase_url` blank for
+the supported local multi-user JSON/SQLite layout.
+
+## Inspecting and Backing Up State
+
+From your runtime home, after DeepTutor has created data, list the SQLite
+databases in the private runtime tree:
+
+```bash
+find data -type f \( -name '*.db' -o -name '*.sqlite3' \) -print
+```
+
+For a selected external Content Workspace, inspect its private database files:
+
+```bash
+workspace="$(deeptutor workspace show | sed -n 's/^Path: //p')"
+if [ -d "$workspace/.deeptutor/data" ]; then
+ find "$workspace/.deeptutor/data" -type f \
+ \( -name '*.db' -o -name '*.sqlite3' \) -print
+fi
+```
+
+Stop DeepTutor and any Partner processes before copying `data` or a workspace.
+SQLite may have live write-ahead log files, so copying only `.db` files while
+the app runs can lose recent transactions. Back up the complete runtime-home
+`data` directory plus each separately configured Content Workspace. Treat every
+copy as sensitive because it can contain credentials, private conversation
+text, and uploaded learning material.