# nakulbhat/hexdtmf architecture

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

- Interactive diagram: https://gitdiagram.com/nakulbhat/hexdtmf
- Repository: https://github.com/nakulbhat/hexdtmf

## Overview

#### Purpose and executable entry point
`hexdtmf` is a POSIX C command-line program that converts hexadecimal-style keypad digits to/from WAV-encoded DTMF audio. The process begins in `src/main.c`, with shared program declarations in `include/main.h`. `Makefile` builds the `hexdtmf` executable using GCC.

#### CLI parsing and mode selection
Argument parsing determines the top-level `encode` or `decode` operation plus input/output, timing, compatibility, verbosity, and help options. This is isolated in:
- `src/args.c`
- `include/args.h`
- `src/main.c`

The parsed options form the boundary between command-line/user I/O concerns and audio processing.

#### Encode pipeline
Encode mode accepts digits from positional arguments, a file, or standard input, then produces a WAV file or writes WAV bytes to its selected output. The encoder is responsible for mapping supported values (`0`–`9`, `A`–`D`, plus `E/F` or compatibility `*/#`) to DTMF row/column frequency pairs, generating timed tone and gap samples, and serializing WAV output.
- `src/encoder.c`
- `include/encoder.h`
- `src/main.c`

Tone and gap durations supplied through CLI options directly control generated sample timing.

#### Decode pipeline
Decode mode consumes a WAV stream/file, identifies DTMF tone segments, resolves their two component frequencies to keypad digits, and emits text to stdout or an output file. WAV parsing and signal/digit recovery are encapsulated behind:
- `src/decoder.c`
- `include/decoder.h`
- `src/main.c`

This component owns the audio-input boundary and must tolerate binary WAV data arriving via stdin as well as files.

#### Digit representation and compatibility boundary
The application uses an extended hexadecimal-oriented representation: `E` represents `*` and `F` represents `#` by default. The compatibility option changes external representation to literal `*` and `#`. That translation applies at the CLI-facing encode/decode boundary rather than changing the underlying DTMF frequency model.
- `src/args.c`
- `src/encoder.c`
- `src/decoder.c`

#### User feedback and failures
Usage/help rendering is separated from core processing in:
- `src/help.c`
- `include/help.h`

`src/main.c` coordinates help/version-style control paths, validates operation selection, calls the appropriate codec path, and returns process status. Verbose mode is a diagnostic/control-flow concern exposed through parsed arguments.

#### Runtime and external dependencies
The program targets Linux/macOS-style POSIX environments and relies on the C runtime, standard streams/files, GCC, and Make. It has no indicated network service, database, web runtime, or third-party runtime dependency. WAV files and stdin/stdout are its primary integration interfaces.

Main entry points: [`src/main.c`](https://github.com/nakulbhat/hexdtmf/blob/main/src/main.c) (Program coordinator), [`src/encoder.c`](https://github.com/nakulbhat/hexdtmf/blob/main/src/encoder.c) (DTMF encoder), [`src/decoder.c`](https://github.com/nakulbhat/hexdtmf/blob/main/src/decoder.c) (DTMF decoder), [`src/args.c`](https://github.com/nakulbhat/hexdtmf/blob/main/src/args.c) (Argument parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI & Control"]
  node_main["Program coordinator<br/>C entry point<br/>[main.c]"]
  node_main_header["Shared declarations<br/>C header<br/>[main.h]"]
  node_args["Argument parser<br/>CLI parser<br/>[args.c]"]
  node_args_header["Argument API<br/>C header<br/>[args.h]"]
  node_help["Help renderer<br/>usage output<br/>[help.c]"]
  node_help_header["Help API<br/>C header<br/>[help.h]"]
end

subgraph group_codec["DTMF Codecs"]
  node_encoder["DTMF encoder<br/>WAV encoder<br/>[encoder.c]"]
  node_encoder_header["Encoder API<br/>C header<br/>[encoder.h]"]
  node_decoder["DTMF decoder<br/>WAV decoder<br/>[decoder.c]"]
  node_decoder_header["Decoder API<br/>C header<br/>[decoder.h]"]
end

node_make{{"Make build<br/>build system"}}
node_user_input["CLI digits / text input<br/>input interface"]
node_wav_input["WAV input<br/>audio interface"]
node_wav_output["WAV output<br/>audio interface"]
node_text_output["Decoded text output<br/>output interface"]
node_posix_runtime(("POSIX C runtime"))

node_make -->|"builds"| node_main
node_main -->|"parses options"| node_args
node_args -.->|"declares"| node_args_header
node_main -.->|"uses"| node_main_header
node_main -->|"renders help"| node_help
node_help -.->|"declares"| node_help_header
node_main -->|"encode mode"| node_encoder
node_main -->|"decode mode"| node_decoder
node_encoder -.->|"declares"| node_encoder_header
node_decoder -.->|"declares"| node_decoder_header
node_user_input -->|"digits or text"| node_encoder
node_encoder -->|"serializes WAV"| node_wav_output
node_wav_input -->|"WAV stream"| node_decoder
node_decoder -->|"emits digits"| node_text_output
node_args -->|"timing and compatibility"| node_encoder
node_args -->|"compatibility and verbosity"| node_decoder
node_posix_runtime -->|"executes"| node_main

click node_make "https://github.com/nakulbhat/hexdtmf/blob/main/Makefile"
click node_main "https://github.com/nakulbhat/hexdtmf/blob/main/src/main.c"
click node_main_header "https://github.com/nakulbhat/hexdtmf/blob/main/include/main.h"
click node_args "https://github.com/nakulbhat/hexdtmf/blob/main/src/args.c"
click node_args_header "https://github.com/nakulbhat/hexdtmf/blob/main/include/args.h"
click node_help "https://github.com/nakulbhat/hexdtmf/blob/main/src/help.c"
click node_help_header "https://github.com/nakulbhat/hexdtmf/blob/main/include/help.h"
click node_encoder "https://github.com/nakulbhat/hexdtmf/blob/main/src/encoder.c"
click node_encoder_header "https://github.com/nakulbhat/hexdtmf/blob/main/include/encoder.h"
click node_decoder "https://github.com/nakulbhat/hexdtmf/blob/main/src/decoder.c"
click node_decoder_header "https://github.com/nakulbhat/hexdtmf/blob/main/include/decoder.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_main,node_main_header,node_args,node_args_header,node_help,node_help_header toneBlue
class node_encoder,node_encoder_header,node_decoder,node_decoder_header toneAmber
class node_make,node_user_input,node_wav_input,node_wav_output,node_text_output,node_posix_runtime toneNeutral
```

## Components

### CLI & Control

- [Program coordinator](https://github.com/nakulbhat/hexdtmf/blob/main/src/main.c): C entry point · Selects control paths and returns process status. · `src/main.c`
- [Shared declarations](https://github.com/nakulbhat/hexdtmf/blob/main/include/main.h): C header · `include/main.h`
- [Argument parser](https://github.com/nakulbhat/hexdtmf/blob/main/src/args.c): CLI parser · Produces operation, I/O, timing, compatibility, and verbosity options. · `src/args.c`
- [Argument API](https://github.com/nakulbhat/hexdtmf/blob/main/include/args.h): C header · `include/args.h`
- [Help renderer](https://github.com/nakulbhat/hexdtmf/blob/main/src/help.c): usage output · `src/help.c`
- [Help API](https://github.com/nakulbhat/hexdtmf/blob/main/include/help.h): C header · `include/help.h`

### DTMF Codecs

- [DTMF encoder](https://github.com/nakulbhat/hexdtmf/blob/main/src/encoder.c): WAV encoder · Maps digits to frequency pairs and generates timed tone/gap samples. · `src/encoder.c`
- [Encoder API](https://github.com/nakulbhat/hexdtmf/blob/main/include/encoder.h): C header · `include/encoder.h`
- [DTMF decoder](https://github.com/nakulbhat/hexdtmf/blob/main/src/decoder.c): WAV decoder · Parses WAV input, detects tone segments, and recovers digits. · `src/decoder.c`
- [Decoder API](https://github.com/nakulbhat/hexdtmf/blob/main/include/decoder.h): C header · `include/decoder.h`

### Other components

- [Make build](https://github.com/nakulbhat/hexdtmf/blob/main/Makefile): build system · Builds the hexdtmf executable with GCC. · `Makefile`
- **CLI digits / text input**: input interface · Positional digits, file content, or stdin for encode mode.
- **WAV input**: audio interface · File or binary stdin consumed in decode mode.
- **WAV output**: audio interface · File or stdout WAV bytes produced in encode mode.
- **Decoded text output**: output interface · Stdout or selected output file.
- **POSIX C runtime**: runtime · Standard streams/files provide the integration boundary.

## Connections

- Make build → Program coordinator: builds
- Program coordinator → Argument parser: parses options
- Argument parser → Argument API: declares
- Program coordinator → Shared declarations: uses
- Program coordinator → Help renderer: renders help
- Help renderer → Help API: declares
- Program coordinator → DTMF encoder: encode mode
- Program coordinator → DTMF decoder: decode mode
- DTMF encoder → Encoder API: declares
- DTMF decoder → Decoder API: declares
- CLI digits / text input → DTMF encoder: digits or text
- DTMF encoder → WAV output: serializes WAV
- WAV input → DTMF decoder: WAV stream
- DTMF decoder → Decoded text output: emits digits
- Argument parser → DTMF encoder: timing and compatibility
- Argument parser → DTMF decoder: compatibility and verbosity
- POSIX C runtime → Program coordinator: executes