Architecture

NOTE

This project recommends discussing requirements and direction through an issue before submitting a pull request.

For new features, behavior changes, or larger refactors, please open an issue first and describe the problem being solved, the use case, and the expected outcome. This helps confirm whether the change fits the project direction before implementation begins.

Pull requests are very welcome for issues with confirmed scope, clear bug fixes, documentation improvements, and technical challenges that have already been discussed. Unsolicited feature PRs may not be merged if they do not align with the project direction.

This project uses a hybrid architecture with a C++23 native backend and a Vue 3 web frontend. For the full design philosophy, component breakdown, and dependency graph, check the root-level AGENTS.md.

Prerequisites

The C++ backend defaults to clang-cl[llvm] (Clang + LLD) for daily development. Release builds use MSVC.

Tool	Requirement	Notes
Visual Studio 2026 / LLVM	Includes C++ and Clang (clang-cl) toolchains
Windows SDK	10.0.22621.0+ (Windows 11 SDK)
Git	Latest	Clone vcpkg and fetch third-party dependencies
xmake	3.1.0	C++ build system
Node.js	v22.13+	Web frontend build and pnpm scripts
JDK	21+	Compile the Android DEX service for ADB mode
Android SDK Command-line Tools	Platform 36 + Build Tools 36.0.0	Build the capture service with javac/d8

Install xmake

# PowerShell (recommended)
irm https://xmake.io/psget.text | iex

# Or download from the official site
# https://xmake.io/#/getting_started?id=installation

Set up vcpkg

git clone https://github.com/microsoft/vcpkg.git D:\dev\vcpkg  # path is up to you
cd D:\dev\vcpkg
.\bootstrap-vcpkg.bat
.\vcpkg.exe integrate install

---

Dependency Setup

1. Third-party dependencies

pnpm run fetch:third-party

2. pnpm dependencies

# Install root and all workspace dependencies
pnpm install

3. Initialize xmake dependencies and apply patches

node scripts/patch-xmake-clang-cl-cxx23.js
node scripts/patch-xmake-clang-cl-deps.js

# Clang-cl + LLD (default)
xmake f --toolchain="clang-cl[llvm]" -y

# Or use MSVC
# xmake f --toolchain=msvc -y

xmake f -m release -y && xmake f -m debug -y
node scripts/patch-vcpkg.js

4. Fetch Android capture service (optional)

If you don't modify the Java code under android/capture/src/, you don't need JDK or Android SDK. Just pull the prebuilt jar from the latest release:

pnpm run fetch:android-jar

After that, pnpm run build automatically skips the Android compilation. To rebuild from source, delete build/android/.android-jar-fetched.

---

Visual Studio Development (Optional)

To browse, edit, and debug the C++ code in Visual Studio, generate an Xmake-managed solution:

xmake vs

Then open:

vsxmake2026\SpinningMomo.sln

Build

TIP

If you encounter environment, dependency, or toolchain issues during local setup, you can refer to the Build Release Workflow for an up-to-date, automated reference build procedure.

Full Build (Recommended)

# One command: C++ Release + Web frontend + Android capture service + assemble dist/
pnpm run build

Output goes to dist/.

Step-by-Step

# C++ backend — Debug (daily development)
xmake config -m debug
xmake build

# C++ backend — Release
xmake release    # automatically restores debug config after release build

# Web frontend
pnpm run build:web

# Android capture service (optional, requires JDK + Android SDK)
pnpm run build:android

# Assemble dist/ (exe + web resources + Android jar)
pnpm run build:dist

Android Capture Service

The Android side is a lightweight screen/audio capture service. Its artifact is build/android/momo-capture.jar, pushed via ADB and run by app_process — no APK installation needed.

When modifying Java code, set up JDK 21 and Android SDK (platforms;android-36, build-tools;36.0.0), then run pnpm run build:android. Dependency versions are in android/capture/build-config.json.

Build Output Paths

Type	Path
Debug	build\windows\x64\debug\
Release	build\windows\x64\release\
Packaged	dist\

Testing

Tests only protect deterministic, stable behavior and documented invariants — coverage is not the goal.

Unit Tests

Backend regression tests use doctest and are carried by the separate SpinningMomoTests target:

xmake test -v

This target is not part of a regular build. If the test executable is reported missing, run xmake build SpinningMomoTests first.

Scenario Tests

Scenario tests launch a real SpinningMomo process and call JSON-RPC over the HTTP /rpc port to verify end-to-end behavior. They run inside a portable sandbox under a temporary directory, with the database, settings, and thumbnails all kept in the sandbox, leaving your everyday instance untouched. Release artifacts are verified by default.

Scenario scripts do not build anything, so prepare the Release artifacts first:

xmake config -m release
xmake build
xmake build SpinningMomoScenarioWindow    # scenario target window for screenshots and recording
xmake config -m debug                     # optional, back to your daily dev config
pnpm run test:scenarios                   # add a suite name substring to filter, e.g. gallery_core

Suites are gallery_core, gallery_recovery, and capture. Exit any running SpinningMomo instance first — RPC port 51206 must be free.

GPU encoders and audio devices vary between machines, so capture and recording behavior on specific hardware still needs manual verification by running the app.

Packaging

Portable (ZIP)

pnpm run build:portable

MSI Installer

Requires WiX Toolset v6:

dotnet tool install --global wix --version 6.0.2
wix extension add WixToolset.UI.wixext/6.0.2 --global
wix extension add WixToolset.BootstrapperApplications.wixext/6.0.2 --global

Then run:

pnpm run build:installer

Web Frontend Development

Start the dev server (C++ backend needs to be running):

pnpm run dev:web

Vite dev server proxies /rpc and /static to the C++ backend (localhost:51206).

Code Generation Scripts

Re-run these when their source files change:

What changed	Run this script
src/migrations/*.sql	node scripts/generate-migrations.js
src/locales/*.json	node scripts/generate-embedded-locales.js