Architecture overview
Entry point for developers. Each area links to the document that holds the details.
Stack
| Layer | Technology |
|---|---|
| Wrapper / backend | Electron (Main Process as a Node.js + TypeScript backend) |
| Frontend | React 19 (Vite) + Tailwind CSS v4 + TanStack Query + TanStack Router |
| Communication | Strict native IPC: contextIsolation: true, nodeIntegration: false, sandbox: true, preload bridge |
| Database | SQLite (WAL) via Drizzle ORM + LibSQL driver |
| Validation | Zod (IPC payloads and remote manifests) |
| LLM | OpenRouter over SSE (native fetch) |
| Sidecars | mkvtoolnix (mkvextract/mkvmerge) and ffmpeg via child_process |
| Logging | electron-log, rotating file in userData/logs |
Tooling runs on Node 26 (.nvmrc). The Main Process runs on Electron 44’s embedded Node (24.x), so @types/node stays at ^24.
Supported platforms: Linux x64 and Windows x64. There is no macOS build.
Layout
src/ main/ config/ paths (userData), remote URLs database/ client (WAL, migrate on boot), schema/, repositories/ ipc/ create-handler (sender check + Zod), register, per-domain handlers/ logging/ electron-log (scopes: app, db, ipc, sidecar, llm, jobs, renderer) services/ shutdown-coordinator, app-info, app-update, native consent dialog sidecars/ sidecar module (no `electron` dependency, testable in plain Node) parsers/ subtitle parsing: decoder, common AST, SRT, ASS/SSA, WebVTT, segmentation, coverage (pure, testable) llm/ OpenRouter client (SSE), model catalog, chunking, prompts, retries, translateDocument memory/ Job Memory: context hash and cache service media-context/ TMDB media context: release-name parser, client, cache, artwork protocol media/ mkvtoolnix facade (probe/extract/mux), languages, output naming, path guard jobs/ job queue, runner, steps (probe/extract/translate/validate/write/mux), job specs batch/ batch planning (scan, probe, track selection) and batch service preflight/ token counting (js-tiktoken) and cost estimate presets/ built-in (immutable) and custom translation presets settings/ typed settings registry and the encrypted secret vault window/ BrowserWindow factory preload/ the only surface exposed to the renderer (window.api), allowlisted renderer/ React + Tailwind + TanStack Query + TanStack Router + i18next src/guides/ in-app user guides, one folder per language (en, pt-BR) shared/ typed IPC contract and pure utilities (no zod/electron)drizzle/ versioned migrationsscripts/ cross-build (Docker/wine), icons and native binariesdocs/ detailed system flowsMain flows
- IPC:
src/shared/ipc-contract.tsis the single source of truth for channels, payloads andwindow.api. The preload only exposes channels listed inINVOKE_CHANNELS/EVENT_CHANNELSand never the rawipcRenderer. Every handler goes throughcreateHandler, which rejects untrustedsenderFrames, validates input with Zod and returns a{ ok, data } | { ok: false, error }envelope. Seeipc.md. - Graceful shutdown:
ShutdownCoordinatorruns disposers in LIFO order with a global timeout onbefore-quitand onSIGINT/SIGTERM. It aborts running jobs first (marking theminterrupted), then releases sidecar child processes (SIGTERM → SIGKILL), the Job Memory writes and the database (wal_checkpoint(TRUNCATE)). - Subtitle parsing: lossless AST per format; only text nodes go to the LLM. See
parsing.md. - Translation: chunking, structured JSON, validation, retries, termbase. See
llm.md,rate-limits.mdandpresets.md. - Cost and cache:
preflight.mdandjob-memory.md. - Jobs and batches: queue, runner, steps, cancellation. See
jobs.md. - Media context (TMDB):
media-context.md. - Sidecars: remote manifest, verified download, pruning. See
sidecars.md. - Database: SQLite in WAL mode (
synchronous=NORMAL,foreign_keys=ON,busy_timeout=5000), Drizzle migrations applied on boot (drizzle/ships inresources/). Seedatabase.md. - Native notifications: emitted by the Main, only in the background, per-category settings. See
notifications.md. - Renderer:
renderer.md. Brand tokens (shared with the site):brand-tokens.md. Website (site/):site.md. Logging:logging.md. Build and release:release.md.
User data
Everything lives in app.getPath('userData') (Linux: ~/.config/bakasub, Windows: %APPDATA%\bakasub), never in the install directory:
bakasub.db SQLite (WAL)logs/main.log JSON lines, rotates at 5 MB (5 files kept)cache/manifests/ last valid remote manifest (offline fallback)bin/ sidecarsSidecars in short
ffmpeg and mkvtoolnix are not bundled. The app reads manifests/sidecar.json from this repository (via raw.githubusercontent.com): URL, SHA-256, archive type and binary path per tool × platform × arch.
- Never downloads automatically:
sidecars:installrequires a native dialog in the Main Process (default button: Cancel), which a compromised renderer cannot approve. - Streaming download with on-the-fly SHA-256, HTTP Range resume and exponential-backoff retry; a hash mismatch discards the file.
- Every binary is executed (
--version) before being recorded inbin/installed.json. - All external CLI execution goes through
ProcessRunner(timeout, SIGTERM→SIGKILL, stderr captured to the log, tracked for shutdown).
const { path, env } = await sidecars.resolve('mkvmerge')// `env` is required: on Linux it injects LD_LIBRARY_PATH for the extracted AppImage libsmkvextract writes .srt files with a UTF-8 BOM; the lexer strips it before reading the first cue.
Feature status (1.0.0)
- Strict IPC, logging, database with migrations, graceful shutdown
- Sidecars: manifests, verifiable download, resume, pruning, consent
- App version check and auto-update (GitHub Releases)
- Build and release (Linux + Windows)
- SRT, ASS/SSA and WebVTT parsers: lossless AST, tolerant scanner with diagnostics, safe repair mode, XLIFF-style segmentation, coverage report. Image-based subtitles (PGS/VobSub) are out of scope
- Job Manager: persisted jobs (
extract,translate,mux,pipeline), FIFO queue with bounded concurrency, per-jobAbortController, retry from the failed step, atomic outputs, presets (4 built-ins + custom, JSON export/import) - Batch mode for Translate, Extract and Mux, with MKV ↔ subtitle pairing for mux
- LLM layer:
<context>/<target>chunks, parallel lanes, AIMD in-flight cap, structured JSON validated with Zod, per-line repair, termbase, SSE with cancellation and cost accounting, encrypted API key - Term consistency pass (local, no LLM)
- Job Memory: validated cache keyed by context hash + language + model + glossary
- Preflight: local token estimate × cache hit rate × live OpenRouter pricing, coverage report, confirmation before translating
- Media context (TMDB): release-name parsing, conservative auto-match, local artwork cache
- Rate limits and retries: per-lane limiter, 429 cooldown, free-model daily quota
- Frontend: onboarding, Translate wizard, queue, Extract, Mux, Presets, Models, Languages, Logs, Settings; English and Brazilian Portuguese
- Parser diagnostics and encoding confidence for subtitle files in the Translate wizard preflight
Known gaps: no batch view after leaving the page that created it and no “remove batch” (batches:list is unused); no encoding override in jobs:create; videos and the queue detail do not show parser diagnostics.