# rkycodes/anima architecture

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

- Interactive diagram: https://gitdiagram.com/rkycodes/anima
- Repository: https://github.com/rkycodes/anima

## Overview

ANIMA is an FPGA-oriented stereo I2S audio processor, currently implemented as a bypass path with diagnostics and control/clock-supervision logic; its DSP, wireless and display features remain planned. The principal documented audio workflow is receiver → coherent stereo-frame handoff → transmitter. The graph also preserves the current control/diagnostic modules and the Python preset/frame behavioral model. RTL integration details are not shown in the excerpts, so those internal connections are intentionally not inferred.

Main entry points: [`sim/fpga_control_logic/preset_manager.py`](https://github.com/rkycodes/anima/blob/main/sim/fpga_control_logic/preset_manager.py) (Preset manager), [`rtl/audio/anima_i2s_receiver.v`](https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_i2s_receiver.v) (I2S receiver), [`rtl/audio/anima_rx_frame_queue.v`](https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_rx_frame_queue.v) (RX frame queue), [`rtl/audio/anima_frame_scheduler.v`](https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_frame_scheduler.v) (Frame scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_audio["Audio RTL"]
  node_receiver["I2S receiver"]
  node_rxqueue["RX frame queue"]
  node_scheduler["Frame scheduler"]
  node_bypass["Bypass core"]
  node_transmitter["I2S transmitter"]
  node_timing["Serial timing"]
  node_warmreset["Warm reset"]
  node_watchdogs["Audio watchdogs"]
  node_diagnostics["Audio diagnostics"]
end

subgraph group_supervision["Control and supervision"]
  node_control["Control shell"]
  node_clocks["Clock supervisor"]
  node_button["Button events"]
  node_reset["Reset synchronizer<br/>[anima_reset_sync.v]"]
end

subgraph group_model["Preset/frame model"]
  node_preset["Preset lifecycle<br/>[preset.py]"]
  node_manager["Preset manager<br/>[preset_manager.py]"]
  node_frame["Audio frame model<br/>[audio_frame.py]"]
end

node_source(("Stereo source"))
node_adc["I2S ADC"]
node_dac["I2S DAC"]
node_speakers(("Powered speakers"))
node_wireless(("Wireless controls"))
node_esp32["ESP32"]
node_uart["FPGA UART/parser"]
node_dsp["Planned DSP"]
node_vga["Planned VGA meters"]

node_source -->|"audio to"| node_adc
node_adc -->|"audio to"| node_receiver
node_receiver -->|"frames to"| node_rxqueue
node_rxqueue -->|"coherent frames"| node_scheduler
node_scheduler -->|"frames to"| node_transmitter
node_transmitter -->|"audio to"| node_dac
node_dac -->|"audio to"| node_speakers
node_wireless -.->|"controls"| node_esp32
node_esp32 -.->|"controls"| node_uart
node_uart -.->|"planned controls"| node_dsp
node_manager -->|"uses"| node_preset
node_manager -->|"creates"| node_frame
node_frame -->|"holds snapshot"| node_preset

click node_receiver "https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_i2s_receiver.v"
click node_rxqueue "https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_rx_frame_queue.v"
click node_scheduler "https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_frame_scheduler.v"
click node_bypass "https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_bypass_core.v"
click node_transmitter "https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_i2s_transmitter.v"
click node_timing "https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_serial_timing.v"
click node_warmreset "https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_warm_reset_controller.v"
click node_watchdogs "https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_audio_watchdogs.v"
click node_diagnostics "https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_audio_diagnostics.v"
click node_control "https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_bypass_control_shell.v"
click node_clocks "https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_clock_supervisor.v"
click node_button "https://github.com/rkycodes/anima/blob/main/rtl/common/anima_button_event.v"
click node_reset "https://github.com/rkycodes/anima/blob/main/rtl/common/anima_reset_sync.v"
click node_preset "https://github.com/rkycodes/anima/blob/main/sim/fpga_control_logic/preset.py"
click node_manager "https://github.com/rkycodes/anima/blob/main/sim/fpga_control_logic/preset_manager.py"
click node_frame "https://github.com/rkycodes/anima/blob/main/sim/fpga_control_logic/audio_frame.py"

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_receiver,node_rxqueue,node_scheduler,node_bypass,node_transmitter,node_timing,node_warmreset,node_watchdogs,node_diagnostics toneBlue
class node_control,node_clocks,node_button,node_reset toneAmber
class node_preset,node_manager,node_frame toneMint
class node_source,node_adc,node_dac,node_speakers,node_wireless,node_esp32,node_uart,node_dsp,node_vga toneIndigo
```

## Components

### Audio RTL

- [I2S receiver](https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_i2s_receiver.v): `rtl/audio/anima_i2s_receiver.v`
- [RX frame queue](https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_rx_frame_queue.v): `rtl/audio/anima_rx_frame_queue.v`
- [Frame scheduler](https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_frame_scheduler.v): `rtl/audio/anima_frame_scheduler.v`
- [Bypass core](https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_bypass_core.v): `rtl/audio/anima_bypass_core.v`
- [I2S transmitter](https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_i2s_transmitter.v): `rtl/audio/anima_i2s_transmitter.v`
- [Serial timing](https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_serial_timing.v): `rtl/audio/anima_serial_timing.v`
- [Warm reset](https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_warm_reset_controller.v): `rtl/audio/anima_warm_reset_controller.v`
- [Audio watchdogs](https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_audio_watchdogs.v): `rtl/audio/anima_audio_watchdogs.v`
- [Audio diagnostics](https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_audio_diagnostics.v): `rtl/audio/anima_audio_diagnostics.v`

### Control and supervision

- [Control shell](https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_bypass_control_shell.v): `rtl/audio/anima_bypass_control_shell.v`
- [Clock supervisor](https://github.com/rkycodes/anima/blob/main/rtl/audio/anima_clock_supervisor.v): `rtl/audio/anima_clock_supervisor.v`
- [Button events](https://github.com/rkycodes/anima/blob/main/rtl/common/anima_button_event.v): `rtl/common/anima_button_event.v`
- [Reset synchronizer](https://github.com/rkycodes/anima/blob/main/rtl/common/anima_reset_sync.v): `rtl/common/anima_reset_sync.v`

### Preset/frame model

- [Preset lifecycle](https://github.com/rkycodes/anima/blob/main/sim/fpga_control_logic/preset.py): `sim/fpga_control_logic/preset.py`
- [Preset manager](https://github.com/rkycodes/anima/blob/main/sim/fpga_control_logic/preset_manager.py): `sim/fpga_control_logic/preset_manager.py`
- [Audio frame model](https://github.com/rkycodes/anima/blob/main/sim/fpga_control_logic/audio_frame.py): `sim/fpga_control_logic/audio_frame.py`

### Other components

- **Stereo source**
- **I2S ADC**
- **I2S DAC**
- **Powered speakers**
- **Wireless controls**
- **ESP32**
- **FPGA UART/parser**
- **Planned DSP**
- **Planned VGA meters**

## Connections

- Stereo source → I2S ADC: audio to (evidence: `README.md`)
- I2S ADC → I2S receiver: audio to (evidence: `README.md`)
- I2S receiver → RX frame queue: frames to (evidence: `README.md`)
- RX frame queue → Frame scheduler: coherent frames (evidence: `README.md`)
- Frame scheduler → I2S transmitter: frames to (evidence: `README.md`)
- I2S transmitter → I2S DAC: audio to (evidence: `README.md`)
- I2S DAC → Powered speakers: audio to (evidence: `README.md`)
- Wireless controls → ESP32: controls (evidence: `README.md`)
- ESP32 → FPGA UART/parser: controls (evidence: `README.md`)
- FPGA UART/parser → Planned DSP: planned controls (evidence: `README.md`)
- Preset manager → Preset lifecycle: uses (evidence: `sim/fpga_control_logic/preset_manager.py`)
- Preset manager → Audio frame model: creates (evidence: `sim/fpga_control_logic/preset_manager.py`)
- Audio frame model → Preset lifecycle: holds snapshot (evidence: `sim/fpga_control_logic/audio_frame.py`)