HLD & Architecture Plan for Mjolnir v1.0 #5

New Issue

2026-08-03T22:18:34Z

xavierk commented

2026-08-03 22:18:34 +00:00

Destination

A complete High-Level Design document for Mjolnir v1.0 covering component architecture, data model, IPC contracts (D-Bus + Netlink), CLI contract, and Architectural Decision Records for all 13 epics — ready to hand off for implementation.

Notes

Source of truth: docs/mjolnir-srs-v0.9.md (APPROVAL CANDIDATE, v0.9, 81 FRs, 13 epics)
Architecture decisions made: Rust userspace (daemon, CLI, GTK) + C kernel module; Netlink IPC; SQLite store; rule-based policy engine; gtk4-rs UI; Cargo + Kbuild
Runtime stack decided: tokio + zbus (#4); zbus_polkit for polkit; refinery for SQLite migrations
DB stack decided: WAL mode, synchronous=FULL, rusqlite + refinery (#13); telemetry as JSON TEXT columns; application-level retention purge
Build stack decided: just command runner, 12-target justfile, DKMS with AUTOINSTALL, Cargo+Kbuild independent build order, binaries to /usr/local/bin. See ADR-004.
Skills: domain-modeling for glossary/ADR creation, grilling for design decisions
Solo developer (Bongbetic), one reference machine (MSI Thin A15 B7UCX: AMD 7535HS + RTX 2050)
Monorepo layout: mjolnird/, mjolnir-km/, mjolnirctl/, mjolnir-gtk/

Decisions so far

Research: Survey existing Linux power management D-Bus APIs and Netlink patterns — D-Bus: system bus, property-centric, PolKit-guarded. Netlink: generic netlink family; neli or rust-netlink viable. See docs/research/dbus-netlink-patterns.md.
Grilling: Component architecture and internal module boundaries — Two shared crates (mjolnir-core + mjolnir-client), 5-member Cargo workspace, 12 internal modules in mjolnird, pull telemetry/push commands data flow, probe-first startup sequencing. See ADR-001.
Grilling: Netlink protocol / kernel-module userspace interface — One "mjolnir" genl family, governor + telemetry cmd groups, nested attributes, monotonic u8 strict-match version, neli crate, error+degradation protocol. See ADR-002.
Task: Netlink protocol — daemon↔kernel module IPC design — 4 commands, 14 attributes, 7 error codes, wire format with nested energy/C-state residency, version negotiation, neli integration, kernel registration template, 9-section spec. See docs/spec/netlink-protocol-spec.md.
Grilling: D-Bus API contract — 4 interfaces on one object, 13 properties (3 readwrite), 8 methods, 9 signals, 9 error codes, 9 PolKit actions, string enums. See ADR-003.
Research: Async runtime + D-Bus library choice for the Rust daemon — tokio + zbus selected; zbus_polkit v5.0.0 for polkit; zbus tokio feature for zero-thread-overhead; GTK4 is separate process with its own GLib loop. See docs/research/async-runtime-dbus-choice.md.
Grilling: SQLite data model and schema — 15 SQLite tables + 2 materialized aggregates, WAL mode, synchronous=FULL, refinery migrations, source discriminator column for simulated manifests, application-level retention purge. #6 superseded.
Grilling: Build sequencing and dependency order — just build tool, 12-target justfile, DKMS with AUTOINSTALL, Cargo+Kbuild independent build order, binaries to /usr/local/bin, development workflow. See ADR-004.
Grilling: CLI contract — mjolnirctl commands and output formats — Resource-oriented command hierarchy, deterministic human/JSON output, stable exit/error mappings, D-Bus-only connectivity, and attached validation workflows. See docs/cli-contract.md; pending D-Bus prerequisites belong to Task: D-Bus API contract — XML interface for all 13 epics.
Task: Module lifecycle protocol — DKMS, validation, boot-count guard — SQLite persistence for validation records and boot-attempt counter, 120s clean-boot threshold, modprobe.d blacklist gate, GRUB snapshot recovery entry, interactive validation via StartValidationRun D-Bus method. See ADR-006.
Task: TOML configuration schema — versioned, strictly validated — Canonical portable configuration boundary settled; unresolved policy and cross-surface contracts split into dependent decisions.
GTK app architecture — view tree, D-Bus client, tray lifecycle — Adaptive split navigation, Tokio plus GLib D-Bus client, resident GTK process, SNI fallback, notifications, and capability gating. See docs/spec/gtk-app-architecture-spec.md.
Grilling: Internal module decomposition for mjolnird — 12 modules + main.rs confirmed; HAL sole hardware writer; dbus.rs dispatch layer; policy.rs sole mode arbiter (Thermal > User > Event hook > App rule > Auto); nine-phase startup; three-tier panic isolation. See ADR-005, docs/architecture/modules.md.
Grilling: ModeProfile semantics — KnobId, target types, Auto and Normal — 8 closed KnobIds, KnobTarget tagged type (Set/AutoRange/Untouched/Snapshot), global Auto thresholds, topology-relative granularity, idle-consolidation lives in governor, Normal uses Snapshot sentinel. See ADR-007.
Grilling: Auto policy thresholds — demand, hysteresis, and advisory cost — Composite demand formula (three-way weighted EMA: utilisation/runqueue/thermal), sustained window evaluated via rolling EMA at 15s tick, per-knob write cooldown, AC/battery differentiated defaults, advisory cost = demand composite with TOML-configurable snooze.
Grilling: Charge preset mapping — start hysteresis for 60, 80, and 100 percent — Preset numeric pairs: 60→50-60, 80→70-80, 100→100-100 (rule-based with cap, 100% no hysteresis). Presets UI-only apply-buttons; TOML stores only start_percent/end_percent. Capability degradation: store both, partial apply, capability_unsupported diagnostic, round-trip portable.
Grilling: Event hook contract — conditions, precedence, and lifecycle — Six-event closed enum, unconditional one-shot, duplicate-reject, priority-ladder override, no auto-restoration, full CRUD via D-Bus + CLI, strict validation. See ADR-008.

Open tickets

Not yet specified

Per-epic ADRs for specific trade-off analyses (emerge as design work resolves)

Out of scope

Implementation (this map delivers the HLD, not code)
Hardware verification (blocked on implementation existing first)
CI/CD pipeline design (deferred until build system is proven)
SQLite schema file creation — #6 closed, superseded by #13 decisions

Migrated from github.com/soubarnak/Mjolnir#1

## Destination A complete High-Level Design document for Mjolnir v1.0 covering component architecture, data model, IPC contracts (D-Bus + Netlink), CLI contract, and Architectural Decision Records for all 13 epics — ready to hand off for implementation. ## Notes - Source of truth: `docs/mjolnir-srs-v0.9.md` (APPROVAL CANDIDATE, v0.9, 81 FRs, 13 epics) - Architecture decisions made: Rust userspace (daemon, CLI, GTK) + C kernel module; Netlink IPC; SQLite store; rule-based policy engine; gtk4-rs UI; Cargo + Kbuild - Runtime stack decided: **tokio + zbus** (#4); zbus_polkit for polkit; refinery for SQLite migrations - DB stack decided: **WAL mode, synchronous=FULL, rusqlite + refinery** (#13); telemetry as JSON TEXT columns; application-level retention purge - Build stack decided: **just** command runner, 12-target `justfile`, DKMS with AUTOINSTALL, Cargo+Kbuild independent build order, binaries to /usr/local/bin. See ADR-004. - Skills: `domain-modeling` for glossary/ADR creation, `grilling` for design decisions - Solo developer (Bongbetic), one reference machine (MSI Thin A15 B7UCX: AMD 7535HS + RTX 2050) - Monorepo layout: `mjolnird/`, `mjolnir-km/`, `mjolnirctl/`, `mjolnir-gtk/` ## Decisions so far - [Research: Survey existing Linux power management D-Bus APIs and Netlink patterns](https://github.com/soubarnak/Mjolnir/issues/9) — D-Bus: system bus, property-centric, PolKit-guarded. Netlink: generic netlink family; neli or rust-netlink viable. See `docs/research/dbus-netlink-patterns.md`. - [Grilling: Component architecture and internal module boundaries](https://github.com/soubarnak/Mjolnir/issues/10) — Two shared crates (`mjolnir-core` + `mjolnir-client`), 5-member Cargo workspace, 12 internal modules in mjolnird, pull telemetry/push commands data flow, probe-first startup sequencing. See ADR-001. - [Grilling: Netlink protocol / kernel-module userspace interface](https://github.com/soubarnak/Mjolnir/issues/11) — One "mjolnir" genl family, governor + telemetry cmd groups, nested attributes, monotonic u8 strict-match version, neli crate, error+degradation protocol. See ADR-002. - [Task: Netlink protocol — daemon↔kernel module IPC design](https://github.com/soubarnak/Mjolnir/issues/3) — 4 commands, 14 attributes, 7 error codes, wire format with nested energy/C-state residency, version negotiation, neli integration, kernel registration template, 9-section spec. See `docs/spec/netlink-protocol-spec.md`. - [Grilling: D-Bus API contract](https://github.com/soubarnak/Mjolnir/issues/12) — 4 interfaces on one object, 13 properties (3 readwrite), 8 methods, 9 signals, 9 error codes, 9 PolKit actions, string enums. See ADR-003. - [Research: Async runtime + D-Bus library choice for the Rust daemon](https://github.com/soubarnak/Mjolnir/issues/4) — **tokio + zbus** selected; zbus_polkit v5.0.0 for polkit; zbus tokio feature for zero-thread-overhead; GTK4 is separate process with its own GLib loop. See `docs/research/async-runtime-dbus-choice.md`. - [Grilling: SQLite data model and schema](https://github.com/soubarnak/Mjolnir/issues/13) — 15 SQLite tables + 2 materialized aggregates, WAL mode, synchronous=FULL, refinery migrations, `source` discriminator column for simulated manifests, application-level retention purge. #6 superseded. - [Grilling: Build sequencing and dependency order](https://github.com/soubarnak/Mjolnir/issues/14) — `just` build tool, 12-target `justfile`, DKMS with AUTOINSTALL, Cargo+Kbuild independent build order, binaries to /usr/local/bin, development workflow. See ADR-004. - [Grilling: CLI contract — mjolnirctl commands and output formats](https://github.com/soubarnak/Mjolnir/issues/15) — Resource-oriented command hierarchy, deterministic human/JSON output, stable exit/error mappings, D-Bus-only connectivity, and attached validation workflows. See `docs/cli-contract.md`; pending D-Bus prerequisites belong to [Task: D-Bus API contract — XML interface for all 13 epics](https://github.com/soubarnak/Mjolnir/issues/2). - [Task: Module lifecycle protocol — DKMS, validation, boot-count guard](https://github.com/soubarnak/Mjolnir/issues/5) — SQLite persistence for validation records and boot-attempt counter, 120s clean-boot threshold, modprobe.d blacklist gate, GRUB snapshot recovery entry, interactive validation via `StartValidationRun` D-Bus method. See ADR-006. - [Task: TOML configuration schema — versioned, strictly validated](https://github.com/soubarnak/Mjolnir/issues/7) — Canonical portable configuration boundary settled; unresolved policy and cross-surface contracts split into dependent decisions. - [GTK app architecture — view tree, D-Bus client, tray lifecycle](https://github.com/soubarnak/Mjolnir/issues/8) — Adaptive split navigation, Tokio plus GLib D-Bus client, resident GTK process, SNI fallback, notifications, and capability gating. See `docs/spec/gtk-app-architecture-spec.md`. - [Grilling: Internal module decomposition for mjolnird](https://github.com/soubarnak/Mjolnir/issues/16) — 12 modules + main.rs confirmed; HAL sole hardware writer; dbus.rs dispatch layer; policy.rs sole mode arbiter (Thermal > User > Event hook > App rule > Auto); nine-phase startup; three-tier panic isolation. See ADR-005, `docs/architecture/modules.md`. - [Grilling: ModeProfile semantics — KnobId, target types, Auto and Normal](https://github.com/soubarnak/Mjolnir/issues/17) — 8 closed KnobIds, KnobTarget tagged type (Set/AutoRange/Untouched/Snapshot), global Auto thresholds, topology-relative granularity, idle-consolidation lives in governor, Normal uses Snapshot sentinel. See ADR-007. - [Grilling: Auto policy thresholds — demand, hysteresis, and advisory cost](https://github.com/soubarnak/Mjolnir/issues/19) — Composite demand formula (three-way weighted EMA: utilisation/runqueue/thermal), sustained window evaluated via rolling EMA at 15s tick, per-knob write cooldown, AC/battery differentiated defaults, advisory cost = demand composite with TOML-configurable snooze. - [Grilling: Charge preset mapping — start hysteresis for 60, 80, and 100 percent](https://github.com/soubarnak/Mjolnir/issues/21) — Preset numeric pairs: 60→50-60, 80→70-80, 100→100-100 (rule-based with cap, 100% no hysteresis). Presets UI-only apply-buttons; TOML stores only start_percent/end_percent. Capability degradation: store both, partial apply, capability_unsupported diagnostic, round-trip portable. - [Grilling: Event hook contract — conditions, precedence, and lifecycle](https://github.com/soubarnak/Mjolnir/issues/22) — Six-event closed enum, unconditional one-shot, duplicate-reject, priority-ladder override, no auto-restoration, full CRUD via D-Bus + CLI, strict validation. See ADR-008. ## Open tickets - [Task: D-Bus API contract — XML interface for all 13 epics](https://github.com/soubarnak/Mjolnir/issues/2) (claimed by soubarnak) - [Grilling: Finalize complete TOML field schema after dependency decisions](https://github.com/soubarnak/Mjolnir/issues/18) (blocked by #20) - [Grilling: Per-app rule contract — identity, precedence, and restoration](https://github.com/soubarnak/Mjolnir/issues/20) - [Grilling: Testing strategy — unit, integration, simulated-manifest, VM, and physical layers](https://github.com/soubarnak/Mjolnir/issues/23) ## Not yet specified - Per-epic ADRs for specific trade-off analyses (emerge as design work resolves) ## Out of scope - Implementation (this map delivers the HLD, not code) - Hardware verification (blocked on implementation existing first) - CI/CD pipeline design (deferred until build system is proven) - SQLite schema file creation — #6 closed, superseded by #13 decisions --- *Migrated from github.com/soubarnak/Mjolnir#1*

xavierk added the wayfinder:map label 2026-08-03 22:18:34 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xavierk/Mjolnir#5