Firmware Architecture
=====================

Design Principles
-----------------

- **Separation of Concerns:** Each module focuses on a single responsibility—hardware, protocol, state, business logic, or UI.
- **Explicit APIs:** Modules communicate through clear interfaces.
- **Scalability:** Structure supports adding new features (web endpoints, hardware interfaces, state transitions) without creating spaghetti code.
- **Testability:** Isolated logic is testable without hardware.

Directory Layout
----------------

The Ma Bell Gateway firmware is organized into logical modules and directories:

.. code-block:: none

   main/
     app/          # Application logic, state machine, and event coordination
     hardware/     # Phone line, GPIO, tones, analog/digital hardware interface
     bluetooth/    # Bluetooth stack, Hands-Free Profile (HFP), and related protocols
     network/      # Wi-Fi management and web interface (REST API, device status)
     storage/      # Persistent storage of configuration and device settings
     platform/     # ESP32/RTOS-specific glue code and project entry point
     include/      # Public headers (optional, if using)
     CMakeLists.txt

Module Responsibilities
-----------------------

**app/**
  - Contains the application's core logic, including the state machine, event system, and all “business logic.”  
  - Coordinates between hardware, Bluetooth, network, and user interfaces.

**hardware/**
  - Manages all interaction with the physical hardware:  
    - Pin configuration (GPIO, PCM/I2S)
    - Analog phone line interfacing (off-hook/ring detect, pulse dial)
    - Generation of all telephony tones
  - Abstracts hardware details from application logic.

**bluetooth/**
  - Implements all Bluetooth functionality, including:  
    - Stack integration
    - Hands-Free Profile (HFP) protocol handling
    - Audio routing and call event management
  - Provides a clear API for application modules to initiate or respond to Bluetooth events.

**network/**
  - Responsible for network connectivity and device management:
    - Wi-Fi provisioning, status, and reconnection
    - Web server and REST API endpoints for status monitoring, configuration, and control

**storage/**
  - Provides persistent storage for configuration data (such as paired device info and user settings)  
  - Abstracts the ESP32’s NVS (non-volatile storage) details behind a simple interface

**platform/**
  - Contains project entry points and ESP32/RTOS glue:
    - Main firmware boot/init
    - Task registration and synchronization
    - Component registration (build system integration)

**include/**
  - Optionally holds public header files for modules that require global access  
  - Helps decouple modules and simplify dependency management

Development Guidelines
----------------------

- **New features** should be added in the most appropriate module or directory—never spread logic across unrelated areas.
- **APIs** between modules must be explicit and documented in header files.
- **Hardware and protocol details** should be abstracted away from core application logic.
- **All project documentation and this architecture page should be updated as you refactor and extend the codebase.**

By following this structure, the Ma Bell Gateway firmware will be maintainable, testable, and easy for new contributors to understand.