# OpenLogi Crate Map Explained: Purpose, Structure, and Developer Workflow

> Understand the OpenLogi crate map purpose, structure, and how it simplifies developer workflow. Discover crate responsibilities and dependency relationships in AprilNEA/OpenLogi.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: deep-dive
- Published: 2026-09-01

---

**The OpenLogi crate map is a high‑level architectural overview that lists every crate in the workspace, defines responsibilities, exposes dependency relationships, and guides contributors to the correct module for any change.**

The OpenLogi project is a Rust workspace for managing Logitech HID++ devices with a modular, cross‑platform architecture. The **OpenLogi crate map** serves as the single source of truth for how this workspace is organized, making it indispensable for both new contributors and maintainers. This article breaks down the purpose of the crate map, its structure, and how to use it effectively when navigating the codebase.

## What the OpenLogi Crate Map Achieves

The crate map documented in [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) fulfills six critical functions for the project:

### Architectural Transparency

The map groups crates by functional area—CLI, core types, HID++, device layer, UI, agent, overlay, IPC—making the project's modular split immediately visible. Rather than hunting through `crates/` directories, developers see at a glance how independent, well‑scoped modules compose the system.

### Clear Ownership Boundaries

Every crate entry includes a concise tagline defining its scope. For example, `openlogi-core` is described as *"Pure types: TOML config, device model, action catalog"*—explicitly stating what it owns and, by omission, what it does not. This prevents responsibility creep across crate boundaries.

### Dependency Visualization

Arrows and tables illustrate compile‑time relationships: `openlogi-device` depends on `openlogi-hidpp`, which in turn depends on the lower‑level `hidpp` crate; `openlogi-desktop` flows through `openlogi-ui` to `gpui`. These chains help developers anticipate the blast radius of changes.

### Onboarding Acceleration

New contributors can locate entry points without deep code archaeology. UI work? Start at `openlogi-ui`. HID++ protocol changes? Head to `openlogi-hidpp`. The crate map reduces cognitive load and encourages safe, scoped refactoring.

### Release Engineering Support

The `xtask` release tooling references the crate map to determine version bumps, documentation updates, and CI checks when changes touch specific modules. This automates consistency across the workspace.

### Cross‑Platform Clarity

Platform‑specific crates—`openlogi-hook`, `openlogi-inject`, `openlogi-hid`—are explicitly flagged. Developers are reminded that `#[cfg(target_os = …)]` code lives in isolated crates and must respect the project's cross‑platform rules.

## Complete OpenLogi Crate Reference

The following table lists all crates as documented in [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md), with their roles and source locations:

| Crate | Role | Source Path |
|-------|------|-------------|
| `openlogi` | CLI front‑end, thin wrapper over `openlogi-cli` | `crates/openlogi` |
| `openlogi-cli` | Command‑line dispatch, falls back to direct hardware enumeration | `crates/openlogi-cli` |
| `openlogi-core` | Pure data types: TOML config, device model, action catalog | `crates/openlogi-core` |
| `openlogi-device` | HID++ device layer (enumeration, probing, writes) | `crates/openlogi-device` |
| `openlogi-hidpp` | Hard‑fork of the `hidpp` protocol crate (protocol implementation) | `crates/openlogi-hidpp` |
| `openlogi-hid` | Host‑specific transport (`async-hid`, macOS Input Monitoring, probe cache) | `crates/openlogi-hid` |
| `openlogi-agent` | Runtime HID/input server (the "agent" process) | `crates/openlogi-agent` |
| `openlogi-agent-core` | Shared orchestration for DPI cycling, action‑ring sessions | `crates/openlogi-agent-core` |
| `openlogi-hook` | OS‑specific input capture (evdev, CGEventTap, WH_MOUSE_LL) | `crates/openlogi-hook` |
| `openlogi-inject` | OS‑specific input synthesis (SendInput, uinput, CGEvent) | `crates/openlogi-inject` |
| `openlogi-ui` | Shared UI assets, GPUI geometry and icons | `crates/openlogi-ui` |
| `openlogi-desktop` | Full GPUI desktop application (main GUI) | `crates/openlogi-desktop` |
| `openlogi-overlay` | Minimal IPC client for the Actions Ring cursor‑centred overlay | `crates/openlogi-overlay` |
| `openlogi-ipc` | tarpc/bincode IPC contract and transport implementation | `crates/openlogi-ipc` |
| `openlogi-camera` | Logitech UVC enumeration, capture, camera‑permission APIs | `crates/openlogi-camera` |
| `openlogi-assets` | Device‑render registry and cached asset fetching | `crates/openlogi-assets` |
| `openlogi-permissions` | Privacy‑permission status handling (macOS TCC, Linux device files) | `crates/openlogi-permissions` |

## Practical Workflow: Using the Crate Map for Changes

The crate map transforms abstract architecture into actionable navigation. Consider adding a new DPI step to a Logitech mouse:

1. **Identify the device layer**: The `openlogi-device` crate owns all device writes—start at [`crates/openlogi-device/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-device/src/lib.rs).

2. **Trace to protocol implementation**: Follow the dependency to `openlogi-hidpp` for low‑level command encoding at [`crates/openlogi-hidpp/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hidpp/src/lib.rs).

3. **Surface in UI if needed**: Edit `openlogi-ui` for shared components, then `openlogi-desktop` at [`crates/openlogi-desktop/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/lib.rs) to expose the new setting in the main GUI.

Without the crate map, this chain would require reverse‑engineering [`Cargo.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/Cargo.toml) files and guessing at responsibility boundaries. The map makes these steps explicit, preventing accidental edits in unrelated crates.

## Key Files for Deep Dives

| File | Purpose |
|------|---------|
| [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) (crate map section) | Authoritative listing of crates, responsibilities, and dependencies |
| [`crates/openlogi-core/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/lib.rs) | Pure data structures used across the workspace |
| [`crates/openlogi-device/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-device/src/lib.rs) | Central hub for device operations and HID++ writes |
| [`crates/openlogi-ipc/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/src/lib.rs) | IPC contract for desktop, overlay, and agent processes |
| [`crates/openlogi-desktop/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/lib.rs) | Main GUI logic consuming UI crate and agent IPC |
| [`crates/openlogi-overlay/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-overlay/src/lib.rs) | Minimal client demonstrating overlay‑to‑agent IPC usage |

## Summary

- The **OpenLogi crate map** in [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) is the backbone of the project's modular design.

- It provides **architectural transparency**, **clear ownership**, **dependency visualization**, **onboarding guidance**, **release automation**, and **cross‑platform awareness**.

- All 17 crates are grouped by function with explicit roles, from `openlogi-core` (pure types) to `openlogi-desktop` (full GUI) and `openlogi-overlay` (minimal IPC client).

- Contributors should consult the crate map before any change to identify the correct entry point and understand dependency chains.

## Frequently Asked Questions

### Where is the OpenLogi crate map documented?

The crate map is documented in the [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) file at the repository root, specifically in its dedicated crate map section. This file serves as the authoritative reference for all crate responsibilities and inter‑dependencies in the OpenLogi workspace.

### How do I know which crate to modify for a feature?

Consult the crate map's role descriptions. UI changes flow through `openlogi-ui` and `openlogi-desktop`; device protocol work belongs in `openlogi-device` and `openlogi-hidpp`; platform‑specific input handling targets `openlogi-hook` or `openlogi-inject`. The map's dependency arrows then confirm which downstream crates may need updates.

### What is the difference between `openlogi-agent` and `openlogi-agent-core`?

`openlogi-agent` is the runtime HID/input server process, while `openlogi-agent-core` provides shared orchestration logic used by that agent—such as DPI cycling and action‑ring session management. The core crate enables code reuse without pulling in the full agent runtime.

### Why are platform‑specific crates like `openlogi-hook` isolated?

Isolation enforces cross‑platform discipline. By containing `#[cfg(target_os = …)]` code in dedicated crates, the crate map ensures developers cannot accidentally introduce platform‑specific logic into shared modules. This makes porting easier and compile‑time failures occur in predictable locations.