Desktop Architecture

🖥️ Desktop Architecture & IPC Bridge

VisualMark Studio is designed as a native Code + Visual desktop IDE (modeled after VS Code and modern desktop developer tools) using Electron, React 18, and an embedded Python FastAPI sidecar daemon.

---

🏛️ System Architecture Overview

┌──────────────────────────────────────────────────────────────────┐
│                   VisualMark Studio Desktop Window               │
│                                                                  │
│  [✦ VisualMark Studio]  [File ▾]   [⌘K Search]    [─] [□] [✕]    │
│  ├────────────────────────────────────────────────────────────┤  │
│  │                                                            │  │
│  │   React + Vite UI (Frameless Custom Titlebar & Studios)    │  │
│  │   - Direct Disk Read/Write (Ctrl+S, Ctrl+O)                │  │
│  │   - Local Folder Workspace Browser (Ctrl+Shift+O)          │  │
│  │                                                            │  │
│  └────────────────────────────────────────────────────────────┘  │
│                                │                                 │
│                         IPC Bridge                               │
│                                │                                 │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │               Electron Main Process (Node.js)              │  │
│  │   - Native file dialogs & disk streaming                   │  │
│  │   - Window minimize / maximize / close                     │  │
│  │   - Sidecar process manager & lifecycle hooks              │  │
│  └────────────────────────────────────────────────────────────┘  │
└────────────────────────────────┼─────────────────────────────────┘
                                 │ HTTP (http://127.0.0.1:8000..8030)
                                 │ Dynamic port negotiation & fallback
┌────────────────────────────────┴─────────────────────────────────┐
│            Standalone Python FastAPI Daemon (server.exe)         │
│  - Frozen via PyInstaller (runs without Python pre-installed)    │
│  - Conflict-resilient port binding (--port <activePort>)         │
│  - Deep AST scanning, multi-file suites & documentation AI       │
└──────────────────────────────────────────────────────────────────┘

---

🔌 1. The Electron IPC Bridge

Because modern web security restricts browser windows from arbitrarily reading and writing files to local disk, the Electron Main Process serves as a secure bridge exposing safe APIs via contextBridge in preload.js:

IPC Channel	Purpose	Direction
read-file	Reads file content directly from local filesystem	Renderer $\rightarrow$ Main
write-file	Saves active document to local filesystem	Renderer $\rightarrow$ Main
select-file	Opens native OS file picker dialog	Renderer $\rightarrow$ Main
select-folder	Opens native OS directory picker dialog	Renderer $\rightarrow$ Main
get-backend-url	Returns the negotiated Python sidecar URL	Renderer $\rightarrow$ Main
window-minimize	Minimizes desktop window	Renderer $\rightarrow$ Main
window-maximize	Toggles maximized / restored state	Renderer $\rightarrow$ Main
window-close	Gracefully closes application and stops sidecar	Renderer $\rightarrow$ Main

---

⚡ 2. Dynamic Port Negotiation (8000–8030)

In developer workstations, port 8000 is frequently occupied by other local servers (e.g. Docker, Django, or other microservices).

To prevent startup crashes:

1. When Electron initializes, it probes ports sequentially from 8000 through 8030.
2. If it discovers an active VisualMark backend (by checking /health), it binds to it immediately.
3. If no backend is running, Electron selects the first available free port and spawns the Python sidecar daemon passing --port <port>.
4. The negotiated URL is pushed to the React UI via get-backend-url, ensuring zero connection errors.

---

🧊 3. Standalone Frozen Sidecar (server.exe)

When packaged for distribution:

• The Python backend is frozen into a self-contained executable (server.exe) using PyInstaller.
• End users do not need Python installed on their machines.
• Electron manages the sidecar's lifecycle: spawning it silently on launch and terminating the process when the window closes.

---

🔒 4. Local-First & Zero Telemetry Philosophy

VisualMark Studio does not transmit your source code, documentation, or file paths to external servers:

• All AST parsing, Markdown linting, and diagram generation execute locally on your hardware.
• External network requests are restricted to public badge fetching (Shields.io) and optional SSRF-sanitized image previews.
• No telemetry, analytics, or behavioral trackers are included in the binaries.

---

Return to Home or continue to 12 Visual Studios Guide.