Getting Started

🚀 Getting Started & Local Development

This guide provides step-by-step instructions for cloning, setting up, running, and debugging VisualMark Studio on your local development machine.

---

📋 System Requirements

Hardware & OS

• Operating System: Windows 10/11 (64-bit recommended), macOS 11+, or Linux (Ubuntu 20.04+)
• RAM: 4 GB minimum (8 GB recommended)
• Storage: 1.5 GB free disk space (includes Node modules, Python packages, and Electron cache)

Software Prerequisites

1. Node.js: v18.0.0 or higher (v20 LTS recommended)

   node --version && npm --version

2. Python: 3.10 or higher (3.11 recommended)

   python --version

3. Git: 2.30 or higher

   git --version

---

📥 1. Clone the Repository

Clone the repository and enter the project directory:

git clone https://github.com/JagaTheGhost/visualmark-studio.git
cd visualmark-studio

---

🐍 2. Backend Setup (FastAPI Sidecar)

The backend provides repository AST scanning, tech stack discovery, documentation template generation, and an SSRF-safe image proxy.

Step 1: Navigate to Backend

cd backend

Step 2: Create & Activate Virtual Environment

Windows (PowerShell):

python -m venv venv
.\venv\Scripts\activate

macOS / Linux:

python3 -m venv venv
source venv/bin/activate

Step 3: Install Dependencies

pip install --upgrade pip
pip install -r requirements.txt

Step 4: Verify Backend Health (Optional)

Run the development FastAPI server:

python main.py

Open http://localhost:8000/docs in your browser to inspect interactive Swagger API documentation. Press Ctrl + C to stop.

---

⚛️ 3. Frontend Setup (React + Electron)

Navigate to the frontend/ directory and install the required npm dependencies:

cd ../frontend
npm install

---

🖥️ 4. Running VisualMark Studio

Option A: Desktop Mode (Recommended)

Launches the Vite dev server and the Electron desktop application concurrently:

npm run electron:dev

• What happens behind the scenes:
  1. Vite starts the React dev server on http://localhost:3000.
  2. Electron performs port negotiation (probing ports 8000 through 8030).
  3. If no backend is running, Electron automatically launches the Python daemon.
  4. The custom frameless Obsidian-themed desktop window opens with full native disk I/O.

Option B: Web Browser Mode

If you only need to work on the UI components inside a standard browser:

npm run dev

Open http://localhost:3000 in your browser.

---

🔧 Troubleshooting Guide

Port 8000 Already in Use

• Resolution: Electron automatically handles port conflicts by testing ports up to 8030. If running manually, specify the port:

  python main.py --port 8005

Electron Window Fails to Load Frontend

• Cause: The Vite dev server did not finish starting before Electron tried to load http://localhost:3000.
• Resolution: Wait 3 seconds and press Ctrl + R inside the Electron window to reload, or check the terminal output for Vite compilation errors.

Python Sidecar Execution Policy on Windows

• Error: Execution of scripts is disabled on this system when activating venv.
• Resolution: Run PowerShell as Administrator and execute:

  Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

---

Return to Home or continue to Desktop Architecture.