# Code Conventions

## Repository Map

- `README.org` — overall architecture
- `lib/FAPG/DAQ/` — shared Perl modules
- `roles/daq-node/` — probe reader script and node service (Pi Zeros)
- `roles/daq-hub/` — MQTT broker configuration (Pi 5)
- `roles/daq-recorder/` — MQTT-to-database recorder (VPS)
- `roles/dashboard/` — Mojolicious dashboard (VPS)
- `roles/vpn/` — WireGuard notes and host configs
- `t/` — end-to-end smoke tests and multi-role tests
- `CAD/` — enclosure design files

## Structure Rules

- Shared DAQ behavior goes under `lib/FAPG/DAQ/` when used by more than one role.
- Role-local code stays under that role's `lib`, `bin`, `etc`, or `t` tree.

## Perl

- Target Perl v5.32.1.
- Use strict/warnings.
- STDOUT and STDERR should provide useful diagnostics for the Systemd journal.
- After modifying Perl code:
  - Lint with Perl-Critic as severely as possible.
  - Reformat with Perl-Tidy using the `.perltidyrc` at the project root.
- Use `JSON::PP` for structured JSON parsing and generation.

## Shell

- Shell scripts use Bash.
- Follow Google's Bash shell style guide.
- Check with shellcheck for critical warnings after modifications.

## General

- All scripts begin with an appropriate shebang line.
- Executable bits on scripts must be preserved.