Developer Guide

Set up the LA-Mesh development environment, build the site, flash devices, and contribute.

Quick Start (Nix + direnv)

git clone https://github.com/Jesssullivan/LA-Mesh.git
cd LA-Mesh
direnv allow        # auto-enters Nix dev shell on cd
just info           # verify all tools are available

The Nix dev shell provides: meshtastic CLI, esptool.py, hackrf tools, bazelisk, just, nodejs, pnpm, git-cliff, shellcheck, ruff.

Without Nix: pip install meshtastic esptool ruff, npm install -g pnpm, cargo install just git-cliff.

Repository Structure

LA-Mesh/
├── site/              # SvelteKit documentation site
├── docs/              # Markdown documentation
├── configs/           # Device profiles and channel templates
├── bridges/           # SMS, email, MQTT bridge code
├── tools/             # Scripts: flash, test, configure, monitor
├── curriculum/        # Educational workshop modules
├── hardware/          # Inventory, BOM, deployment guides
├── firmware/          # Manifest, checksums, version pinning
└── captures/          # SDR capture storage (gitignored)

Common Just Recipes

Command	Purpose
`just dev`	Start docs site dev server (hot reload)
`just build`	Build site for production
`just check`	Run all validations (format + type check)
`just ci`	Full CI simulation (check + build)
`just provision <device> <port>`	One-command device provisioning
`just fetch-firmware`	Download and verify firmware
`just firmware-versions`	Show pinned firmware versions
`just firmware-check`	Check for upstream updates
`just mesh-info`	Show connected device info
`just mesh-nodes`	List visible mesh nodes
`just configure-profile <profile>`	Apply device configuration profile
`just configure-channels`	Apply LA-Mesh channel config

Branch Strategy

Branch	Purpose
`main`	Production -- deploys to GitHub Pages
`feature/*`	Feature development
`fix/*`	Bug fixes

PRs target main. CI must pass before merge.

CI/CD Workflows

Workflow	Trigger	Purpose
`ci.yml`	Push/PR to main	Lint, validate, build site
`deploy-pages.yml`	Push to main	Deploy GitHub Pages
`firmware-check.yml`	Weekly cron	Check for firmware updates
`security-scan.yml`	Push/PR to main	Gitleaks, ShellCheck, YAML lint

Security: Never Commit

Secrets (never committed -- use encrypted storage)
PSK values (channel encryption keys)
API keys (SMS gateway, SMTP, MQTT credentials)
Private keys (SSH, GPG, TLS)

Enable the pre-commit hook: git config core.hooksPath .githooks

Recommended Operating Systems

OS	Use Case
Linux Mint	Desktop OS for mesh operators -- stable, beginner-friendly, full hardware support
Rocky Linux	Server OS for gateway and bridge nodes -- enterprise-grade, long-term support