docs: architecture map (initial 5-slice generation, 105 pages)
Five-slice navigable map of the entire codebase under
docs/architecture-map/. Each slice is a self-contained
breadcrumbed sub-tree:
01-frontend (16) Svelte/SvelteKit UI
02-tauri-runtime (26) src-tauri commands + lifecycle
03-audio-transcription (16) audio + transcription crates
04-llm-formatting-mcp (19) llm, ai-formatting, mcp, cloud
05-core-storage-hotkey-build core, storage, hotkey, workspace,
(26) CI, dev glue
Plus master README.md and data-flow-end-to-end.md tracing
audio bytes from microphone to FTS5 search to MCP read.
Generated by 5 parallel subagents on 2026/05/09 against
HEAD 3c47000. Each page has YAML frontmatter, file:line code
refs, sibling cross-links, plain-English summaries.
Aggregated debt surfaced (full lists in master README):
RB-08 macOS power assertion, schema head drift v14 vs v15,
VAD blocked on ort version conflict, streaming primitives
not wired into live.rs, no prompt versioning, MCP has no
auth, cloud-providers in-memory keystore, SettingsPage
2 484 LOC, commands/live.rs 1 737 LOC, dual theme system,
brand rename to Lumenote pending across the codebase.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
jars
@@ -0,0 +1,162 @@
|
||||
---
|
||||
name: CI pipeline
|
||||
type: architecture-map-page
|
||||
slice: 05-core-storage-hotkey-build
|
||||
last_verified: 2026/05/09
|
||||
---
|
||||
|
||||
# CI pipeline
|
||||
|
||||
> **Where you are:** [Architecture map](../README.md) → [Core, Storage, Hotkey, Build](README.md) → CI pipeline
|
||||
|
||||
**Plain English summary.** Three GitHub Actions workflows. `check.yml` runs per-push compile + lint + library tests + frontend build on Linux, Windows, and macOS. `build.yml` produces installer artefacts (.AppImage/.deb on Linux, .msi/.exe on Windows, .dmg/.app on macOS) for tag pushes and on-demand. `audit.yml` runs cargo-audit and npm-audit weekly.
|
||||
|
||||
## At a glance
|
||||
|
||||
- Files: `.github/workflows/check.yml`, `build.yml`, `audit.yml`.
|
||||
- LOC: 7,017 + 7,157 + 1,443 bytes respectively.
|
||||
- Shared concerns across check and build: same Linux / macOS / Windows system-package install steps (libwebkit2gtk, Vulkan SDK, libclang for bindgen), same `Swatinem/rust-cache@v2` cache scoping (`workspaces: .` because the workspace target dir is `./target`, **not `src-tauri/target`** — this was the silent miss that made Windows checks slow).
|
||||
|
||||
## `check.yml` — per-push compile + lint + tests
|
||||
|
||||
### Triggers
|
||||
|
||||
```yaml
|
||||
on: [push, pull_request]
|
||||
concurrency:
|
||||
group: check-${{ github.ref }}
|
||||
cancel-in-progress: true # newer push supersedes older
|
||||
```
|
||||
|
||||
### Jobs
|
||||
|
||||
#### `rust` — matrix
|
||||
|
||||
```yaml
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
os: [ubuntu-22.04, windows-latest, macos-latest]
|
||||
```
|
||||
|
||||
Steps per OS:
|
||||
|
||||
1. **Install system deps** — libwebkit2gtk-4.1, libappindicator3, librsvg2, libasound2, libudev, patchelf, cmake, build-essential, libclang, clang, libvulkan, glslang-tools, spirv-tools (Linux); Homebrew vulkan-headers, vulkan-loader, molten-vk, shaderc, llvm (macOS); choco llvm + vulkan-sdk (Windows). Each install resolves `LIBCLANG_PATH` / `VULKAN_SDK` dynamically so a minor SDK version bump does not hardcode-break the step.
|
||||
2. `dtolnay/rust-toolchain@stable` with `rustfmt, clippy`.
|
||||
3. `Swatinem/rust-cache@v2` with `workspaces: .` and shared key `magnotia-${{ matrix.os }}`.
|
||||
4. `cargo check --workspace --all-targets`.
|
||||
5. `cargo fmt --all -- --check`.
|
||||
6. `cargo clippy --workspace --all-targets -- -D warnings`.
|
||||
7. `cargo test --workspace --lib` (Linux only, gated on `matrix.os == 'ubuntu-22.04'`).
|
||||
8. `cargo audit` (Linux only).
|
||||
|
||||
The Linux-only gating on tests + audit keeps macOS and Windows legs focused on compile coverage. The library-tests-only flag (`--lib`) excludes integration tests that need a runtime / GPU.
|
||||
|
||||
#### `frontend` — Linux only
|
||||
|
||||
1. Setup Node 20.
|
||||
2. `npm ci`.
|
||||
3. `npm audit --audit-level=high`.
|
||||
4. `npm run build` — Vite-only build (no `tauri build`).
|
||||
5. `svelte-check` for type and template errors.
|
||||
|
||||
### Why the workspace cache scope matters
|
||||
|
||||
The original CI step pointed `Swatinem/rust-cache@v2` at `workspaces: src-tauri`. The workspace target dir is at `./target` (defined by the repo-root `Cargo.toml`), not `src-tauri/target`. That meant the cache silently missed every run, and Windows check runs felt like they recompiled `sqlx` from scratch every time. Documented inline at `check.yml`. The current scope `workspaces: .` is the fix.
|
||||
|
||||
## `build.yml` — release artefacts
|
||||
|
||||
### Triggers
|
||||
|
||||
```yaml
|
||||
on:
|
||||
push:
|
||||
tags: ['v*'] # tagged releases (v0.1.0, v0.2.0, ...)
|
||||
workflow_dispatch: # manual, any branch
|
||||
inputs:
|
||||
tag_name:
|
||||
description: 'Optional tag name to attach the build to'
|
||||
required: false
|
||||
```
|
||||
|
||||
`workflow_dispatch` lets us build a Windows binary on demand to dual-boot test without cutting a release.
|
||||
|
||||
### Concurrency
|
||||
|
||||
```yaml
|
||||
concurrency:
|
||||
group: build-${{ github.ref }}
|
||||
cancel-in-progress: false # release builds finish even on tag re-pushes
|
||||
```
|
||||
|
||||
Different from `check.yml`: a release build is too expensive to abandon mid-flight.
|
||||
|
||||
### Matrix
|
||||
|
||||
```yaml
|
||||
include:
|
||||
- os: ubuntu-22.04 artefacts: *.AppImage, *.deb
|
||||
- os: windows-latest artefacts: *.msi, *.exe
|
||||
- os: macos-latest artefacts: *.dmg, *.app
|
||||
```
|
||||
|
||||
### Steps
|
||||
|
||||
1. System deps (same as `check.yml`).
|
||||
2. Rust toolchain.
|
||||
3. Cache (`shared-key: magnotia-build-${{ matrix.os }}`, distinct from check.yml's key so the build cache is not invalidated by check runs).
|
||||
4. `npm ci`.
|
||||
5. `tauri-apps/tauri-action@v0` — runs `tauri build`. On tag pushes, attaches artefacts to a draft GitHub Release. Empty `tagName` for `workflow_dispatch` so we get artefacts only.
|
||||
6. `actions/upload-artifact@v4` — always uploads to the run page (30-day retention) so the workflow_dispatch path produces something downloadable too.
|
||||
7. `du -h` on the produced bundle directory for visibility.
|
||||
|
||||
### Code signing
|
||||
|
||||
**Not configured.** Both macOS (Apple Developer ID) and Windows (code-signing certificate) signing blocks are commented out in `build.yml`. Users hit Gatekeeper / SmartScreen on first run.
|
||||
|
||||
To enable later:
|
||||
|
||||
- **macOS:** uncomment the `APPLE_SIGNING_IDENTITY` / `APPLE_CERTIFICATE` / `APPLE_CERTIFICATE_PASSWORD` env block; add the corresponding repo secrets.
|
||||
- **Windows:** uncomment the `WINDOWS_CERTIFICATE` / `WINDOWS_CERTIFICATE_PASSWORD` env block; add the secrets.
|
||||
|
||||
Documented in the file header.
|
||||
|
||||
## `audit.yml` — weekly vulnerability scan
|
||||
|
||||
### Triggers
|
||||
|
||||
```yaml
|
||||
on:
|
||||
schedule:
|
||||
- cron: "0 6 * * 1" # Mondays 06:00 UTC
|
||||
workflow_dispatch:
|
||||
```
|
||||
|
||||
Mondays so any advisory has the whole week to be triaged rather than landing on a Friday.
|
||||
|
||||
### Jobs
|
||||
|
||||
#### `cargo-audit`
|
||||
|
||||
Uses `rustsec/audit-check@v2` against the RustSec advisory DB. Fails on any unignored advisory.
|
||||
|
||||
#### `npm-audit`
|
||||
|
||||
`npm audit --audit-level=high`. Ignores low / moderate noise — only high and critical advisories warrant a bump.
|
||||
|
||||
### Why a separate workflow?
|
||||
|
||||
A newly published advisory surfaces as its own failing run (easy to spot, easy to track) without blocking unrelated PR work. The same `cargo audit` runs as part of `check.yml` on every push, so this workflow is the catch-all for advisories that land between pushes.
|
||||
|
||||
## Watch-outs
|
||||
|
||||
- **`cargo audit` runs in two places.** `check.yml` (Linux only, on every push) and `audit.yml` (weekly). The duplication is cheap and useful.
|
||||
- **`tauri-action@v0` is unpinned.** `@v0` floats. A breaking change in tauri-action would surface on the next release attempt. Worth pinning to a specific version when v0.1 ships.
|
||||
- **macOS `LIBCLANG_PATH` resolution.** `brew --prefix llvm` resolves to the Apple Silicon path on M-series runners (`/opt/homebrew/...`) and the Intel path on intel runners (`/usr/local/...`). The dynamic resolution handles both.
|
||||
- **Linux runners use Ubuntu 22.04, not 24.04.** Pinned because 22.04's `libwebkit2gtk-4.1` package is stable; 24.04's namespace shifted. Worth re-evaluating once GitHub Actions retires 22.04.
|
||||
- **No nightly clippy.** The `-D warnings` clippy step uses stable. A nightly canary job would catch upcoming lint changes earlier.
|
||||
|
||||
## See also
|
||||
|
||||
- [Workspace Cargo.toml](workspace-cargo.md) — the release profile this CI consumes.
|
||||
- [Dev launcher and scripts](dev-launcher-and-scripts.md) — local equivalent.
|
||||
Reference in New Issue
Block a user