Synapse Framework — Project Overview

Reference map for contributors and agents working in this repository.

What this project is

Synapse Framework is a Windows-focused Tauri 2 desktop app that recreates and extends classic Synapse executor UIs. It provides:

• A Luau script editor (Monaco)
• Script Hub (ScriptBlox catalog + legacy embedded scripts)
• Console (F9 logs from executor)
• A local executor bridge on 127.0.0.1:31337 with three HTTP methods — Port (Fastest), Stream, and Compat — each with a Lua client and Rust queue. See EXECUTOR_BRIDGE.md.
• An extensible plugin system (JS modules, overlays, bridge providers). See PLUGINS.md.
• Four UI shells selectable via settings (uiMode)

This is not a web backend, monorepo, or authenticated SaaS. Persistence uses localStorage, IndexedDB, and Tauri filesystem JSON — there is no SQL/ORM.

flowchart TB
  subgraph desktop [Synapse Framework]
    React["React/Vite src/"]
    Rust["Rust src-tauri/"]
    Axum["Axum bridge :31337"]
  end
  Executor["Executor Luau client (Port / Stream / Compat)"] <-->|HTTP :31337| Axum
  React <-->|Tauri IPC invoke| Rust
  Rust --> Axum
  ScriptBlox["scriptblox.com"] -->|dev proxy /scriptblox-api path| React

Repository layout

Not in repo (as of this doc): root tsconfig.json, ESLint/Prettier config, .env files, CI workflows, Docker, automated tests.

Tech stack

Entry points and boot flow

Frontend bootstrap — src/main.tsx

1. Tauri detection → adds synapse-tauri class, sets window background from theme
2. Normalizes /index.html → / (Tauri asset protocol quirk)
3. applyAlternateShellBootPathFromSettings() — sync redirect to /synapse-original/*, /synapse-x/*, or /synapse-v3/* before React paints
4. Persists app_settings_snapshot.json via persist_app_settings_snapshot for Rust cold-start routing
5. Global contextmenu suppression (except Monaco, Radix menus)
6. Renders src/app/App.tsx

Routing — src/app/routes.tsx

altShellBootRedirectLoader catches edge cases where persisted uiMode does not match the URL.

Rust bootstrap — src-tauri/src/main.rs → lib.rs

• Reads app_settings_snapshot.json before webview paint to open the correct initial window route
• Spawns the Axum server on 127.0.0.1:31337 — Port (/port_bridge/*), Stream (/stream_bridge/*), Compat (/compat_bridge/*), script downloads, and per-method liveness watchdogs
• Registers all Tauri IPC commands

Tauri IPC commands

UI shells and settings

Settings: src/app/appSettings.ts

• Storage key: synapse.appSettings.v1
• uiMode: "default" | "synapseOriginal" | "synapseX" | "synapseV3"
• Bridge transport: bridgeMethod: "port" | "stream" | "compat" (Settings labels: Fastest / Stream / Compatible). Legacy "websocket" migrates to "port".
• Other flags: autoAttach, confirmations, resizable window, alwaysOnTop, minimap, error logging, edge curves per shell, integrated webpage URL

Theming: src/ui/shellTheme.ts — CSS vars, IndexedDB media (synapse-original-shell-media), per-shell keys.

Core feature modules

Editor

• src/editor/ScriptMonacoEditor.tsx — Monaco mount
• src/editor/luauLanguage.ts — language registration
• src/editor/synapseIntellisense.ts — completions
• src/editor/synapseDiagnostics.ts — luaparse markers
• Tab/workspace: src/app/editorWorkspace/ (EditorWorkspaceContext)
• Disk I/O: src/app/scripts/editorDiskScripts.ts

Executor bridge

Axum listener on 127.0.0.1:31337 serves three HTTP bridge methods. Full protocol: EXECUTOR_BRIDGE.md.

Plugins

App-wide JS extensions loaded on the main webview. Full guide: PLUGINS.md.

Script Hub

• src/app/scriptHub/scriptBloxApi.ts — ScriptBlox fetch layer (dev proxied in vite.config.ts as /scriptblox-api)
• src/app/scriptHub/synapseLegacyScripts.ts — embedded legacy URLs

Integrated webpage

• src/app/integratedSiteWebview.ts — secondary native webview (bypasses iframe limits)

Data persistence

Dev and build commands

npm install
npm run dev          # Vite @ http://127.0.0.1:5173 (browser only)
npm run tauri:dev    # Full desktop (needs VS DevCmd on Windows)
npm run build        # vite build → dist/
npm run tauri:build  # MSI installer

• Port cleanup: scripts/ensure-dev-port.mjs (5173/4173)
• Tauri auto-runs npm run dev / npm run build via src-tauri/tauri.conf.json hooks

Key files quick reference

Working on this codebase

1. Identify which UI shell and route are affected
2. Decide whether logic belongs in React, Tauri IPC, or bridge.rs
3. Respect boot-path synchronization between main.tsx, routes.tsx, and Rust boot_window_config
4. Bridge protocols live in src-tauri/src/{port,stream,compat}_bridge.rs and matching * Bridge.lua scripts
5. Plugin changes may require Restart Framework — see PLUGINS.md

Gaps and conventions

• No automated tests in the main app
• No CI/CD — builds are local MSI only
• No root tsconfig — Vite transpiles TS without strict project config
• Figma heritage — src/imports/ SVG path modules; npm package name @figma/my-make-file
• Auth: none; Synapse X shell is explicitly UI-only
• Synapse V3 is partially integrated (single main route; many dormant components)

Optional future improvements

Not required for day-to-day development; add when explicitly requested:

• Root tsconfig.json for stricter TypeScript checking
• Vitest or similar test runner
• GitHub Actions CI for npm run build and cargo test