From 07b11740bfaba5c5d49c948209375f199201f82a Mon Sep 17 00:00:00 2001
From: Michele Bigi <mikbigi@gmail.com>
Date: Sat, 1 Aug 2026 02:27:24 +0200
Subject: [PATCH] adr-000

---
 documents/ADR-000 — Engineering Philosophy.md | 97 +++++++++++++++++++
 .../HUBAudio_Bus_and_Pin_Assignment.md        |  0
 {docs => old_docs}/HUBAudio_HW_Design.md      |  0
 .../HUBAudio_I2C_Address_Map.md               |  0
 .../HUBAudio_Power_Management_Architecture.md |  0
 5 files changed, 97 insertions(+)
 create mode 100644 documents/ADR-000 — Engineering Philosophy.md
 rename {docs => old_docs}/HUBAudio_Bus_and_Pin_Assignment.md (100%)
 rename {docs => old_docs}/HUBAudio_HW_Design.md (100%)
 rename {docs => old_docs}/HUBAudio_I2C_Address_Map.md (100%)
 rename {docs => old_docs}/HUBAudio_Power_Management_Architecture.md (100%)

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