# Repository Guidelines

## Project Structure & Module Organization

This repository records a provisional centrifuge electronics design; it contains no firmware implementation or released hardware design.

- `README.md`: current decisions, open questions, and file index.
- `docs/`: architecture, pin assignments, procurement snapshots, and source references.
- `data/`: editable CSVs for GPIO allocation, reserved pins, I2C devices, and 24 client requirements.
- `research/`: archived schematics, pinout images, and extracted reference text.
- `presentation/centrifuge-architecture.html`: standalone architecture presentation with embedded styling and scripts.

Use `docs/architecture.md` and `docs/pin-assignment.md` for current wiring decisions; the presentation preserves an earlier discussion.

## Architecture Overview

The main blocks are the RP2350 touchscreen HMI, ESP32-S3-ETH supervisor, separate motor drive, interface carrier, machine sensors/actuators, communications/storage, and independent protective circuitry. The HMI handles interaction; the supervisor owns machine sequencing and records; the motor board regulates speed. The carrier provides conditioning, drivers, expansion, timekeeping, and interface hardware. Preserve these responsibility boundaries when proposing changes.

## Build, Test, and Development Commands

No build system, dependency manifest, automated test runner, or lint configuration is present.

- `python3 -m http.server 8000 --bind 127.0.0.1`: serve the repository locally; open `http://127.0.0.1:8000/presentation/centrifuge-architecture.html` to preview slides.
- `rg -n 'GPIO|RS485|UART' docs data README.md`: locate related definitions before changing interfaces.

## Coding Style & Naming Conventions

Use descriptive Markdown headings, relative links, and tables for allocations. Follow existing lowercase, hyphenated document names, such as `pin-assignment.md`. Preserve CSV headers, column order, requirement IDs, and hexadecimal I2C address notation. No indentation standard is enforced; use spaces consistently in new code snippets and avoid unrelated reformatting of compact HTML.

## Testing Guidelines

There is no test framework or coverage threshold. Check local links and CSV row consistency. For allocation changes, verify unique GPIOs, reserved-pin exclusions, distinct I2C addresses, and agreement between CSVs and documentation. For presentation edits, manually check navigation, notes, reading mode, and print layout. Record checks performed; document consistency does not establish hardware validation.

## Commit & Pull Request Guidelines

This workspace has no Git metadata, so historical commit conventions cannot be established. When versioned, use concise imperative subjects, for example `docs: clarify motor interface assumptions`. Include rationale, affected files, source references, checks performed, and unresolved assumptions. Link relevant issues; attach screenshots for presentation changes.

## Evidence & Design Status

Distinguish selected components, proposed interfaces, and verified results. Add technical references to `docs/sources.md`; date procurement observations. Preserve explicit uncertainty around motor protocols, independent protection, and hardware qualification.