167 lines
6.9 KiB
Markdown
167 lines
6.9 KiB
Markdown
# 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:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
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
|
|
|
|
**Development:**
|
|
- Go 1.25+
|
|
- pnpm (for frontend package management)
|
|
- Linux: WebKitGTK development headers (webkit2gtk-4.1)
|
|
- All Go commands require `-tags webkit2_41` build tag
|
|
|
|
**Production (Linux):**
|
|
- WebKitGTK 4.1 runtime libraries
|
|
- D-Bus session bus (for MPRIS2 media controls)
|
|
|
|
**Cross-Platform Support:**
|
|
- Linux: Full support (MPRIS2 media controls via D-Bus)
|
|
- macOS/Windows: Supported via Wails; media controls use no-op stub (`backend/mediacontrols/stub.go`)
|
|
- User data paths: `~/.local/share/yellowjacket/` (Linux), `~/Library/Application Support/yellowjacket/` (macOS), `%LOCALAPPDATA%\yellowjacket\` (Windows)
|
|
|
|
---
|
|
|
|
*Stack analysis: 2026-02-26*
|