Skip to content

Architecture Decision Records (ADR)

This directory contains all Architecture Decision Records for the EMDR Bilateral Stimulation Device project.

Format: MADR 4.0.0 (Markdown Architectural Decision Records) Migration Date: 2025-11-21 Status: ✅ Migrated from monolithic docs/architecture_decisions.md

Quick Navigation

ID Title Status Phase Date
AD001 ESP-IDF v5.5.0 Framework Selection ✅ Accepted Phase 1a 2025-10-28
AD002 JPL Power of Ten Rules Adoption ✅ Accepted Phase 1a 2025-10-28
AD003 C Language Selection (C17 Standard) ✅ Accepted Phase 1a 2025-10-28
AD004 Seeed XIAO ESP32C6 Platform Selection ✅ Accepted Phase 1a 2025-10-28
AD005 GPIO Assignment Strategy ✅ Accepted Phase 1a 2025-10-28
AD006 Bilateral Cycle Time Architecture ✅ Accepted Phase 1a 2025-10-28
AD007 FreeRTOS Task Architecture ✅ Accepted Phase 1a 2025-10-28
AD008 BLE Protocol Architecture 🔄 Superseded Phase 1b 2025-10-29
AD009 Bilateral Timing Implementation ✅ Accepted Phase 1a 2025-10-29
AD010 Race Condition Prevention Strategy ✅ Accepted Phase 1b 2025-10-29
AD011 Emergency Shutdown Protocol ✅ Accepted Phase 1a 2025-10-29
AD012 Dead Time Implementation Strategy ✅ Accepted Phase 1a 2025-10-29
AD013 Factory Reset Security Window ✅ Accepted Phase 1a 2025-10-30
AD014 Deep Sleep Strategy ✅ Accepted Phase 3 2025-10-30
AD015 NVS Storage Strategy ✅ Accepted Phase 1a 2025-10-30
AD016 No Session State Persistence ✅ Accepted Phase 1a 2025-10-30
AD017 Conditional Compilation Strategy ✅ Accepted Phase 1a 2025-10-30
AD018 Technical Risk Mitigation ✅ Accepted Phase 4 2025-10-31
AD019 Task Watchdog Timer Adaptive Feeding ✅ Accepted Phase 4 2025-10-31
AD020 Power Management Strategy (Phased) ✅ Accepted Phase 3 2025-11-01
AD021 Motor Stall Detection (Back-EMF) ✅ Accepted Phase 3 2025-11-04
AD022 ESP-IDF Build System and Test Architecture ✅ Accepted Phase 1a 2025-11-05
AD023 Deep Sleep Wake State Machine ✅ Accepted Phase 3 2025-11-06
AD024 LED Strip Component Version Lock ✅ Accepted Phase 4 2025-11-07
AD025 Dual-Device Wake Pattern UX ✅ Accepted Phase 3 2025-11-08
AD026 BLE Automatic Role Recovery 🔄 Superseded Phase 1b 2025-11-09
AD027 Modular Source File Architecture ✅ Accepted Phase 1b 2025-11-10
AD028 Command-and-Control Architecture with Synchronized Fallback ✅ Accepted Phase 2 2025-11-11
AD029 Relaxed Timing Specification (±100ms) ✅ Accepted Phase 2 2025-11-11
AD030 BLE Bilateral Control Service ✅ Accepted Phase 1b 2025-11-12
AD031 Research Platform Extensions ✅ Accepted Phase 4+ 2025-11-12
AD032 BLE Configuration Service Architecture ✅ Accepted Phase 1b 2025-11-12
AD033 LED Color Palette Standard ⏳ Approved Phase 1b 2025-11-13
AD034 Documentation Versioning and Release Management ⏳ Approved Phase 1b 2025-11-13
AD035 Battery-Based Initial Role Assignment (Phase 1c) ✅ Implemented Phase 1c 2025-11-14
AD036 BLE Bonding and Pairing Security (Phase 1b.3) ⏳ Approved Phase 1b.3 2025-11-15
AD037 State-Based BLE Connection Type Identification 🔄 Superseded Phase 1b.3 2025-11-18
AD038 UUID-Switching Strategy for Connection Type Identification ✅ Implemented Phase 1b.3 2025-11-18
AD039 Time Synchronization Protocol 🔄 Superseded Phase 2 2025-11-19
AD040 Firmware Version Checking for Peer Devices ⏳ Approved Phase 2 2025-11-19
AD041 Predictive Bilateral Synchronization Protocol 🔄 Superseded Phase 6v 2025-12-12
AD042 Remove MAC-Based Scan Delay (Battery-Based Symmetry Breaking) ✅ Implemented Phase 6q 2025-11-29
AD043 Filtered Time Synchronization Protocol ✅ Approved Phase 6r 2025-12-02
AD044 CLIENT Hardware Timer Synchronization ✅ Accepted Phase 6 2025-12-03
AD045 Synchronized Independent Bilateral Operation ⏳ Proposed Phase 6u 2025-12-08
AD046 PTP Observation Mode Integration ⏳ Proposed Phase 6v 2025-12-12
AD047 Scheduled Pattern Playback Architecture ✅ Implemented Phase 7 2025-12-13
AD048 ESP-NOW Adaptive Transport and Hardware Acceleration 🔬 Research Phase 7+ 2025-12-17
AD049 CSI Phase-Based Motion Detection Exploration 🔬 Exploratory Phase 8+ 2025-12-23
AD050 UTLP Module Extraction ⏳ Proposed Phase 8 2025-12-24

Phase 0.1: Foundation (Framework & Standards)

  • Development platform selection
  • Coding standards
  • Build system

Phase 0.4: JPL Compliance (Single-Device)

  • Message queue architecture
  • Error handling patterns
  • Watchdog management

Phase 1: Dual-Device Foundation

  • Peer discovery
  • Connection management
  • Battery monitoring

Phase 1b: BLE Bonding & Pairing

  • Pairing security
  • NVS storage
  • Connection identification

Phase 1b.3: UUID Switching

  • Peer vs app identification
  • Time-based advertising

Phase 1c: Role Assignment

  • Battery-based roles
  • SERVER/CLIENT assignment

Phase 2: Time Synchronization (Complete)

  • NTP-style beacon exchange
  • Clock drift compensation
  • Quality metrics

Phase 6: Bilateral Motor Coordination (Complete)

  • PTP-inspired pattern broadcast architecture
  • EMA filter with dual-alpha design
  • Motor epoch for independent operation
  • ±30 μs precision over 90 minutes

Phase 6k: Predictive Bilateral Synchronization

  • Drift-rate prediction
  • Motor epoch broadcasting
  • CLIENT antiphase calculation
  • Validates AD028 Option A with drift compensation

Phase 6q: Discovery Race Condition Fix

  • Remove MAC-based scan delay
  • Fix error 523 handler bug
  • Battery-based symmetry breaking
  • Eliminates advertising-only race window

Phase 6r: Filtered Time Synchronization

  • One-way SERVER timestamps (replaces 4-way RTT)
  • Exponential moving average filter
  • Eliminates RTT spike sensitivity
  • ±15ms accuracy improvement

Phase 6u: Synchronized Independent Operation

  • Both devices calculate from synced clocks
  • Eliminates correction death spiral
  • Passive monitoring for edge cases
  • ±6 μs precision over 20 minutes

Phase 7: Scheduled Pattern Playback (P7.0-P7.2 Complete - AD047)

  • ✅ P7.0 Pattern Engine Foundation
  • ✅ P7.1 Scheduled Pattern Playback (catalog, interpolation, "Lightbar Mode")
  • ✅ P7.2 Pattern Catalog Export (pattern_generate_json())
  • ⏳ P7.3 PWA Pattern Designer
  • 📋 P7.4 Legacy Mode Migration

Phase 7+: ESP-NOW and Hardware Acceleration (Research - AD048)

  • ESP-NOW as adaptive BLE fallback for extended range
  • 802.11mc FTM coexistence for ranging
  • AES/SHA/ECC hardware accelerator utilization
  • Transport abstraction layer design

Phase 8: Architecture Refinement

  • AD049: CSI Phase-Based Motion Detection (Exploratory)
  • AD050: UTLP Module Extraction (Proposed)
  • Clean separation: Time = unencrypted (public), Application = encrypted
  • Transport-agnostic API for portability
  • Reference implementation for prior art documentation

✅ Accepted

Decisions that have been implemented and are in active use.

🔄 Superseded

Decisions that have been replaced by newer decisions.

Supersession Chain: - AD008 (BLE Protocol Architecture) → 🔄 Superseded in Phase 1b (replaced by AD030, AD032) - AD010 (Race Condition Prevention - MAC Delay) → 🔄 Partially Superseded by AD042 (MAC delay component removed; error 523 handling retained) - AD026 (BLE Automatic Role Recovery) → 🔄 Superseded by AD028 (Command-and-Control Architecture) - AD028 (Command-and-Control - Motor Control) → 🔄 Partially Superseded by AD041 (Predictive Sync for motor control, command-and-control retained for emergency features) - AD037 (State-Based Connection ID) → 🔄 Superseded by AD038 (UUID-Switching Strategy) - AD039 (Time Synchronization Protocol) → 🔄 Superseded by AD043 (Filtered Time Sync replaces 4-way RTT with one-way timestamps + EMA filter)

⏳ Approved

Decisions that have been accepted but not yet fully implemented.

🔬 Research

Decisions under active investigation/research before implementation planning.

❌ Deprecated

Decisions that are no longer valid or relevant.

Architecture

Core system design decisions affecting multiple components.

Build System

Compilation, linking, and environment configuration decisions.

Security

Authentication, authorization, encryption, and pairing decisions.

Testing

Test strategy, verification methods, and validation approaches.

Documentation

Documentation format, structure, and maintenance decisions.

How to Create a New ADR

  1. Copy the template: 

    cp docs/adr/_template.md docs/adr/NNNN-your-decision-title.md

  2. Fill in all sections:

  3. Date, Phase, Status, Type
  4. Summary (Y-Statement)
  5. Problem Statement, Context, Decision
  6. Consequences (Benefits & Drawbacks)
  7. Options Considered (with pros/cons)
  8. Related Decisions

  9. Implementation Notes

  10. Update this index:

  11. Add row to Quick Navigation table
  12. Add to appropriate Phase section
  13. Add to Status section

  14. Add to Type section

  15. Reference in code: 

    // Per AD040, we check firmware version compatibility
// See docs/adr/0040-firmware-version-checking.md

  16. Commit with clear message: 

    git add docs/adr/NNNN-*.md docs/adr/README.md
git commit -m "[ADR] Add ADNNN: Title"

ADR Migration Notes

Original Location: docs/architecture_decisions.md (4,354 lines, 186 KB) Reason for Migration: Exceeded Claude Code read tool token limit (25,000 tokens) Migration Date: 2025-11-21 Commit Hash: [to be added]

Benefits of File-Per-AD Structure: - ✅ Individual ADs readable by AI tools (500-1000 tokens each) - ✅ Fast grep/search for specific decisions - ✅ Automated cross-reference validation - ✅ Clear template for future decisions - ✅ Parallel development (no merge conflicts) - ✅ Granular git history per decision

Backward Compatibility: - Original file archived at docs/archive/architecture_decisions.md - "AD0XX" reference format works with both old and new structure - Links in code/docs can gradually migrate to new location

Cross-Reference Graph

(To be populated with decision dependency visualization)

Statistics

  • Total Decisions: 50
  • Accepted: 31 (AD001-007, AD009-013, AD015-024, AD027-032, AD044)
  • Implemented: 5 (AD035, AD038, AD041, AD042, AD047)
  • Approved: 5 (AD033, AD034, AD036, AD040, AD043)
  • Proposed: 3 (AD045, AD046, AD050)
  • Research/Exploratory: 2 (AD048, AD049)
  • Superseded: 4 (AD008, AD026, AD037, AD039)
  • Partially Superseded: 2 (AD010 - MAC delay only, AD028 - motor control only)
  • Deprecated: 0

Maintenance

Last Updated: 2025-12-24 Maintained By: Project team + Claude Code AI Review Frequency: Quarterly or when adding new decisions Template Version: MADR 4.0.0 (Customized for EMDR Pulser)

Questions about ADRs? - See docs/adr/_template.md for structure - Review existing ADs for examples - Reference MADR 4.0.0 standard: https://adr.github.io/madr/