tiag0ss/synapse repository overview

⁠Synapse

Markdown vaults companion to Myelin⁠. Notes live in MySQL; creating notes never creates PM work — push project/task is always an explicit manual action.

This project is a work in progress — bugs may still be found; please report them on GitHub.

⁠Features

• 📔 Markdown vaults — Folder paths (meta/risks), note tree (folders first), vault switcher
• ✏️ Editor — Split/edit/preview, toolbar, paste/drop images + file attachments + lightbox; autosave + unsaved warnings; Ctrl/Cmd+S
• 🖼️ Whiteboards — Excalidraw boards as first-class vault items; maximize to full page; peek / public wiki / share viewers (pan, zoom, background; drawing chrome hidden)
• 🔎 Search — Filter by title/path/body; Jump to note palette (Ctrl/Cmd+O)
• 🔗 Wikilinks & graph — [[links]] (path + unique leaf), tags, backlinks, focused + full mindmap; board→note links show as (board) in References
• 📎 Inline board embeds — ![[Whiteboard title]] embeds a read-only board mid-note (preview, peek, wiki, password share); plain [[Whiteboard]] stays a link
• 🕘 Revisions — History with side-by-side restore
• 📦 ZIP import / export — Nested folders ↔ note paths; images included
• 📋 Templates — Blank, meeting, risk, decision when creating notes
• 🗑️ Trash — Soft-delete notes with restore; leave shared vaults / delete owned vaults
• ✅ Checkbox → PM tasks — Manual create (single or bulk with progress); Synapse pulls PM closed/cancelled status
• 📤 Share note — Password-protected temporary links (/s/:token); Send copy/move to another vault (same Share modal)
• 👁️ Visibility — Vault wiki audience (private / authenticated / unlisted / public) + per-note overrides on /w/:slug
• 🌐 Wiki directory — /w lists wikis you may open (not unlisted); private wikis only if shared with you
• 👥 Vault sharing — Read = wiki only; Edit = vault editor + wiki; invite by search or PM user id
• 🔐 Auth — Local username/password and optional PM SSO (linked by email); password reset via SMTP
• ⚙️ Admin settings — Registration toggle, SMTP, PM integration switch, user management
• 🤖 AI todo suggestions — Optional external Ollama⁠ (Admin → AI); analyzes a note and proposes YAML todos: — review/merge before save; never auto-applies
• 🔌 PM bridge — Per-user SSO token or personal pt_… API key (Profile); manual vault→project link; Synapse refs on PM tasks

⁠Tech Stack

⁠Local Development

1. Create MySQL database and user:

mysql -u root -p < server/database/scripts/bootstrap.sql

That creates DB pm_synapse and user synapse / password change-me-synapse-db-password (edit the SQL first if you want another password).

Or run manually:

CREATE DATABASE IF NOT EXISTS pm_synapse CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER IF NOT EXISTS 'synapse'@'localhost' IDENTIFIED BY 'your-password';
GRANT ALL PRIVILEGES ON pm_synapse.* TO 'synapse'@'localhost';
FLUSH PRIVILEGES;

1. Copy env:

cp .env.example .env

PORT=3010
JWT_SECRET=change-me-synapse-jwt-secret
DB_HOST=localhost
DB_PORT=3306
DB_USER=synapse
DB_PASSWORD=change-me-synapse-db-password
DB_NAME=pm_synapse
PM_BASE_URL=http://localhost:3000
SSO_CLIENT_ID=synapse
SSO_CLIENT_SECRET=change-me-synapse-sso-secret
NEXT_PUBLIC_APP_URL=http://localhost:3010

1. On Myelin (only if using SSO), set:

ALLOWED_SSO_REDIRECTS=http://localhost:3010/api/auth/sso/callback
SSO_CLIENT_ID=synapse
SSO_CLIENT_SECRET=change-me-synapse-sso-secret

1. Install and run (from this folder):

pnpm install --ignore-workspace
pnpm run dev

Open http://localhost:3010⁠ — register a local account (first user becomes admin) and/or sign in with Myelin. Admins manage registration, SMTP, and users under Settings. Each user manages their personal Myelin API token under Profile. Local and SSO accounts with the same email are linked.

Note: TypeScript must stay on 5.x ([email protected]) — Next.js 16 does not support TypeScript 7.

⁠Docker

Build and push (same pattern as Myelin):

cp .env.docker.example .env.docker
# edit secrets + PM_BASE_URL / SSO / NEXT_PUBLIC_APP_URL

sg docker -c "./docker-build.sh"          # or: ./docker-build.sh 0.1.0
DOCKER_USERNAME=youruser docker compose up -d
curl -s http://localhost:3010/health

See DEPLOYMENT.md⁠ for compose ports, volumes, and SSO checklist.

⁠Environment Variables

⁠Ports

⁠Architecture

+---------------------------+          +----------------------------+
|  synapse               |  SSO +   |  myelin        |
|  Next.js + Express :3010 |  REST →  |  Next.js + Express :3000   |
|  MySQL: pm_synapse        |          |  MySQL/MSSQL               |
+---------------------------+          +----------------------------+

Notes and vault ACLs live only in Synapse. Task/project create goes through Myelin’s authenticated APIs with the user’s SSO token.

⁠Wiki visibility

Share Read = wiki only (no vault editor). Share Edit / owner = vault app + wiki. Per-note visibility filters content inside an accessible wiki; private notes are visible on the wiki only to Edit/Owner (not Share Read).

⁠Note syntax (quick)

Password share links: Share… → Link creates /s/:token (password + expiry). Shared notes that embed boards include board JSON in the unlock payload so guests do not need vault API access.

⁠Agent docs

• AGENTS.md⁠ — Cursor / agent entry
• docs/PM_API_CONTRACT.md⁠ — PM HTTP contracts Synapse depends on
• .cursor/rules/ + .github/prompts/ — conventions and task skills

This folder can be moved to its own git repository (synapse) when ready. Keep docs/PM_API_CONTRACT.md in sync whenever Synapse’s PM client changes.

⁠Related

• Myelin⁠ — parent app (SSO + task APIs)