1.7 KiB
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