---

Table of Contents

• Quick Start
  • 5-Minute Setup (Tauri Web App)
  • Python CLI (Hydra-driven backend)
  • Python PySide6 Desktop GUI
  • Tauri + TypeScript Web App
  • Analytics & Interpretability Dashboard
  • Mobile Apps (Android / iOS)
  • Benchmarking Suite & Utility Scripts
• Features
• Installation & Setup
  • Install from a Release (Desktop App)
  • Build from Source (Development)
• Running the Application
• CLI Commands Reference
• Usage
• Build
• Testing
• Troubleshooting
• Advanced Configuration
• Development Workflow
• Documentation
• Security Notes
• Project Implementation Notes
• Common Tasks Quick Reference

---

🚀 Quick Start

Prerequisites Check

# Check if you have the required tools
rustc --version  # Should be 1.70+
node --version   # Should be 18+
psql --version   # Should be 14+
python3 --version # Should be 3.11+

5-Minute Setup

Step 1: Database Setup (2 minutes)

# Install pgvector (if not already installed)
cd /tmp
git clone https://github.com/pgvector/pgvector.git
cd pgvector
make && sudo make install

# Create database
sudo -u postgres psql << 'EOF'
CREATE DATABASE image_toolkit;
CREATE USER toolkit_user WITH PASSWORD 'change_me_123';
GRANT ALL PRIVILEGES ON DATABASE image_toolkit TO toolkit_user;
\c image_toolkit
CREATE EXTENSION vector;
ALTER DATABASE image_toolkit OWNER TO toolkit_user;
EOF

Step 2: Configure Environment (1 minute)

cd frontend/src-tauri

# Create .env file
cat > .env << 'EOF'
DATABASE_URL=postgresql://toolkit_user:change_me_123@localhost:5432/image_toolkit
RUST_LOG=info
EOF

Step 3: Install Dependencies (1 minute)

# From project root
npm run setup

Step 4: Run the Application (1 minute)

Option 1: Quick Run Script (Recommended)

./run.sh

Option 2: Using npm

npm run dev

Option 3: Using Make

make dev

Option 4: From frontend directory

cd frontend
npm run tauri dev

First time? This will take a few minutes to compile Rust dependencies.

Step 5: Create Your Account

1. Application launches → Login dialog appears
2. Click "Create New Account"
3. Enter account name (e.g., "MyAccount")
4. Set a master password
5. Click "Create Account"

You're done! ✅

After login, you should see:

• ✅ Green "DB Connected" in the header
• Navigation tabs on the left
• Convert tab open by default

---

Python CLI (Hydra-driven backend)

The Python backend exposes a Hydra-configured CLI entry point for training pipelines, embedding generation, and ComfyUI headless orchestration.

Prerequisites: Python venv activated (see Installation & Setup).

source .venv/bin/activate

# Run training pipeline (uses configs/base.yaml by default)
python -m backend.dispatcher command=train

# Generate safetensors metadata embeddings
python -m backend.dispatcher command=embed_metadata

# Launch ComfyUI headlessly with a custom port
python -m backend.dispatcher command=comfyui comfyui.port=8188 comfyui.listen=127.0.0.1

# Override any config key from the CLI (standard Hydra syntax)
python -m backend.dispatcher command=train training.batch_size=16 training.epochs=50

# Batch image conversion via the main CLI
python backend/main.py convert --output_format png --input_path /path/to/images --input_formats webp avif

Config files live in backend/config/. Override any key with key=value on the command line. backend/config/asp_config.toml configures the Anime Stitch Pipeline — see backend/src/animation/config.py for the schema.

---

Python PySide6 Desktop GUI

The legacy Qt-based desktop application provides a full feature set including the gallery, stitch tab, wallpaper manager, and crawlers.

Prerequisites: Python venv activated, PostgreSQL running, base C++ module built (just build-base).

source .venv/bin/activate

# Launch the GUI
python backend/main.py

# Or via the justfile
just python

On first launch, the login dialog will appear — create an account or log in with an existing one. The header bar shows a green "DB Connected" indicator when the PostgreSQL connection is healthy.

Critical constraints (do not violate):

• All heavy operations run off the main thread (QThread / QRunnable). Never block the event loop.
• Never use QWebEngineView. Open external URLs via QDesktopServices.openUrl().
• All QFileDialog calls must pass QFileDialog.Option.DontUseNativeDialog to avoid GTK/JVM SIGSEGV.

---

Tauri + TypeScript Web App

The primary cross-platform interface is built with React 19 + Tauri (Rust backend). This is the recommended environment for most users.

Prerequisites: Node 18+, Rust 1.70+, PostgreSQL running with pgvector, .env configured in frontend/src-tauri/.

# One-command setup and launch (recommended for first run)
./run.sh

# Or with npm from the project root
npm run setup   # first time only
npm run dev

# Or from the frontend directory
cd frontend && npm run tauri dev

The first build compiles the Rust backend — expect 5–10 minutes on a cold cache. Subsequent runs are fast due to incremental compilation.

Production build:

npm run build
# Bundles to: frontend/src-tauri/target/release/bundle/

---

Analytics & Interpretability Dashboard

The analytics dashboard is the React/TypeScript tab inside the Tauri app, implemented in frontend/src/tabs/analytics/. It provides SVG-based visualisations of benchmark results, ASP pipeline diagnostics, and model interpretability metrics.

Prerequisites: Same as the Tauri web app above. The Electron mode also works for a standalone window.

# Run in Tauri dev mode (dashboard is the Analytics tab)
npm run dev

# Run in Electron mode (standalone window, faster React hot-reload)
cd frontend
npm run electron-dev

# Build as standalone Electron app
npm run start-electron

The dashboard reads benchmark JSON outputs from backend/benchmark/results/. Run the benchmark suite first to populate data:

source .venv/bin/activate
python backend/benchmark/run_all.py

Then open the Analytics tab in the running app to see the results.

---

Mobile Apps (Android / iOS)

Android (Kotlin / Jetpack Compose)

Prerequisites: Android Studio, JDK 17+, Android SDK.

cd app

# Debug build (installs to connected device or emulator)
./gradlew assembleDebug
./gradlew installDebug

# Release build
./gradlew assembleRelease

# Run unit tests
./gradlew test

# Run instrumented tests (requires connected device)
./gradlew connectedAndroidTest

The app connects to the same PostgreSQL backend. Set the server URL in app/src/main/res/values/config.xml or via the in-app settings screen.

iOS (Swift / SwiftUI)

Prerequisites: Xcode 15+, macOS, Apple Developer account for device builds.

cd app

# Build for simulator
xcodebuild -project ImageToolkit.xcodeproj -scheme ImageToolkit -destination 'platform=iOS Simulator,name=iPhone 15' build

# Run on a connected device (requires signing)
xcodebuild -project ImageToolkit.xcodeproj -scheme ImageToolkit -destination 'generic/platform=iOS' build

# Run unit tests
xcodebuild test -project ImageToolkit.xcodeproj -scheme ImageToolkit -destination 'platform=iOS Simulator,name=iPhone 15'

---

Benchmarking Suite & Utility Scripts

ASP Benchmark (Anime Stitch Pipeline quality regression)

source .venv/bin/activate

# Run the full 97-test benchmark corpus
python backend/benchmark/run_all.py

# Run with baseline comparison (fails if metrics regress)
python backend/benchmark/run_all.py --baseline backend/benchmark/results/baseline/

# Run a single test by ID
python backend/benchmark/run_single.py --test-id 09

# Safe animation test suite (no GPU, no heavy model imports)
pytest backend/test/animation/ --skip-gpu

Rust criterion micro-benchmarks

cd base
cargo bench

# Run a specific benchmark group
cargo bench -- linalg

Frontend math module benchmarks

cd frontend
npx ts-node src/math/benchmark.ts

Utility scripts

# Batch image conversion helper
bash desktop/linux/cli/convert_images.sh

# Environment setup / dependency sync
bash desktop/linux/scripts/setup_env.sh

# Check module import times (validates <1.5s threshold for all animation modules)
source .venv/bin/activate
python backend/src/utils/check_import_times.py

---

✨ Features

Core Capabilities

• 🖼️ Image Database - PostgreSQL with pgvector for semantic search
• 🔍 Advanced Search - Filter by tags, groups, formats, and visual similarity
• 🔄 Batch Processing - Convert, merge, and manipulate images in bulk
• 🖥️ Wallpaper Manager - KDE/GNOME wallpaper automation with slideshow
• 🎬 Video Tools - Extract frames and clips from videos
• 🌐 Web Integration - Image crawlers, reverse search, cloud sync
• 🤖 AI Models - Training, inference, and generation pipelines

Tech Stack

• Frontend: React + TypeScript + Tauri
• Backend: C++ (pybind11) + Python
• Database: PostgreSQL + pgvector
• Legacy GUI: PySide6
• Mobile: Kotlin (Android) + Swift (iOS)

---

📦 Installation & Setup

Install from a Release (Desktop App)

Prebuilt Linux desktop bundles are published on the GitHub Releases page: an AppImage and a .deb package. A native Windows build is also available as a zip archive; see docs/INSTALL.md.

# Linux AppImage
chmod +x ImageToolkit-*-x86_64.AppImage
./ImageToolkit-*-x86_64.AppImage

# Debian / Ubuntu
sudo dpkg -i image-toolkit_*_amd64.deb   # launches as `image-toolkit` or from the app menu

Database prerequisite: vector similarity search, anime training pipelines, and legacy migration need an external PostgreSQL 14+ with the pgvector extension (≥ 0.5.0) — it is not bundled. The app runs without it on local encrypted (SQLCipher) storage and disables only those features. Full setup (automated just db-setup, manual SQL, DATABASE_URL) is in docs/INSTALL.md.

Scope note: the release ships the PySide6 desktop app only. The web frontend (React/Electron), browser extension, mobile apps, and Django API are not yet part of a release — build them from source as described below.

Build from Source (Development)

System Requirements

All Platforms

• Rust (1.70+)
• Node.js (18+) and npm
• PostgreSQL (14+) with pgvector extension
• Python (3.11+) for backend modules

Linux

sudo apt update
sudo apt install -y build-essential curl wget libssl-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev binutils qdbus-qt6 qt6-base-dev-tools

macOS

# Install Xcode Command Line Tools
xcode-select --install

Windows

• Install Visual Studio C++ Build Tools
• Install WebView2

Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Verify installation:

rustc --version
cargo --version

Install Node.js Dependencies

From project root (recommended):

npm run setup
# This installs all dependencies including TypeScript types

Or manually:

npm install
cd frontend
npm install
cd ..
npm install --save-dev @types/react-dom

Setup PostgreSQL with pgvector

Install PostgreSQL

Ubuntu/Debian:

sudo apt install postgresql postgresql-contrib

macOS (Homebrew):

brew install postgresql@14
brew services start postgresql@14

Windows: Download and install from PostgreSQL Downloads

Install pgvector Extension

From Source:

cd /tmp
git clone --branch v0.5.0 https://github.com/pgvector/pgvector.git
cd pgvector
make
sudo make install

macOS (Homebrew):

brew install pgvector

Create Database and Enable Extension

# Start PostgreSQL service (if not running)
sudo systemctl start postgresql  # Linux
# or
brew services start postgresql@14  # macOS

# Create database and user
sudo -u postgres psql << EOF
CREATE DATABASE image_toolkit;
CREATE USER toolkit_user WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE image_toolkit TO toolkit_user;
\c image_toolkit
CREATE EXTENSION IF NOT EXISTS vector;
ALTER DATABASE image_toolkit OWNER TO toolkit_user;
EOF

Configure Environment Variables

# Copy example environment file
cd frontend/src-tauri
cp .env.example .env

# Edit .env and update with your database credentials
nano .env

Update DATABASE_URL in .env:

DATABASE_URL=postgresql://toolkit_user:your_secure_password@localhost:5432/image_toolkit
RUST_LOG=info

Setup Python Environment (for backend modules)

UV

To use the UV Python package and project manager to setup the virtual environment:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create environment
uv init --python 3.11 --name image-toolkit

# Install dependencies
uv add -r env/requirements.txt
uv add --dev env/dev_requirements.txt

# Or just sync
uv sync

Afterwards, initialize the virtual environment:

source .venv/bin/activate  # Linux/macOS
# or
.venv\Scripts\activate.bat  # Windows CMD
# or
.venv\Scripts\Activate.ps1  # Windows PS

Anaconda Environment

To setup using Anaconda distribution:

conda env create --file env/environment.yml -y --name img_db
conda activate img_db

To list installed packages:

conda list

To deactivate/delete:

conda deactivate
conda remove -n img_db --all -y

Virtual Environment

Using Pip and Python's venv module:

python3 -m venv env/.img_db
source env/.img_db/bin/activate
pip install -r env/requirements.txt

List packages:

pip list

Deactivate/delete:

deactivate
rm -rf env/.img_db

Setup C++ Dependencies

sudo apt install libgtest-dev libopencv-dev libxext-dev libxt-dev libxrender-dev libpqxx-dev libgumbo-dev nlohmann-json3-dev libcxxopts-dev

---

🛠️ Running the Application

Development Mode

From project root (any of these methods):

Option 1: Quick Run Script (Recommended)

./run.sh

This script will:

• Check for .env file (create from template if missing)
• Verify dependencies are installed
• Test database connection
• Start the development server

Option 2: Using npm

npm run dev

Option 3: Using Make

make dev

Option 4: From frontend directory (traditional)

cd frontend
npm run tauri dev

All methods will:

1. Start the React development server
2. Compile the Rust backend
3. Launch the application window
4. Enable hot-reload for frontend changes

Production Build

From project root:

npm run build
# or
make build

From frontend directory:

cd frontend
npm run tauri build

The compiled application will be in:

• Linux: frontend/src-tauri/target/release/bundle/
• macOS: frontend/src-tauri/target/release/bundle/macos/
• Windows: frontend/src-tauri/target/release/bundle/msi/

Legacy PySide6 GUI

source .venv/bin/activate
python backend/main.py
# or: make python-dev

---

📝 CLI Commands Reference

All commands can be run from the project root directory.

Quick Commands

Setup & Installation

Complete Setup:

npm run setup

• Installs all dependencies (root + frontend workspace)
• Installs TypeScript types
• One command to get everything ready

Individual Steps:

npm run install:all        # Install all dependencies
npm install                 # Install root dependencies only
npm install --workspace=frontend   # Install frontend dependencies only

Using Make:

make setup      # Complete setup
make install    # Install dependencies only

Development Commands

Start Development Server:

# Any of these work:
./run.sh        # Recommended - checks everything first
npm run dev
make dev

# Traditional way (from frontend dir):
cd frontend && npm run tauri dev

Build for Production:

npm run build
# or
make build

# Output will be in:
# Linux:   frontend/src-tauri/target/release/bundle/
# macOS:   frontend/src-tauri/target/release/bundle/macos/
# Windows: frontend/src-tauri/target/release/bundle/msi/

Type Checking:

npm run tauri:check
# or
make check

Testing

Run All Tests:

npm test
# or
make test

Frontend Tests Only:

npm run test-frontend

Rust Tests Only:

cd frontend/src-tauri && cargo test

Python Tests:

pytest

Database Commands

Setup Database (PostgreSQL + pgvector):

make db-setup

This creates:

• Database: image_toolkit
• User: toolkit_user
• Password: change_me_123 (change this!)
• Enables pgvector extension

Check Database Connection:

make db-check

Run Migrations:

make db-migrate

Manual Database Connection:

psql postgresql://toolkit_user:password@localhost:5432/image_toolkit

Cleanup

Clean Build Artifacts:

make clean

Removes:

• frontend/dist
• frontend/build
• frontend/src-tauri/target
• node_modules

Format Code:

make format

Formats both Rust and TypeScript code.

npm Scripts Reference

All scripts from package.json:

Make Commands Reference

Run make help for a full list. Common commands:

---

💻 Usage

Before you start the program, you must initialize the PostgreSQL Database by running one of the following commands:

• On the Linux CLI: sudo systemctl start postgresql
• On the Windows CMD: net start postgresql-x64-18
• On the macOS Terminal: brew services start postgresql

Afterwards, you can stop the Database by running one of the following commands:

• On the Linux CLI: sudo systemctl stop postgresql
• On the Windows CMD: net stop postgresql-x64-18
• On the macOS Terminal: brew services stop postgresql

After installing PostgreSQL, you can use the psql -U postgres -d img_db command to connect to the database (and exit to leave it).

Note: You also need to install pgvector from the official GitHub in order to access full database functionality.

Convert Image Format

You can either convert a single image at a time:

python backend/main.py convert --output_format png --input_path <path_to_img> --output_path <path_new_img>

or batch convert all images in a directory that match one (or more) image formats:

python backend/main.py convert --output_format png --input_path <path_to_dir> --input_formats webp avif --output_path <path_new_dir>

Note: If no --output_path argument is given, the new image will have the same name (or the images will be generated in the same directory, in the case of batch conversion), just with a different file extension.

First Time Application Setup

Create Your Account

When you first launch the application:

1. You'll see the login dialog
2. Click "Create New Account"
3. Enter your desired account name
4. Set a master password (this encrypts your vault)
5. Click "Create Account"

Important: The master password cannot be recovered if lost!

Verify Database Connection

After logging in, check the header bar:

• ✅ Green "DB Connected" - Everything is working
• ❌ Red "DB Offline" - Check your PostgreSQL setup and .env configuration

Configure Settings

Click the ⚙️ Settings button to:

• Choose your theme (Light/Dark/System)
• Create system preference profiles
• Change your master password

Application Features

• Add Images: Use the "Scan" tab to import images into the database
• Search Images: Use the "Search" tab with filters (tags, groups, formats)
• Convert Images: Use the "Convert" tab for batch format conversion
• Set Wallpaper: Use the "Wallpaper" tab for desktop wallpaper management

---

🔨 Build

Tauri Application

Production build:

npm run build
# or from frontend:
cd frontend && npm run tauri build

Platform-specific builds:

Linux AppImage:

npm run build
# Output: frontend/src-tauri/target/release/bundle/appimage/

macOS DMG:

npm run build
# Output: frontend/src-tauri/target/release/bundle/macos/

Windows MSI:

npm run build
# Output: frontend/src-tauri/target/release/bundle/msi/

Python Application

To build the desktop app part of the project:

pyinstaller --clean app.spec

Core and Web (C++)

To build the core and web parts of the project:

mkdir build
cd build
cmake ..
cmake --build . --clean-first
make

Mobile

Android:

cd app
./gradlew assembleDebug

iOS:

cd app
xcodebuild -project ImageToolkit.xcodeproj -scheme ImageToolkit build

---

🧪 Testing

Frontend Tests

cd frontend
npm test

Backend Tests

cd frontend/src-tauri
cargo test

Python Tests

pytest

Java Tests

To test the Java portion of the project:

mvn test

Integration Tests

# Start app in test mode
DATABASE_URL=postgresql://localhost/test_db cargo run

---

🐛 Troubleshooting

Common Issues

"DB Offline" in header

# Check PostgreSQL is running
sudo systemctl status postgresql

# Test connection manually
psql postgresql://toolkit_user:change_me_123@localhost:5432/image_toolkit

Database Connection Failed

Error: Failed to connect to PostgreSQL database

Solutions:

1. Verify PostgreSQL is running:

   sudo systemctl status postgresql  # Linux
   brew services list  # macOS
   

2. Check your .env file has correct credentials

3. Test connection manually:

   psql postgresql://toolkit_user:password@localhost:5432/image_toolkit
   

4. Ensure pgvector extension is installed:

   \c image_toolkit
   SELECT * FROM pg_extension WHERE extname = 'vector';
   

Build fails with OpenSSL errors

# Linux
sudo apt install libssl-dev pkg-config

# macOS
brew install openssl@3

TypeScript Build Errors

Error: Cannot find module 'react-dom/client'

Solution:

cd frontend
npm install --save-dev @types/react-dom

Rust Compilation Errors

Error: failed to run custom build command for 'openssl-sys'

Solution (Linux):

sudo apt install libssl-dev pkg-config

Solution (macOS):

brew install openssl@3

Python Backend Issues

Error: ModuleNotFoundError: No module named 'base'

Solution:

# Build the C++ pybind11 extension
just build-base

Tauri Build Fails

Error: webkit2gtk-4.1 not found

Solution (Linux):

sudo apt install libwebkit2gtk-4.1-dev

Verify Dependencies

# Check if dependencies are installed
ls node_modules/@types/react-dom   # Should exist
ls frontend/node_modules           # Should exist

# Verify Rust toolchain
rustc --version
cargo --version

# Check Tauri dependencies (Linux)
dpkg -l | grep -E "webkit2gtk|libssl-dev|build-essential"

---

⚙️ Advanced Configuration

Custom Database Host

If using a remote PostgreSQL server:

DATABASE_URL=postgresql://user:[email protected]:5432/image_toolkit

Performance Tuning

For large image collections (100k+ images):

1. Increase PostgreSQL connection pool:

   // In frontend/src-tauri/src/db.rs
   PgPoolOptions::new()
       .max_connections(20)  // Increase from default 5
   

2. Adjust PostgreSQL settings (/etc/postgresql/14/main/postgresql.conf):

   shared_buffers = 256MB
   effective_cache_size = 1GB
   maintenance_work_mem = 128MB
   

Enable Debug Logging

RUST_LOG=debug
RUST_BACKTRACE=full

Then check logs:

# Development mode - logs to terminal
npm run tauri dev

# Production - logs to:
# Linux: ~/.config/image-toolkit/logs/
# macOS: ~/Library/Logs/image-toolkit/
# Windows: %APPDATA%\image-toolkit\logs\

Environment Variables

Required Variables:

Create frontend/src-tauri/.env from template:

cp frontend/src-tauri/.env.example frontend/src-tauri/.env

Edit and set:

DATABASE_URL=postgresql://user:password@localhost:5432/image_toolkit

Optional Variables:

RUST_LOG=info          # Log level (debug, info, warn, error)
RUST_BACKTRACE=1       # Enable stack traces

---

🔄 Development Workflow

Hot Reload

The development server supports hot reload:

• Frontend (React): Changes auto-reload in browser
• Backend (Rust): Requires manual restart (Ctrl+C then re-run)

Database Migrations

To create a new migration:

cd frontend/src-tauri
sqlx migrate add <migration_name>

Edit the generated SQL file in migrations/, then run:

sqlx migrate run

Adding New Tauri Commands

1. Create command in appropriate module (e.g., src/database_commands.rs)
2. Add to invoke_handler! in src/lib.rs
3. Call from frontend using invoke('command_name', { params })

Typical Development Session

1. Start fresh:

   ./run.sh
   

2. Make changes:

   • Frontend changes auto-reload
   • Rust changes require restart (Ctrl+C, then ./run.sh again)

3. Run tests:

   npm test
   

4. Build for production:

   npm run build
   

Quick Iteration

# Terminal 1: Keep dev server running
npm run dev

# Terminal 2: Run tests on changes
npm test -- --watch

---

📚 Documentation

• CLAUDE.md - Architecture and development guidelines for AI coding assistants
• GEMINI.md - Project instructions for Gemini

Documentation Website

The docs/website directory is a Vue-powered interactive site that renders every Markdown page under docs/ (roadmap, changelog, research, tutorials, API references, and the linked submodule sites). It's an npm workspace, so it can be launched from the repo root:

# One-time setup (installs the root, frontend, and docs/website workspaces)
npm run install:all

# Start the docs site in dev mode (hot reload) at http://localhost:5173
npm run docs-website:dev

# Build the static site to docs/website/dist/
npm run docs-website:build

# Preview a production build locally
npm run docs-website:preview

The same site is what's deployed to GitHub Pages by .github/workflows/docs.yml on every push to main.

---

🔒 Security Notes

1. VaultManager: Credentials are encrypted with AES-256-GCM
2. Master Password: Never stored anywhere - only used for encryption
3. Database: Store sensitive data in environment variables, not in code
4. IPC Security: Tauri validates all frontend-backend communication
5. NEVER hardcode credentials - use .env files and VaultManager

---

📖 Project Implementation Notes

Root Command System

The project supports multiple ways to run the application from the project root:

Method 1: Quick Run Script (Best for beginners)

./run.sh

Method 2: Using npm (Best for CI/CD)

npm run setup    # One-time
npm run dev      # Every time

Method 3: Using Make (Best for developers)

make setup       # One-time
make dev         # Every time

Method 4: Traditional (Still works)

cd frontend
npm run tauri dev

Workspace Configuration

The root package.json uses npm workspaces to manage the frontend:

{
  "workspaces": ["frontend"]
}

This allows commands like:

npm run tauri dev --workspace=frontend

Smart Run Script

The run.sh script includes:

• Environment file checking
• Dependency verification
• Database connection testing
• Color-coded output
• Interactive prompts

Benefits

For New Users:

• ✅ One command to get started: ./run.sh
• ✅ Automatic setup checks and helpful error messages
• ✅ No need to remember complex paths
• ✅ Works from anywhere in the project

For Developers:

• ✅ Faster workflow (no cd-ing around)
• ✅ Make commands for common tasks
• ✅ Consistent command structure
• ✅ Easy integration with scripts/CI

---

🎯 Common Tasks Quick Reference

Just want to try it out?

./run.sh

Need to setup from scratch?

make setup
make db-setup
npm run dev

Building for distribution?

npm run build

Database not working?

make db-check
# If fails: make db-setup

Clean slate?

make clean
npm run setup

---

Last Updated: 2026-01-13

For help: Run make help or npm run to see all available commands.

License

This project is dual-licensed under an open-core model:

• Open source (free) — GNU AGPL-3.0. Free to use, modify, and distribute for hobbyists, students, researchers, non-profits, and any other use that complies with the AGPL-3.0's copyleft and network source-disclosure terms.
• Commercial (paid). For proprietary, closed-source, or SaaS use that can't comply with the AGPL's obligations, a paid commercial license is available — contact ACFHarbinger [email protected] for pricing and terms.