Mantle Open the web app

Architecture

Mantle is one Go core with one HTTP API and one web frontend, run in three shells: a Windows desktop window, a browser tab that runs the core itself as WebAssembly (the web build), and an Android app. This page is the map: what each part does, where it lives and how it talks to the others. Internals holds the detail behind it: measurements, workarounds and edge cases.

The desktop, web and Android shells and the server build around one Go core. The frontend asks the core over an API. The core asks plugins, which run in a Lua sandbox, and syncs sealed records with the Mantle Together service.

The frontend never imports Wails' JavaScript runtime. It talks to Go only with fetch calls to /api/, /art/ and /media/. That is why the same frontend runs in all three shells.

Contents: Parts · Layout · Shells · Core · Sync · Server · Plugins · Frontend · Tests

The parts

Part What it does Where Talks to
Shells Open the app: a window, a tab or a server. Each starts the core and serves the API. cmd/mantle/ The core, over method calls. The frontend, over /api/.
Frontend Draws the screens and takes input. frontend/ The API, with fetch.
Server The API, artwork, the media server and the Android app's door. internal/server/ The core.
Core The application: profiles, titles, playback, downloads, saving, sync. internal/core/ Plugins, the network, the disk, the account service.
Plugins Everything beyond the core: catalogs, sources, importers. Lua. internal/plugin/, internal/script/, plugins/ The core's hooks, and the network they were granted.
Mantle Together Optional accounts. Syncs a household's sealed records between its devices. internal/together/, supabase/ The core, over HTTPS and Realtime.

Repository layout

Path What it holds
embed.go, embed_ui.go The one root package (mantle): the plugins that come with the app and the built frontend, embedded (Go forbids .. in an embed path) for cmd/mantle to read. The web build has no frontend embed.
cmd/mantle/app.go Code shared by the shells: start (builds and starts the core), stop, the plugin file watchers.
cmd/mantle/main.go, desktop.go, devhooks_*.go, reveal_*.go, resize_*.go, zoom_*.go The desktop shell (build constraint !web && !js).
cmd/mantle/main_js.go The web build's shell (GOOS=js): the core as WebAssembly.
cmd/mantle/web.go The Android app's shell: a server (build tag web).
android/ The Android app's window: AndroidManifest.xml, src/app/mantle/*.java, test/ (the JVM tests mk android runs), res/.
internal/core/ The core.
internal/server/ The API, the media server, the access gate and the host interface.
internal/plugin/ The plugin host: manifests, state, installing, permissions, hooks.
internal/script/ The Lua sandbox and the mantle table plugins use.
internal/secrets/ The store for plugins' keys and tokens, and the account's session and key: secrets.dat, AES-256-GCM under a key in the data folder (secrets.key), or a given key (the Android app's).
internal/together/ The client of the account service: sealing, records, rounds, friends, parties.
internal/media/ The model of a title, its episodes and details.
internal/release/ Reads a release's name (title, season, resolution, codec, HDR, audio).
internal/art/ Serves artwork at the size asked for and caches it.
internal/fetch/ Downloads a file over HTTP, carrying on after a cut or a restart.
internal/container/ (with dolby/, dts/ and flac/, the audio decoders it runs) Reads MP4 and Matroska files in parts (keyframes, length, chapters) and repackages one as HLS for a player that cannot switch audio tracks itself, or whose keyframes are too far apart for a browser to hold. A long stretch between keyframes is cut in parts that start without one, which hls.js 1.7 mishandles: video.js works around it by going to the stretch's keyframe itself (issue #51). The mechanism is in the internal/container code and in Internals.
internal/bitio/ Reads and writes bits: the decoders' and the QR encoder's.
internal/pgs/ Reads PGS subtitles (a Blu-ray's pictures) into timed cues of pictures.
internal/portable/ Finds the data folder, and locks it.
internal/sample/ The built-in sample catalogue, for development and tests.
plugins/ The plugins that come with Mantle, in Lua.
frontend/ The web UI. frontend/src/web/ is the web build's side of the page: the core's worker and its files.
supabase/ The Together service's schema (migrations/), settings and emails.
tools/mk/ The build tool.
docs/ These pages, the diagrams in docs/images/, and the design reference prototype in docs/ref/.

One core, three shells

Each shell does the same four things:

  1. Finds the data folder and calls start in cmd/mantle/app.go.
  2. Creates the API with server.New(core, data, host), whose handler also serves the embedded frontend (the web build's serves nothing else: its page is the site).
  3. Serves that over a transport.
  4. Calls stop when it ends (not the web build: a tab closes without warning, so it saves as it goes).
Desktop Web Android
Entry cmd/mantle/main.go cmd/mantle/main_js.go cmd/mantle/web.go, built for Android
Build no tag GOOS=js GOARCH=wasm, production web,production with GOOS=android
Transport Wails serves the handler as the window's assets The page's service worker, through the page, to a worker running the core net/http listener on 127.0.0.1
Host desktop (desktop.go) server.Page server.Browser
Media server.ServeMedia: its own listener on 127.0.0.1, a random port None: nothing downloads or is relayed server.Media mounted at /media/
Door None None: the page is the app server.Gate: a code made for each launch (-code), elsewhere the code kept in the data folder
Data mantle-data beside the program /mantle-data in files kept in the browser's IndexedDB <app files>/mantle-data

The Android app runs Mantle's server as a child process. MainActivity starts libmantle.so (the program, packed as a native library) with -listen 127.0.0.1:0 -data <path> -code <random>, reads the Mantle is at … line from its output, and loads <address>/auth?code=<random> in a WebView. tools/mk/android.go compiles the program with CGO and the NDK, so it uses the phone's own DNS and certificates.

The web build

The same program as the others, built with GOOS=js GOARCH=wasm; core.InBrowser is true in it. The page starts the core before the app (src/web/core.js), takes a Web Lock so one tab runs it at a time, and starts a worker (src/web/worker.js) that runs the core over a file system in memory kept in IndexedDB (files.js). The service worker passes /api/ and /art/ to the page, which passes them to the worker. secrets.dat is sealed there under a key the page cannot export (seal.js).

  • A tab closing cannot be made safe: the worker ends with the page, so a save asked as the page goes never lands. Saves are small and frequent instead (the core's each second it changed, the files' batch 50 ms after the last change, a save when the tab is hidden). The measurements are in Internals, and the script is frontend/measure/closing/closing.mjs.
  • What a page cannot do, the core does not try: Network is the browser's fetch; a plugin whose manifest says native does not run (ErrNeedsApp); Download answers ErrNeedsApp; artwork is a redirect (ArtAddress); the kept answers may take 16 MB, not 64.
  • The frontend asks inPage() and downloads() (core/host.js) to hide what does not apply, and runsHere(p) for a plugin.

What start does

cmd/mantle/app.go builds the core in this order (the detail of each step is in Internals):

  1. Takes the data folder's lock (portable.Lock): a second run on one folder ends, and a crash never leaves it locked.
  2. Creates the core (core.Empty; core.New with the sample), opens the log in <data>/logs.
  3. Adds the plugins that come with the app (embedded; MANTLE_PLUGINS reads them from a folder in a build without the production tag only, build.DevEnv: every packaged build has the tag and ignores it), then the real providers.
  4. Opens <data>/secrets.dat, applies a restore waiting in the folder, and gives the core the network.
  5. Sets the answers cache, the home folder for download paths and the plugins installed from links.
  6. Reads <data>/mantle.json (falling back to a copy if it cannot be read), then saves whenever it changes.
  7. Refreshes the plugins, describes the profile's titles in the background and resumes downloads.

The core

internal/core holds the application. The UI asks it for display-ready data: what Home shows, a title's page, search results. It also holds the actions that change that data. Core is guarded by one mutex, and its methods are safe to call from many goroutines.

  • State. Profiles (each has its library, lists, favourites, progress, history and settings; one is current, for every client of one server), the registry of titles providers described, the plugin host, the downloads and their folders, what is playing, and the log. mantle.json holds it, without the providers' answers.
  • Saving. Once a second if it changed, by writing beside and renaming, with copies kept (.bak, .before-*). A save that fails is shown in a banner and tried again. Downloads keep a reserve of free disk for it.
  • Going back. A version that goes back reads what a newer one wrote without losing most of it (forward.go): unknown fields are kept and written back, and a file that cannot be read is set aside, never overwritten.

Why these rules and what they cost: Internals.

Questions to providers

Everything a plugin supplies is a question: a list's page, a search, a title's details, a title's sources. Questions are cached, and each is asked once however many pages wait for it (network.go).

  • An answer has a lifetime: lists 30 minutes, details 6 hours, sources 10 minutes. An old answer still serves while it is asked again, and pages that show it hear of a change (news.go).
  • Some answers are kept on disk (answers.go): compressed, up to 64 MB, least recently used first. Sources are not, since a source's link can carry an indexer's key.
  • A call can say what it has so far (mantle.so_far), and a question can be in a plugin's lane, where a newer one stops the older.
  • A provider can be slow, so an API page answers at once with what it has and names what is pending. Asked again with ?wait=1, it answers when the next answer comes. The frontend's useLoad does this.

Playback

playback.go runs the steps of getting a source ready (playsource.go resolves one), and the player shows each:

Stage What it means
prep Finding sources and trying one.
pick The profile must choose a source (none found, or all failed, or Picker is on).
transfer A resolver is preparing the release. The core asks its progress every 3 seconds.
play A stream is ready. The player has its address.

The core fails over to the next ranked source when one fails (bestLeft), and says why a source failed (whyFailed). The player reports where it stopped, and the core records progress and history. One thing plays at a time: Play ends the playback still going elsewhere, and that player closes with "Stopped: something is playing elsewhere". How finders, resolvers and the check for cached releases combine is in provided.go.

The parts of the core

File What it does
importers.go An importer plugin gives a library, watched marks and lists; the core merges them by fixed rules.
settings.go A profile's preferences, with defaults so the page can tell what changed.
setup.go A plugin's settings, its sign-in by code and what it still needs (requires, needs).
pin.go A profile's PIN: below.
setupshare.go The setup as a code or file: below.
library.go The Library, lists and each list's sort (SetSort, synced as sort/<list>); the search and filters are the page's, per profile on this device.
export.go core.File: a file the core makes, saved with SaveIn, which refuses a name that would land outside the folder.
onboarding.go The first run's step, saved.
downloads.go, downloadrun.go, downloadrow.go, folders.go, ondisk.go Downloads: the queue, fetching one, the page's rows, and folders of their own per title; a file is only served or copied from inside its folder.
history.go A profile's plays, one sync record each; History shows the newest of a title a day.
notes.go Notes on a title in a list, as threads; a first note needs the title in the list.
friends.go, internal/together/friends.go Invites: the service holds a proof and a sealed card, never the secret.
activity.go, losing.go, devicename.go What the people a profile shares with did, found as the rounds sync and told once; what deleting the account or taking a profile out would take; what a device calls itself.
household.go The household's plugins, as records: below.
shared.go Shared and own lists, as records.
restore.go, apply.go, copies.go Backups and restores: staged, applied as Mantle starts.
forward.go, persist.go Saving, and reading what a newer version wrote.
party.go, partystate.go, partymsg.go Watch parties: the actions, what the party knows and its view, and what is said on it.
playsource.go, failover.go Resolving a source, and giving up on one for the next.

The whole package's file map is the comment at the top of internal/core/core.go. The detail of each part is in Internals.

Profile PINs

A PIN of 4 to 8 digits keeps a profile to itself in a household. It is not encryption: anyone who can read the data folder can read every profile. The page asks for it; the core refuses only what changes whose profile is whose (SwitchProfile, ChangeProfile, RemoveProfile). It is stored as a salted PBKDF2 hash, sent nowhere, and wrong tries wait longer each time (from the fifth, 30 s doubling to 5 min). A refusal is a 403, a wait a 429, never a 401. Routes and rules: Internals.

Sharing a setup

A share is JSON compressed into a mantle1: code or a file. It holds a profile's plugins, repositories, settings and lists, never a secret or a link that may hold a key. Pick cuts it, ViewShare shows how it would land, ApplyShare brings it in, and the frontend installs each plugin it names, asking for permissions. See Internals.

Mantle Together

Optional accounts, so a household's devices share profiles, lists, friends and watch parties. Everything is sealed on the device before it is sent, so the service holds records it cannot read (internal/together, the schema in supabase/migrations, the guide in Mantle Together). A device pushes the records that changed, pulls what others pushed, and merges them by record: the later stamp wins.

A sync round in four steps: a whole round checks the account, pulls what changed and pushes what changed here, with news waking other devices through Realtime. A round of what changed here alone only pushes.

  • Records. A profile's library, lists, progress and history, a shared list's records, and the household's plugins are records (plugin/<id>, own/<list>/…, note/…). A record this version would never make by that name (a newer version's: a kind it lacks, a setting it has no field for) is left alone: not applied, noted, deleted or sent. Two devices that change one list apart keep both changes; deleting a list wins over every edit, and removes its notes and read marks too.
  • What costs. The service is paid for by requests and rows, so a round (syncRound, sync.go) is one of two kinds. A whole round does the checks (some eight requests), pulls and pushes: every 5 minutes with Realtime connected, 30 seconds without, and when news or an action asks. A round of what changed here alone just pushes. Playing is paced: progress goes up at most every 90 seconds, and at once as Mantle quits or the page is hidden. Two hours of a film once cost 12,500 requests and now about 1,400.
  • Limits. A page is 1000 rows, a push 16 MiB; lists too big for one push are rekeyed in pages of 500. Sign-ups are limited per network, and counted rows are capped.
  • Keys. Which device may replace the recovery sealing or delete an account is decided by a device's proof that it holds the key. A member of a shared list may write only as themselves.
  • From the betas. Lists before 0.3.0 were one record each. A device reads those records as the new ones and writes the old list/<id> only to delete one an older build wrote again (readOldLists, listsold.go), so an older build keeps working.
  • Locks. A round holds the account's lock only while it reads or writes state, never across a request; calls that change the account wait for a round in flight, reads and sign-out do not (Locks in a round).

Detail and numbers: What sync costs, parts of the core, own lists.

The server and its hosts

server.New(core, data, host).Handler(ui) returns an http.Handler:

Path What it serves
/api/… The JSON API: one route for each call the frontend makes, the table routes in internal/server/routes.go, each answered by a small named handler. A handler returns its answer and its error; only a route that writes the response itself (a file, a picture, a range) takes the writer.
/art/{id}/{kind} Artwork (poster, backdrop) at the width asked for, resized once and cached in <data>/cache/art. A picture over 40 MB is refused (422); a title with no artwork is 404, a provider's failure 502.
everything else The frontend's files.

replyOr answers a core error with the status the statuses table in api.go gives it: unknown things 404, conflicts 409, bad input 400, a PIN not given or wrong 403, wrong too often 429, what only the desktop can do 501, anything else 500. To give a new core error a status, add it to its row. The body is the error's own text, and a toast shows it, so an error must say something true where it is returned. More in Internals.

A file is saved one of two ways: the desktop's page POSTs and the server writes it into <data>/exports; a browser's page GETs a route that answers an attachment, and the Android WebView's DownloadListener asks the phone's Save dialog. Sharing, export, backup and restore routes: Internals. A restore is staged, then applied as Mantle starts, and never half-done (Internals).

Host

What the surroundings do beyond the core is the Host interface: Kind (desktop, browser, page, or android), OpenURL, Reveal, ChooseFolder, Window and Restart. The desktop host opens the system browser and dialogs and drives the window. server.Browser is the host in a browser: its calls return ErrNotHere, the API turns that into 501, and the window routes are 404. server.Page is the web build's. GET /api/host tells the page which it is, and the page hides what does not apply.

Media

server.Media(core, secret) serves the player what it cannot get elsewhere, under /media/<secret>/; the secret is new at every start.

  • <key>: the file of a finished download, with ranges for seeking.
  • relay/<key>: a stream that needs headers of its own (an addon's proxyHeaders). The core fetches it, asks public addresses alone on every hop of a redirect (unless the hop's host is one the stream's plugins may reach: Core.held, the one test streams, downloads, previews and frame reads all use), passes on only the headers a player reads, and answers nosniff with Content-Security-Policy: sandbox.

The desktop serves this on a listener of its own on 127.0.0.1; the Android app mounts it beside the API, behind the gate; the web build has none.

Gate

The Android app's server wraps its handler in server.Gate. Without a session cookie, a request gets the sign-in page, or 401 for /api/, /art/ and /media/. The code is 8 to 64 letters or digits; each signed-in device is a hashed session token, up to 64, signed out after 30 unused days. Wrong codes are counted per address (an IPv6 address as its /64) and slow down; behind -proxied the client is the last X-Forwarded-For and the cookie is Secure when the proxy says https. It refuses another site's unsafe requests, frames, and any Host that is not an address, localhost, this computer's name or one given with -allow-host (DNS rebinding). CheckListen refuses a non-loopback address without -insecure-lan, since there is no TLS. The code can be given with -code, -code-file or MANTLE_CODE (the last two keep it off the command line), and is printed to stderr, never the log, only when Mantle made it. All of it: Internals. To run that server on a computer, see Building and testing.

Plugins

A plugin is Lua, either a folder with an init.lua or a single .lua file. internal/plugin is the host. internal/script runs the Lua with gopher-lua, which is Lua 5.1 in pure Go. The plugin guide (plugins/README.md) is the reference for the plugin object and its functions.

The main chunk returns the plugin object, M. Mantle reads it with nothing granted: no network, no secrets. The object says who the plugin is, what it may reach (permissions) and its settings. Its init then adds what the plugin offers by calling mantle.<part>.add, and each part maps to one of the core's hooks (the table is in internal/script/register.go):

Call Hook
mantle.nav.add ui.nav.items
mantle.shelf.add ui.home.sections
mantle.catalog.add catalog.providers
mantle.metadata.add metadata.providers
mantle.finder.add source.finders
mantle.resolver.add source.resolvers
mantle.importer.add library.importers

A hook's kind says how contributions combine: contribute, transform, replace or veto (internal/plugin/plugin.go). The core reads each hook from the plugins that are on, in priority order, so turning one on or off changes the app at once. contract.go checks every contribution has what the core needs; one that does not is left out, and the log says so. A plugin with a refresh function renews what it keeps in mantle.store (at start, on sign-in or out, when its settings change), and is then read again (Internals). When the core needs an answer it calls the plugin's function by its place (catalog.page, resolver.resolve) with a table; a call has 30 seconds, and up to four run at once, each in its own Lua state.

The sandbox

A script starts from an empty environment with string, table and math: no io, os, debug, load or dofile. It gets the mantle tables its plugin was granted.

  • mantle.http works only with the network permission, and only to the granted hosts. Redirects are checked host by host, and a redirect cannot reach the computer or its network (script.HoldUnless): artwork, relayed streams, previews, downloads and frame reads are held the same way on every hop (Core.held).
  • mantle.cred works only with the credentials permission. Secret settings are kept there too.
  • The rest (json, xml, html, re, url, release, time, store, log, hash, base64, stremio) does heavy work in Go.

A plugin refused the network (Plugin.NetOff) is not Online: it does not refresh, import, or run, and its health check says so. The host rule, the store's limits and the links a user gives to install something are in Internals.

Where plugins live

  • The plugins that come with Mantle are embedded in the program (plugins/*/*.lua). Their tests are not.
  • internal/plugin/builtin/*.lua are plugins the core itself answers for: Mantle core (navigation, the Home shelves the core owns, smart-list fields) and Skip intro.
  • Plugins installed from links are written to <data>/plugins, with where they came from kept so they can be updated. A Stremio addon is a plugin of one line, return mantle.stremio.addon(link).
  • The sample's stand-ins (internal/plugin/standins) exist only in builds without the production tag.

What a plugin was granted, its settings and its place in the priority order are the device's. Whether it is on is each profile's (Plugin.Chosen), else how it starts (Plugin.On). A plugin made private is visible to one profile only. In a household, a plugin's start, grants, settings and sign-in are records that sync (household.go), and a refusal made by one device is a mark that the others keep (Internals).

The frontend

frontend/ is a Vite project. The UI is Preact, written with htm: components are tagged templates, so there is no JSX build step. It has no router, state or UI library beyond Preact and a few small packages (interactjs for dragging, lucide for icons, the Hanken Grotesk and JetBrains Mono fonts).

Folder What it holds
src/main.js Starts the app: input tracking, the window, /api/host, then renders. In a browser it also follows the browser's history and registers the service worker.
src/bridge/ api.js (every call into the core, over fetch), host.js, window.js (the native window), copy.js (clipboard).
src/lib/ html.js (htm bound to Preact) and words.js (how sentences name things: listed, lower, count).
src/app/ The shell (App.js), the rail and the phone's tab bar, the router, the player, navigation, settings and downloads state.
src/app/pages/ One file for each screen.
src/ui/ The component kit. Each has Storybook stories.
src/nav/, src/input/ Focus movement for keyboard and controller; input modality, long press and hold.
src/styles/ Design tokens, themes and base styles.
src/testkit/ A stand-in core for stories, and the stories' helpers (clock.js, sim.js).
src/fixtures/ What the stories and tests read: JSON the core answers with, clips, HLS files.
src/web/ The web build's page side: starting the core, its worker and its files.
public/ The manifest, the icons and sw.js, for a browser.
Subject The rule, and where the detail is
Calls Almost every call goes through core/api.js. In the Android WebView a 401 reloads the page, which signs in again.
Window core/window.js calls /api/window/… for the title bar's buttons; the only native calls are wails:drag and wails:resize:…. The title bar is the page's top bar, marked as the drag area.
Router A stack of routes in memory (router.js). Back returns to where you were (scroll and focus kept per history entry; a new visit starts at the top); in a browser it follows history; a menu or sheet takes an entry of its own. Internals.
Loading useLoad loads a page's data, asks again while parts are pending, and asks again quietly when the core says something is new.
Phone CSS and ui/phone.js: at 760 px or less, or a touch screen 500 px tall or less, the rail becomes a tab bar, menus become sheets and the player is driven by touch. The media query is written out in phone.js and in each stylesheet that has a phone layout.
Words lib/words.js for sentences the app says: listed(['A', 'B', 'C']) is "A, B and C".
Quiet watch stalledStream.js and video.js notice hls.js gone quiet on a repackaged stream and restart it, or fail the source so the core fails over (issue #87). Internals.
Party speed The host reports the speed it plays at; every guest plays at it, whatever its device, and Catch up is for a guest back from away. Nothing holds a speed below what a viewer picks. Internals.
Offline sw.js keeps the page and its files so a browser opens the app without a connection. It never keeps the API, artwork, media or the sign-in page. With ?page it passes /api/ and /art/ to the page.

Tests

  • Go tests sit beside the code. A plugin's tests are JSON files in plugins/<id>/tests/: a call, what the network answers, what must come back.
  • Every Storybook story is a test. Page stories use frontend/src/testkit/api.js, a stand-in for the core that answers /api/ calls from fixtures, so a page is tested without a Go process.
  • The web build's own rules are tested as it runs: internal/core/*_js_test.go, built as WebAssembly and run in Node. Its files (src/web/files.test.js) and the player's stall watch (src/app/stalledStream.test.js) are tested in Node, with no browser.
  • go run ./tools/mk test runs them all. Building and testing lists what.

This page is made from docs/dev/architecture.md in the repository.