diff --git a/documents/ADR-000 — Engineering Philosophy.md b/documents/ADR-000 — Engineering Philosophy.md new file mode 100644 index 0000000..7ccb993 --- /dev/null +++ b/documents/ADR-000 — Engineering Philosophy.md @@ -0,0 +1,97 @@ +# ADR-000 — HubAudio Engineering Philosophy + +**Status:** Accepted + +**Date:** 2026-08-01 + +--- + +## Purpose + +HubAudio is designed as a professional embedded platform. + +The primary objective is **maintainability**, followed by extensibility, robustness and performance. + +The architecture shall minimise cognitive load for future developers. + +--- + +# Core Principles + +## 1. Code that fits in your head + +Every class, function and module shall be understandable in isolation. + +If understanding a module requires reading large portions of the codebase, the design should be reconsidered. + +Complexity must never be hidden. + +--- + +## 2. One Responsibility + +Every module has exactly one responsibility. + +Examples: + +- PowerManager +- DSPManager +- RadioManager +- BluetoothManager +- AudioRouter + +Responsibilities shall never overlap. + +--- + +## 3. Hardware is software controlled + +Every subsystem should, whenever technically possible, support: + +- independent power control +- independent reset +- diagnostics +- firmware update + +--- + +## 4. Digital-first architecture + +Audio remains digital until external conversion is explicitly required. + +The DSP is the centre of the audio routing architecture. + +--- + +## 5. Documentation is part of the product + +Documentation is considered part of the deliverable. + +Every architectural decision shall be documented. + +--- + +## 6. Simplicity over cleverness + +The simplest correct solution is preferred. + +Elegant architecture is preferred over clever implementation. + +--- + +## 7. Small incremental changes + +The project evolves through small, reviewable improvements. + +Large architectural changes shall be avoided unless justified. + +--- + +# Definition of Done + +A feature is considered complete only when: + +- implemented +- documented +- testable +- understandable \ No newline at end of file diff --git a/docs/HUBAudio_Bus_and_Pin_Assignment.md b/old_docs/HUBAudio_Bus_and_Pin_Assignment.md similarity index 100% rename from docs/HUBAudio_Bus_and_Pin_Assignment.md rename to old_docs/HUBAudio_Bus_and_Pin_Assignment.md diff --git a/docs/HUBAudio_HW_Design.md b/old_docs/HUBAudio_HW_Design.md similarity index 100% rename from docs/HUBAudio_HW_Design.md rename to old_docs/HUBAudio_HW_Design.md diff --git a/docs/HUBAudio_I2C_Address_Map.md b/old_docs/HUBAudio_I2C_Address_Map.md similarity index 100% rename from docs/HUBAudio_I2C_Address_Map.md rename to old_docs/HUBAudio_I2C_Address_Map.md diff --git a/docs/HUBAudio_Power_Management_Architecture.md b/old_docs/HUBAudio_Power_Management_Architecture.md similarity index 100% rename from docs/HUBAudio_Power_Management_Architecture.md rename to old_docs/HUBAudio_Power_Management_Architecture.md