yonlu/yellowjacket

Fork 0

Files

T

yonlu 572b7fb664 docs: map existing codebase

2026-02-26 16:58:25 -05:00

6.9 KiB

Raw Blame History

Technology Stack

Analysis Date: 2026-02-26

Languages

Primary:

Go 1.25 - Backend application logic, audio playback, database, system integrations
TypeScript ~5.9 - Frontend UI with Lit Web Components

Secondary:

SQL - SQLite schemas and queries (via sqlc code generation)
HTML/CSS - Frontend layout and styling (Lit css tagged templates, index.html, index.css)
Bash - Build/profiling scripts (scripts/profile.sh)

Runtime

Environment:

Wails v2 runtime (WebView2 on Windows, WebKitGTK on Linux, WKWebView on macOS)
Linux builds require webkit2_41 build tag (passed to all Go commands)

Package Manager:

Go modules (go.mod) - lockfile: go.sum
pnpm - Frontend package manager; lockfile: frontend/pnpm-lock.yaml

Frameworks

Core:

Wails v2 (github.com/wailsapp/wails/v2 v2.10.2) - Desktop application framework bridging Go backend to WebView frontend
Lit (lit ^3.2.1) - Web Component framework for the frontend UI
Web Awesome (@awesome.me/webawesome ^3.2.1) - Icon library and component toolkit (icons via <wa-icon>)

Testing:

Go standard testing package with go test
Race detector enabled: -race flag

Build/Dev:

Make - Build orchestration (Makefile)
Wails CLI (go tool wails) - Dev server, production builds
Vite (^7.0.0) - Frontend bundler with HMR
golangci-lint v2 - Go linting and formatting

Key Dependencies

Go (Critical)

github.com/gopxl/beep/v2 v2.1.1 - Audio playback engine (MP3, FLAC, OGG, WAV decoding; speaker output; resampling; volume effects)
modernc.org/sqlite v1.45.0 - Pure-Go SQLite driver (no CGo required)
github.com/wailsapp/wails/v2 v2.10.2 - Desktop app framework (Go ↔ JS bridge, event system, window management)
github.com/dhowden/tag v0.0.0-20240417053706 - Audio metadata/tag extraction (ID3, Vorbis, FLAC tags)

Go (Infrastructure)

github.com/BurntSushi/toml v1.6.0 - TOML config file parsing/writing (config.toml)
github.com/godbus/dbus/v5 v5.1.0 - D-Bus integration for MPRIS2 media controls (Linux)
github.com/golang-cz/devslog v0.0.15 - Pretty-printed structured logging for development
golang.org/x/sync v0.19.0 - errgroup for concurrent library scanning
golang.org/x/image v0.12.0 - Image processing for cover art thumbnail generation
golang.org/x/text v0.34.0 - Unicode normalization for text processing
github.com/a-h/templ v0.3.977 - Type-safe HTML templating (used for config page fragments)

Go (Build Tools - declared in `tool` directive)

github.com/sqlc-dev/sqlc - SQL-to-Go code generator
github.com/a-h/templ/cmd/templ - Templ HTML template compiler
github.com/golangci/golangci-lint/v2/cmd/golangci-lint - Linter
github.com/evilmartians/lefthook - Git hooks manager
golang.org/x/vuln/cmd/govulncheck - Vulnerability scanner
github.com/wailsapp/wails/v2/cmd/wails - Wails CLI

Frontend (npm)

lit ^3.2.1 - Web Component framework (decorators, reactive properties, shadow DOM)
@awesome.me/webawesome ^3.2.1 - Web component library (icons)
@lit-labs/signals ^0.2.0 - Signal-based reactivity for Lit
@lit-labs/virtualizer ^2.1.1 - Virtual scrolling for large lists
vite ^7.0.0 - Build tool with HMR
typescript ^5.9.3 - TypeScript compiler
ts-lit-plugin ^2.0.2 - Lit template type checking
vite-plugin-static-copy ^3.0.0 - Static asset copying during build
stylelint-config-standard ^40.0.0 - CSS linting

Configuration

Application Config:

config.toml in user config directory (~/.config/yellowjacket/config.toml on Linux)
TOML format, managed by backend/config/config.go
Sections: [Library], [Theme], [Window], [TrackList], [Favorites]

Build Configuration:

wails.json - Wails project configuration (app name, frontend commands)
frontend/vite.config.mts - Vite bundler config with path aliases
frontend/tsconfig.json - TypeScript config (strict mode, decorators, path aliases)
.golangci.yml - golangci-lint v2 config (standard + extra linters, formatters)
backend/database/sqlc.yaml - sqlc code generation config
lefthook.yml - Git hooks (pre-commit: vet, lint, codegen-check, typecheck; pre-push: test, mod-verify, protect-main)

TypeScript Path Aliases (defined in both tsconfig.json and vite.config.mts):

@go/* → frontend/wailsjs/go/* (Wails Go bindings)
@components/* → frontend/src/components/*
@store/* → frontend/src/store/*
@runtime/* → frontend/wailsjs/runtime/* (Wails runtime JS)
@utils/* → frontend/src/utils/*
@assets/* → frontend/src/assets/*
@pages/* → frontend/src/pages/*

Environment:

No .env files detected - application is self-contained
Dev/prod detection via Go build tags: internal/dev/devbuild.go (//go:build dev) and internal/dev/nondevbuild.go (//go:build !dev)

Build System

Development:

make dev           # Full dev mode: install deps, generate, clean, wails dev with HMR
make lint          # golangci-lint v2 with all enabled linters
make test          # go test -tags webkit2_41 -race -count=1 -timeout 120s ./...

Production:

make build-prod    # wails build with -obfuscated -upx -ldflags "-s -w"

Key Differences (Dev vs Prod):

Aspect	Development	Production
Build tag	`dev` (enables `IsDev = true`)	`!dev` (default, `IsDev = false`)
Log level	`slog.LevelDebug`	`slog.LevelInfo`
Profiling	pprof server on `localhost:6060`, block/mutex profiling enabled	No-op (zero overhead, code eliminated by compiler)
Binary	Uncompressed, debug symbols	Obfuscated + UPX compressed, stripped (`-s -w`)
Version	`dev` (default)	Set via `LDFLAGS` from git tag/commit
Frontend	Vite dev server with HMR	Embedded in binary via `//go:embed all:frontend/dist`

Code Generation:

make generate      # Runs: go generate ./...

Triggers:

backend/app.go: //go:generate go tool templ generate (compiles .templ → *_templ.go)
backend/database/database.go: //go:generate go tool sqlc generate (compiles SQL → Go in backend/database/sql/sqlcgen/)

Git Hooks (lefthook):

Pre-commit: go vet, golangci-lint, codegen freshness check, frontend TypeScript typecheck
Pre-push: protect main branch, go test, go mod verify

Platform Requirements