100 lines
2.9 KiB
Text
100 lines
2.9 KiB
Text
|
---
|
|||
|
|
title: Wails v3 Architecture
|
|||
|
|
description: Deep-dive diagrams and explanations of every moving part inside Wails v3
|
|||
|
|
sidebar:
|
|||
|
|
order: 1
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
|
|||
|
|
Wails v3 is a **full-stack desktop framework** consisting of a Go runtime,
|
|||
|
|
a JavaScript bridge, a task-driven tool-chain and a collection of templates that
|
|||
|
|
let you ship native applications powered by modern web tech.
|
|||
|
|
|
|||
|
|
This page presents the *big picture* in four diagrams:
|
|||
|
|
|
|||
|
|
1. **Overall Architecture** – how every subsystem connects
|
|||
|
|
2. **Runtime Flow** – what happens when JS calls Go and vice-versa
|
|||
|
|
3. **Development vs Production** – two modes of the asset server
|
|||
|
|
4. **Platform Implementations** – where OS-specific code lives
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1 · Overall Architecture
|
|||
|
|
|
|||
|
|
**Wails v3 – High-Level Stack**
|
|||
|
|
|
|||
|
|
{/*
|
|||
|
|
TODO: Fix D2 diagram generation (triple quotes for multi-line strings) or embed as image.
|
|||
|
|
The previous D2 code block was causing MDX parsing errors in the build pipeline.
|
|||
|
|
*/}
|
|||
|
|
|
|||
|
|
**[High-Level Stack Diagram Placeholder]**
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2 · Runtime Call Flow
|
|||
|
|
|
|||
|
|
**Runtime – JavaScript ⇄ Go Calling Path**
|
|||
|
|
|
|||
|
|
{/*
|
|||
|
|
TODO: Fix D2 diagram generation (triple quotes for multi-line strings) or embed as image.
|
|||
|
|
The previous D2 code block was causing MDX parsing errors in the build pipeline.
|
|||
|
|
*/}
|
|||
|
|
|
|||
|
|
**[Runtime Call Flow Diagram Placeholder]**
|
|||
|
|
|
|||
|
|
Key points:
|
|||
|
|
|
|||
|
|
* **No HTTP / IPC** – the bridge uses the native WebView’s in-memory channel
|
|||
|
|
* **Method IDs** – deterministic FNV-hash enables O(1) lookup in Go
|
|||
|
|
* **Promises** – errors propagate as rejections with stack & code
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3 · Development vs Production Asset Flow
|
|||
|
|
|
|||
|
|
**Dev ↔ Prod Asset Server**
|
|||
|
|
|
|||
|
|
{/*
|
|||
|
|
TODO: Fix D2 diagram generation (triple quotes for multi-line strings) or embed as image.
|
|||
|
|
The previous D2 code block was causing MDX parsing errors in the build pipeline.
|
|||
|
|
*/}
|
|||
|
|
|
|||
|
|
**[Asset Flow Diagram Placeholder]**
|
|||
|
|
|
|||
|
|
* In **dev** the server proxies unknown paths to the framework’s live-reload
|
|||
|
|
server and serves static assets from disk.
|
|||
|
|
* In **prod** the same API is backed by `go:embed`, producing a zero-dependency
|
|||
|
|
binary.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4 · Platform-Specific Runtime Split
|
|||
|
|
|
|||
|
|
**Per-OS Runtime Files**
|
|||
|
|
|
|||
|
|
{/*
|
|||
|
|
TODO: Fix D2 diagram generation (triple quotes for multi-line strings) or embed as image.
|
|||
|
|
The previous D2 code block was causing MDX parsing errors in the build pipeline.
|
|||
|
|
*/}
|
|||
|
|
|
|||
|
|
**[Platform Split Diagram Placeholder]**
|
|||
|
|
|
|||
|
|
Every feature follows this pattern:
|
|||
|
|
|
|||
|
|
1. **Common interface** in `pkg/application`
|
|||
|
|
2. **Message processor** entry in `pkg/application/messageprocessor_*.go`
|
|||
|
|
3. **Implementation** per OS under `internal/runtime/*.go` guarded by build tags
|
|||
|
|
|
|||
|
|
Missing functionality on an OS should return `ErrCapability` and register
|
|||
|
|
availability via `internal/capabilities`.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Summary
|
|||
|
|
|
|||
|
|
These diagrams outline **where the code lives**, **how data moves**, and
|
|||
|
|
**which layers own which responsibilities**.
|
|||
|
|
Keep them handy while exploring the detailed pages that follow – they are your
|
|||
|
|
map to the Wails v3 source tree.
|