# Architecture

This section is for developers who want to extend Exaplay 3, integrate with it, or build it from source.

## System Overview

```
┌─────────────────────────────────────────────────────────────────────┐
│                         Exaplay 3                                   │
│                                                                     │
│  ┌────────────────────┐  HTTP / WS  ┌─────────────────────────┐    │
│  │   Vue 3 SPA        │◄───────────►│   C++ Engine            │    │
│  │   (Frontend)       │             │   (exaplay-sdk)         │    │
│  │                    │             │                         │    │
│  │  • Editor UI       │             │  • OpenGL rendering     │    │
│  │  • Operator UI     │             │  • Media decode         │    │
│  │  • User Panel      │             │  • Audio (ASIO)         │    │
│  └────────┬───────────┘             │  • Network protocols    │    │
│           │ HTTP / WS               │  • Project model        │    │
│           ▼                         └──────────────┬──────────┘    │
│  ┌────────────────────┐                            │ IPC           │
│  │   Effects Server   │                            ▼               │
│  │   (Node.js)        │             ┌─────────────────────────┐    │
│  │                    │             │   Watchdog Service      │    │
│  │  • Shader uniforms │             │   (exaplay3-service)    │    │
│  │  • Audio analysis  │             │   • Crash detection     │    │
│  │  • Data tracks     │             │   • Auto-restart        │    │
│  └────────────────────┘             └─────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────┘
```

## Directory Structure

```
exaplay_backend/
  main.cpp                  Windows app entry point (tray, engine init)
  server.js                 Node.js effects server
  exaplay-sdk/              Core C++ engine (~100+ source files)
    mh/                     Media handlers (HAP, Medialooks, NotchLC, browser)
    th/                     Target/output handlers (VIOSO, virtual)
    engine-comm/            Communication (HTTP, WS, OSC, TCP/UDP, ArtNet, LTC)
    config/                 Configuration subsystems
    project/                Project model (compositions, cuelists, screens)
  exaplay3-service/         Watchdog Windows service
  exa-dep/                  External deps (QLM, MediaInfo, VIOSO)
  mgx-dep/                  Internal utilities (OpenGL, JSON, logging)
  __tests__/                Jest tests for server.js

exaplay_frontend/
  src/
    main.js                 Bootstrap, Pinia, Axios config
    App.vue                 Root component (WebSocket init, theming)
    router/index.js         3 routes: / (editor), /control, /user
    stores/                 Pinia: data, inspector, settings, playlist, drag, split
    views/                  MainView, ControlView, UserView, ConfigView, AboutView
    components/             UI components
  public/brand/             Theming (logo, splash, brand.css)
```

## C++ Engine

The engine is a Windows-only native application:

* **Entry point:** `wWinMain` in `main.cpp`
* **Single-instance mutex** prevents multiple instances
* **HTTP server** on port `8123` (configurable) serves both the REST API and the built frontend files
* **WebSocket endpoints:** `/info` (project events) and `/perf` (performance metrics)
* **OpenGL 4+** rendering with GLSL shaders
* **Media decode** via HAP, Medialooks (ProRes, H.264), and NotchLC decoders

## Node.js Effects Server

`server.js` runs on port `3001` and manages GPU shader state:

* **Express 4** for REST endpoints
* **ws** library for WebSocket connections
* Maintains effect state in memory and broadcasts changes to all connected clients
* Audio analysis uses JavaScript FFT (no native addon required)

See [Effects Server API](/v3/developer-reference/effects-server-api.md) for the full API reference.

## Frontend

A **Vue 3 SPA** built with Vite:

* Two WebSocket connections to the engine (`/info` and `/perf`)
* One WebSocket connection to the Effects Server (`ws://localhost:3001/effects`)
* State managed entirely in **Pinia** stores
* **Arco Design** component library for UI

## Technology Reference

| Layer          | Libraries / Standards                                   |
| -------------- | ------------------------------------------------------- |
| C++ Engine     | MSVC C++17, Win32 API, OpenGL 4+, GLSL, GLEW, GLM       |
| Media          | HAP codec, Medialooks SDK, NotchLC                      |
| Audio          | ASIO SDK, PortAudio                                     |
| Networking     | Boost.Beast (HTTP/WS), libuv (timers)                   |
| Projection     | VIOSO WarpBlend API                                     |
| Licensing      | Soraco QLM                                              |
| Effects Server | Node.js 18+, Express 4.18, ws 8.13                      |
| Frontend       | Vue 3.x, Vite 4.x, Pinia, Axios, Arco Design            |
| Testing        | Jest + Supertest (backend); no frontend tests currently |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.exaplay.one/v3/developer-reference/index.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.