Study Route Framework

English | 简体中文

Study Route is a personal, local-first learning execution system with Markdown as its source of truth. Version 3 replaces the old flat goals/routes/plans/logs taxonomy with a deliberate hierarchy:

Direction
  └─ Project or course
      ├─ Milestones / knowledge points
      ├─ Unified tasks
      ├─ Reusable learning routes
      ├─ Exams
      └─ Resources

All work units → global week plan → Today queue → daily evidence → global week review

Product model

• The primary navigation contains Today / Directions / Courses / Week Review; courses can be opened from a direction or browsed directly.
• Today shows one explainable recommendation, at most five queued tasks, and deadlines within 14 days.
• Projects progress through milestones and acceptance criteria; courses progress through knowledge points, mastery, and evidence.
• Exams belong to courses. A learning route can support several work units in the same direction.
• Every task competes for capacity in one global week plan. Overload is visible but may be saved intentionally.
• AI produces auditable drafts only. Every core workflow remains available without AI.

Quick start

npm.cmd install
npm.cmd run dev

Development runs at http://127.0.0.1:5173. Without STUDY_ROUTE_DATA_DIR, the schema 3 workspace in demo-data/ is used.

Multi-user authentication is enabled by default. For a local-only demo that is not exposed to the network, explicitly set STUDY_ROUTE_AUTH_DISABLED=true before npm run dev. To test real authentication locally, set APP_DATA_ROOT, run npm run admin -- create --username admin, and then start the development server.

For private data:

$env:STUDY_ROUTE_DATA_DIR='D:\path\to\my-study-route'
npm.cmd run cli -- init
npm.cmd run dev

Workspace schema 3

directions/  projects/  courses/  routes/
week-plans/  daily-logs/  week-reviews/
resources/   exams/      inbox/   templates/
attachments/ .study-route/

Entities and tasks use stable IDs; relationships are never inferred from titles or paths. Schema 0–2 workspaces are not migrated automatically. Their files remain untouched and the app asks the user to select or create a schema 3 workspace.

Readable entity IDs can be confirmed or changed during creation. A later ID change creates backups and cascades structured references across directions, courses, logs, and linked work units. The Directions page lists projects and courses whose direction reference is missing or invalid so they can be reassigned without searching the filesystem.

Web Git workspace

The Git area in the sidebar opens the /git workspace. A data directory can be initialized with one click. Once enabled, the page separates staged, unstaged, and untracked files; shows working-tree and staged diffs; stages or unstages selected paths; commits either staged content or a complete learning snapshot; browses commit history; and safely restores historical files into the working tree for review and a new commit.

The web UI exposes a fixed set of local Git operations. It does not provide arbitrary commands, history rewriting, branch merging, or remote pull / push. New repositories ignore .backups/ and .trash/. Local Git helps recover mistakes but is not an off-site disaster backup.

CLI

npm.cmd run cli -- init
npm.cmd run cli -- today
npm.cmd run cli -- directions
npm.cmd run cli -- create-direction --title "Career"
npm.cmd run cli -- inbox --title "Unsorted note" --content "..."
npm.cmd run cli -- week-plan --week 2026-W29 --capacity 12 --task "task:id|2|2026-07-18"
npm.cmd run cli -- review --week 2026-W29 --conclusion "..."
npm.cmd run cli -- health
npm.cmd run cli -- doctor

Validation

npm.cmd run typecheck
npm.cmd test
npm.cmd run build
npm.cmd run test:e2e

Workspace AI settings never store secrets. Attachments remain inside the active data root, and path safety, backups, Git snapshots, and auditable AI diffs remain part of the framework.

Private multi-user deployment

The production server supports invitation-only accounts backed by SQLite. Each user gets an isolated schema 3 Markdown workspace, attachment tree, drafts, and Git repository. Public registration and email delivery are intentionally not included.

cp .env.example .env
# Set DOMAIN and generate STUDY_ROUTE_SESSION_SECRET with: openssl rand -base64 48
mkdir -p data
sudo chown 1000:1000 data
docker compose up -d --build
docker compose run --rm -e STUDY_ROUTE_ADMIN_PASSWORD='a password-manager generated password' app \
  npm run admin -- create --username admin --display-name 'Administrator'

Caddy terminates HTTPS and the Node port remains private to the Compose network. Persistent state is stored under data/system/study-route.sqlite and data/users/<uuid>/workspace/.

GitHub Actions deployment

The repository includes .github/workflows/deploy.yml. After Continuous Integration succeeds for a push to the default branch, it connects over SSH, checks out the exact tested commit on the server, and rebuilds the Compose services. It can also be started manually. Pull requests neither run the deployment job nor receive its secrets.

Complete the initial deployment on the server first. The deployment user must be able to read the repository, write to its deployment directory, and run Docker Compose. Keep the server's .env and data/ in that directory and outside Git; CI never reads or transfers them, so DOMAIN, the session secret, and AI keys remain server-only.

Create a production environment under Settings → Environments and add these environment secrets:

Secret	Value
DEPLOY_SSH_HOST	Server IP address or SSH hostname
DEPLOY_SSH_PORT	SSH port, such as 22
DEPLOY_SSH_USER	Dedicated deployment user
DEPLOY_SSH_PRIVATE_KEY	Dedicated SSH private key for that user
DEPLOY_SSH_KNOWN_HOSTS	Verified SSH host-key record for the server
DEPLOY_PATH	Absolute server repository path, such as /opt/study-route

Generate the host-key record from a trusted terminal with a command such as ssh-keyscan -H -p <port> <server>, then independently verify its fingerprint through the cloud console or directly on the server before saving it. Do not automatically accept a new host key. A dedicated deployment key and required reviewers on the production environment are recommended. GitHub masks complete secret values in logs, but Actions debug logging and scripts that print environment variables should still remain disabled.

Only the secret names above are public. Their values are not committed, and no domain secret is needed because Caddy continues to read DOMAIN from the server-local .env.

Existing schema 3 data can be checked and imported without modifying the source:

npm run admin -- import-workspace --username admin --source /path/to/workspace
npm run admin -- import-workspace --username admin --source /path/to/workspace --apply

If the source contains .git, its history is preserved. AI is disabled by default and keys remain server environment variables. Per-user Git repositories provide readable history and rollback, but local Git on the same server is not an off-site disaster backup; back up the entire data/ directory separately if that risk policy changes.

Instance-specific footer content, such as regulatory registration information, can be configured after deployment from User management → Custom footer HTML. The value is stored in SQLite rather than source control. Only a, span, strong, em, and br are rendered; scripts, images, inline styles, event handlers, and non-HTTP(S) links are removed.

License: GPL-3.0-only.