# kassemazanki/mpx-stl architecture

> Architecture diagram of the GitHub repository kassemazanki/mpx-stl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kassemazanki/mpx-stl
- Repository: https://github.com/kassemazanki/mpx-stl

## Overview

MPX STL is ESP32-S3 firmware that turns an internet radio stream into stereo FM composite audio with RDS, while exposing live controls through a browser portal. The main runtime path decodes the stream, processes audio, synthesizes MPX/RDS, and outputs it over I2S to a DAC. Separate branches handle WiFi setup, persisted configuration, browser diagnostics, and optional OLED status. The README documents capabilities beyond the sampled excerpts; those are represented where the tree supports a module, without asserting unverified internal wiring.

Main entry points: [`mpx_encoder.h`](https://github.com/kassemazanki/mpx-stl/blob/main/mpx_encoder.h) (Audio Chain), [`web_portal.h`](https://github.com/kassemazanki/mpx-stl/blob/main/web_portal.h) (Web Portal), [`mpx_esp32.ino`](https://github.com/kassemazanki/mpx-stl/blob/main/mpx_esp32.ino) (Firmware Tasks), [`audio_manager.h`](https://github.com/kassemazanki/mpx-stl/blob/main/audio_manager.h) (Stream Decoder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Audio Runtime"]
  node_firmware["Firmware Tasks<br/>[mpx_esp32.ino]"]
  node_stream_decoder["Stream Decoder<br/>[audio_manager.h]"]
  node_mpx["MPX Synthesizer<br/>[mpx_encoder.h]"]
  node_rds["RDS Encoder<br/>[rds_encoder.h]"]
  node_dac["I2S DAC Output<br/>[mpx_encoder.h]"]
end

subgraph group_processing["Audio Processing"]
  node_audio_chain["Audio Chain<br/>[mpx_encoder.h]"]
  node_filters["Audio Filters<br/>[audio_filters.h]"]
  node_equalizer["10-Band EQ<br/>[audio_eq10.h]"]
  node_agc["AGC<br/>[audio_agc.h]"]
  node_limiter["Lookahead Limiter<br/>[audio_limiter.h]"]
  node_clipper["Audio Clipper<br/>[audio_clipper.h]"]
  node_preemphasis["Pre-emphasis<br/>[preemphasis.h]"]
  node_stereo_booster["Stereo Booster"]
end

subgraph group_control["Web Control"]
  node_portal["Web Portal<br/>[web_portal.h]"]
  node_settings[("Settings Store<br/>[settings_store.h]")]
end

subgraph group_connectivity["Connectivity"]
  node_wifi["WiFi Manager<br/>[wifi_manager.h]"]
end

subgraph group_status["Local Status"]
  node_oled["OLED Display<br/>[oled_display.h]"]
end

node_listener(("Radio Stream"))
node_exciter(("FM Exciter"))
node_operator(("Operator"))

node_listener -->|"streams audio"| node_stream_decoder
node_firmware -->|"runs decode"| node_stream_decoder
node_stream_decoder -->|"pushes samples"| node_audio_chain
node_audio_chain -->|"filters audio"| node_filters
node_audio_chain -->|"equalizes"| node_equalizer
node_audio_chain -->|"levels audio"| node_agc
node_audio_chain -->|"limits peaks"| node_limiter
node_audio_chain -->|"clips peaks"| node_clipper
node_audio_chain -->|"emphasizes audio"| node_preemphasis
node_audio_chain -->|"widens stereo"| node_stereo_booster
node_firmware -->|"runs synthesis"| node_mpx
node_mpx -->|"reads RDS data"| node_rds
node_mpx -->|"writes I2S"| node_dac
node_dac -->|"outputs composite"| node_exciter
node_operator -->|"controls"| node_portal
node_portal -->|"sets stream"| node_stream_decoder
node_portal -->|"sets processing"| node_audio_chain
node_portal -->|"sets RDS"| node_rds
node_portal -->|"loads and saves"| node_settings
node_firmware -->|"restores settings"| node_settings
node_portal -->|"configures network"| node_wifi
node_firmware -->|"manages connection"| node_wifi
node_firmware -.->|"updates status"| node_oled
node_oled -->|"reads status"| node_wifi
node_oled -->|"reads stream status"| node_stream_decoder
node_oled -->|"reads MPX level"| node_mpx

click node_firmware "https://github.com/kassemazanki/mpx-stl/blob/main/mpx_esp32.ino"
click node_stream_decoder "https://github.com/kassemazanki/mpx-stl/blob/main/audio_manager.h"
click node_audio_chain "https://github.com/kassemazanki/mpx-stl/blob/main/mpx_encoder.h"
click node_filters "https://github.com/kassemazanki/mpx-stl/blob/main/audio_filters.h"
click node_equalizer "https://github.com/kassemazanki/mpx-stl/blob/main/audio_eq10.h"
click node_agc "https://github.com/kassemazanki/mpx-stl/blob/main/audio_agc.h"
click node_limiter "https://github.com/kassemazanki/mpx-stl/blob/main/audio_limiter.h"
click node_clipper "https://github.com/kassemazanki/mpx-stl/blob/main/audio_clipper.h"
click node_preemphasis "https://github.com/kassemazanki/mpx-stl/blob/main/preemphasis.h"
click node_stereo_booster "https://github.com/kassemazanki/mpx-stl/blob/main/audio_stereo_booster.h"
click node_mpx "https://github.com/kassemazanki/mpx-stl/blob/main/mpx_encoder.h"
click node_rds "https://github.com/kassemazanki/mpx-stl/blob/main/rds_encoder.h"
click node_dac "https://github.com/kassemazanki/mpx-stl/blob/main/mpx_encoder.h"
click node_portal "https://github.com/kassemazanki/mpx-stl/blob/main/web_portal.h"
click node_settings "https://github.com/kassemazanki/mpx-stl/blob/main/settings_store.h"
click node_wifi "https://github.com/kassemazanki/mpx-stl/blob/main/wifi_manager.h"
click node_oled "https://github.com/kassemazanki/mpx-stl/blob/main/oled_display.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_firmware,node_stream_decoder,node_mpx,node_rds,node_dac toneBlue
class node_audio_chain,node_filters,node_equalizer,node_agc,node_limiter,node_clipper,node_preemphasis,node_stereo_booster toneAmber
class node_portal,node_settings toneMint
class node_wifi toneRose
class node_oled,node_listener,node_exciter,node_operator toneIndigo
```

## Components

### Audio Runtime

- [Firmware Tasks](https://github.com/kassemazanki/mpx-stl/blob/main/mpx_esp32.ino): `mpx_esp32.ino`
- [Stream Decoder](https://github.com/kassemazanki/mpx-stl/blob/main/audio_manager.h): `audio_manager.h`
- [MPX Synthesizer](https://github.com/kassemazanki/mpx-stl/blob/main/mpx_encoder.h): `mpx_encoder.h`
- [RDS Encoder](https://github.com/kassemazanki/mpx-stl/blob/main/rds_encoder.h): `rds_encoder.h`
- [I2S DAC Output](https://github.com/kassemazanki/mpx-stl/blob/main/mpx_encoder.h): `mpx_encoder.h`

### Audio Processing

- [Audio Chain](https://github.com/kassemazanki/mpx-stl/blob/main/mpx_encoder.h): `mpx_encoder.h`
- [Audio Filters](https://github.com/kassemazanki/mpx-stl/blob/main/audio_filters.h): `audio_filters.h`
- [10-Band EQ](https://github.com/kassemazanki/mpx-stl/blob/main/audio_eq10.h): `audio_eq10.h`
- [AGC](https://github.com/kassemazanki/mpx-stl/blob/main/audio_agc.h): `audio_agc.h`
- [Lookahead Limiter](https://github.com/kassemazanki/mpx-stl/blob/main/audio_limiter.h): `audio_limiter.h`
- [Audio Clipper](https://github.com/kassemazanki/mpx-stl/blob/main/audio_clipper.h): `audio_clipper.h`
- [Pre-emphasis](https://github.com/kassemazanki/mpx-stl/blob/main/preemphasis.h): `preemphasis.h`
- [Stereo Booster](https://github.com/kassemazanki/mpx-stl/blob/main/audio_stereo_booster.h): `audio_stereo_booster.h`

### Web Control

- [Web Portal](https://github.com/kassemazanki/mpx-stl/blob/main/web_portal.h): `web_portal.h`
- [Settings Store](https://github.com/kassemazanki/mpx-stl/blob/main/settings_store.h): `settings_store.h`

### Connectivity

- [WiFi Manager](https://github.com/kassemazanki/mpx-stl/blob/main/wifi_manager.h): `wifi_manager.h`

### Local Status

- [OLED Display](https://github.com/kassemazanki/mpx-stl/blob/main/oled_display.h): `oled_display.h`

### Other components

- **Radio Stream**
- **FM Exciter**
- **Operator**

## Connections

- Radio Stream → Stream Decoder: streams audio
- Firmware Tasks → Stream Decoder: runs decode
- Stream Decoder → Audio Chain: pushes samples
- Audio Chain → Audio Filters: filters audio
- Audio Chain → 10-Band EQ: equalizes
- Audio Chain → AGC: levels audio
- Audio Chain → Lookahead Limiter: limits peaks
- Audio Chain → Audio Clipper: clips peaks
- Audio Chain → Pre-emphasis: emphasizes audio
- Audio Chain → Stereo Booster: widens stereo
- Firmware Tasks → MPX Synthesizer: runs synthesis
- MPX Synthesizer → RDS Encoder: reads RDS data
- MPX Synthesizer → I2S DAC Output: writes I2S
- I2S DAC Output → FM Exciter: outputs composite
- Operator → Web Portal: controls
- Web Portal → Stream Decoder: sets stream
- Web Portal → Audio Chain: sets processing
- Web Portal → RDS Encoder: sets RDS
- Web Portal → Settings Store: loads and saves
- Firmware Tasks → Settings Store: restores settings
- Web Portal → WiFi Manager: configures network
- Firmware Tasks → WiFi Manager: manages connection
- Firmware Tasks → OLED Display: updates status
- OLED Display → WiFi Manager: reads status
- OLED Display → Stream Decoder: reads stream status
- OLED Display → MPX Synthesizer: reads MPX level