5.5 KiB
HubAudio Engineering Principles
Document: Engineering Principles
Version: 0.1 (Draft)
Status: Draft
Applies to: Entire HubAudio Project
1. Purpose
This document defines the engineering principles that govern the design, development, documentation and maintenance of the HubAudio platform.
These principles apply equally to:
- Hardware
- Firmware
- Documentation
- Architecture
- Development tools
Every engineering decision shall be consistent with these principles.
Whenever a principle cannot be respected, the reason shall be documented through an Architecture Decision Record (ADR).
2. Vision
HubAudio is not simply an electronic board.
HubAudio is an embedded digital audio platform designed to evolve over many years while remaining understandable, maintainable and reliable.
The project values engineering quality over feature quantity.
Every design decision should reduce complexity rather than increase it.
3. Core Values
The project follows these values, listed in order of importance.
- Understandability
- Maintainability
- Reliability
- Modularity
- Extensibility
- Performance
Performance is important.
Understanding the system is more important.
4. Fundamental Principle
EP-001 — Code That Fits in Your Head
This is the fundamental engineering principle of HubAudio.
The concept applies to every engineering artifact.
An engineering artifact includes:
- Source code
- Electrical schematics
- PCB layout
- Documentation
- Architecture diagrams
- Firmware modules
- Test procedures
- Design notes
Every engineering artifact should remain understandable by a single engineer during a normal working session.
When understanding an artifact requires reading many unrelated parts of the project, the design should be reconsidered.
Complexity shall never be removed by hiding it elsewhere.
Complexity shall instead be isolated inside the component responsible for it.
EP-001.a — One Sheet, One Story
Each schematic sheet shall describe one subsystem.
Examples:
- ESP32 System Controller
- Power Management
- DSP Engine
- Radio Engine
- Bluetooth Engine
- USB Interface
A schematic shall never mix unrelated functions simply to reduce the number of pages.
Readability is always preferred over compactness.
EP-001.b — One Document, One Topic
Each document shall describe one subject.
If a document becomes too large, it should be divided into multiple documents.
Documentation shall remain easy to navigate.
EP-001.c — One Module, One Responsibility
Each firmware module shall implement one responsibility only.
Modules communicate through interfaces.
Implementation details remain internal.
EP-001.d — One PCB Area, One Function
PCB placement should reflect the logical architecture.
Subsystems should remain visually identifiable.
Power, DSP, Radio, Bluetooth and Controller sections should remain clearly separated whenever practical.
5. Engineering Principles
EP-002 — Single Responsibility
Every hardware and software component shall have one clearly defined responsibility.
Responsibilities shall never overlap.
EP-003 — Architecture Before Implementation
The design process always follows this order:
Architecture
↓
Documentation
↓
Implementation
↓
Verification
Implementation shall never drive architecture.
EP-004 — Hardware Independence
Firmware shall communicate with logical devices.
Hardware details shall remain confined inside the Hardware Abstraction Layer whenever practical.
EP-005 — Modular Hardware
Each subsystem should, whenever technically possible, provide:
- Independent power control
- Independent reset
- Diagnostic capability
- Firmware update capability
EP-006 — Digital First
Audio shall remain digital until analog conversion is explicitly required.
EP-007 — Observable System
Every subsystem shall expose sufficient diagnostic information.
A system that cannot be observed cannot be maintained efficiently.
EP-008 — Serviceability
Maintenance shall be considered from the beginning of the project.
Firmware update, diagnostics and hardware verification are part of the system architecture.
They are not optional features.
EP-009 — Documentation is Part of the Product
Documentation is part of the engineering deliverable.
Every important design decision shall be documented.
Outdated documentation shall be considered a defect.
EP-010 — Continuous Improvement
Engineering decisions are based on evidence.
Whenever a better solution becomes available, it shall be evaluated using objective engineering criteria.
Previous decisions are never protected by pride.
6. Engineering Rules
The following practical rules derive directly from these principles.
- Small classes
- Small functions
- Explicit interfaces
- No hidden side effects
- Clear ownership
- Minimal coupling
- Meaningful names
- Predictable behaviour
7. Definition of Done
A development activity is complete only when:
✓ Implementation completed
✓ Documentation updated
✓ Review completed
✓ Tests completed
✓ Future maintenance considered
8. Scope
These principles apply to every future revision of HubAudio unless explicitly superseded by a newer approved version.
9. References
-
ADR-000 — Engineering Principles
-
Mark Seemann Code That Fits in Your Head
-
Robert C. Martin Clean Architecture
-
John Ousterhout A Philosophy of Software Design