gui/docs/ref/wails-v3/contributing/codebase-layout.mdx

---
title: Codebase Layout
description: How the Wails v3 repository is organised and how the pieces fit together
sidebar:
  order: 2
---

Wails v3 lives in a **monorepo** that contains the framework runtime, CLI,
examples, documentation, and build tool-chain.  
This page walks through the *directory structure* that matters to anyone digging
into the internals.

## Top-Level View

```
wails/
├── v3/               # ⬅️ Everything specific to Wails v3 lives here
├── v2/               # Legacy v2 implementation (can be ignored for v3 work)
├── docs/             # Astro-powered v3 docs site (this page!)
├── website/          # Docusaurus v2 site and marketing pages (main site)
├── scripts/          # Misc helper scripts (e.g. sponsor image generator)
├── mkdocs-website/   # Deprecated v3 docs prototype
└── *.md              # Project-wide meta files (CHANGELOG, LICENSE, …)
```

From here on, we zoom into the **`v3/`** tree.

## `v3/` Root

```
v3/
├── cmd/          # Compilable commands (currently only wails3 CLI)
├── examples/     # Hands-on sample apps testing every feature
├── internal/     # Framework implementation (not public API)
├── pkg/          # Public Go packages ‑ the API surface
├── tasks/        # Taskfile-based release utilities
├── templates/    # RFC-style proposals (WEP) + common assets
├── go.mod
└── go.sum
```

### Mental Model

1. **`pkg/`** exposes *what application developers import*  
2. **`internal/`** contains *how the magic is implemented*  
3. **`cmd/wails3`** drives *project lifecycle & builds*  
4. **`examples/`** double as *living tests* and *reference code*  

Everything else supports those three pillars.

---

## `cmd/` – Commands

| Path | Notes |
|------|-------|
| `v3/cmd/wails3` | The **CLI entrypoint**. A tiny `main.go` delegates all logic to packages in `internal/commands`. |
| `internal/commands/*` | Sub-commands (init, dev, build, doctor, …). Each lives in its own file for easy discoverability. |
| `internal/commands/task_wrapper.go` | Bridges between CLI flags and the Taskfile build pipeline. |

The CLI owns:

* **Project scaffolding** (`init`, template generation)  
* **Dev server orchestration** (`dev`, live-reload)  
* **Production builds & packaging** (`build`, `package`, platform wrappers)  
* **Diagnostics** (`doctor`)  

---

## `internal/` – The Engine Room

```
internal/
├── assetserver/  # Serving & embedding web assets
├── buildinfo/    # Reproducible build metadata
├── commands/     # CLI mechanics (see above)
├── runtime/      # Desktop runtime (per-platform)
├── generator/    # Static analysis & binding generator
├── templates/    # Project templates (frontend stacks)
├── packager/     # Linux AppImage/deb/rpm, Windows MSI, macOS DMG
├── capabilities/ # Host OS capability probing
├── dbus/         # Linux system tray integration
├── service/      # IPC micro-services framework
└── ...           # [other helper sub-packages]
```

### Key Sub-Packages

| Package | Responsibility | Where It Connects |
|---------|----------------|-------------------|
| `runtime` | Window/event loop, clipboard, dialogs, system tray. One file per OS with build-tags (`*_darwin.go`, `*_linux.go`, …). | Called by `pkg/application` and message processor. |
| `assetserver` | Dual-mode file server:<br />• Dev: serves from disk & proxies Vite<br />• Prod: embeds assets via `go:embed` | Initialized by `pkg/application` during startup. |
| `generator` | Parses Go source to build **binding metadata** which later produces TypeScript stub files and Go marshal/unmarshal code. | Triggered by `wails3 init` / `wails3 generate`. |
| `packager` | Wraps platform-specific packaging CLIs (eg. `electron-builder` equivalents) into Go for cross-platform automation. | Invoked by `wails3 package`. |

Supporting utilities (eg. `s/`, `hash/`, `flags/`) keep internal concerns decoupled.

---

## `pkg/` – Public API

```
pkg/
├── application/   # Core API: windows, menus, dialogs, events, …
├── runtime/       # JS-side helpers (bridge, events, screen, ...)
├── options/       # Strongly-typed configuration structs
├── menu/          # Declarative menu DSL
└── ...            # Platform helpers (mac/, windows/, assetserver/, …)
```

`pkg/application` bootstraps a Wails program:

```go
func main() {
    app := application.New(application.Options{
        Name: "MyApp",
        Assets: application.NewAssetsFS(assetsFS),
    })
    window := app.Window.New(&application.WebviewWindowOptions{
        Title:  "Hello",
        Width:  1024,
        Height: 768,
    })
    app.Run()
}
```

Under the hood it:

1. Spins up `internal.runtime.*`
2. Sets up an `assetserver`
3. Registers bindings generated by `internal.generator`
4. Enters the OS main thread

---

## `examples/` – Living Specs

Each sub-folder is a **self-contained application** exercising one feature.  
Patterns you’ll see mirrored in real code:

* Binding services (`examples/binding/`)  
* Multi-window (`examples/window/`)  
* System tray (`examples/systray-*`)  
* Packaging (`examples/file-association/`)  

When in doubt, start here and drill into implementation.

---

## `templates/` – Scaffolding Blueprints

`internal/templates` ships **base templates** (Go layout) and **frontend skins**
(React, Svelte, Vue, …).  
At `wails3 init -t react`, the CLI:

1. Copies `_common` Go files
2. Merges desired frontend pack
3. Runs `npm install` + `task deps`

Editing templates **does not** affect existing apps, only future `init`s.

---

## `tasks/` – Release Automation

Taskfiles wrap complex cross-compilation, version bumping, and changelog
generation. They are consumed programmatically by `internal/commands/task.go`
so the same logic powers **CLI** and **CI**.

---

## How the Pieces Interact

```d2
direction: down
CLI: "wails3 CLI"
Generator: "internal/generator"
AssetDev: "assetserver (dev)"
Packager: "internal/packager"
AppRuntime: {
  label: "App runtime"
  ApplicationPkg: "pkg.application"
  InternalRuntime: "internal.runtime"
  OSAPIs: "OS APIs"
}
CLI -> Generator: "build / generate"
CLI -> AssetDev: "dev"
CLI -> Packager: "package"
Generator -> ApplicationPkg: "bindings"
ApplicationPkg -> InternalRuntime
InternalRuntime -> OSAPIs
ApplicationPkg -> AssetDev
```

*CLI → generator → runtime* forms the core path from **source** to **running
desktop app**.

---

## Orientation Tips

| Need to understand… | Look at… |
|---------------------|----------|
| Platform shims | `internal/runtime/*_DARWIN.go`, `*_windows.go`, … |
| Bridge protocol | `pkg/application/messageprocessor_*.go` |
| Asset workflow | `internal/assetserver`, `v3/templates/base/assets` |
| Packaging flow | `internal/commands/appimage.go`, `internal/packager` |
| Template engine | `internal/templates/templates.go` |
| Static analysis | `internal/generator/*` |

---

You now have a **mental map** of the repository.  
Use it with `ripgrep`, your IDE’s “Go to File/Symbol”, and the example apps to
navigate deeper into any feature. Happy hacking!