# dhogborg/go-pocsag architecture

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

- Interactive diagram: https://gitdiagram.com/dhogborg/go-pocsag
- Repository: https://github.com/dhogborg/go-pocsag

## Overview

go-pocsag is a command-line POCSAG pager-message decoder. Its workflow accepts WAV audio or raw sample bytes from standard input, scans for transmissions and converts samples to bits, then synchronizes and decodes protocol codewords into messages for terminal display and optional file output. The README also documents piping rtl_fm output and forcing BCD or alphanumeric decoding. The graph follows the sampled entry point and source; protocol details beyond those excerpts are represented only at the documented subsystem level.

Main entry points: [`main.go`](https://github.com/dhogborg/go-pocsag/blob/master/main.go) (CLI workflow), [`internal/pocsag/stream.go`](https://github.com/dhogborg/go-pocsag/blob/master/internal/pocsag/stream.go) (Transmission scanner), [`internal/pocsag/pocsag.go`](https://github.com/dhogborg/go-pocsag/blob/master/internal/pocsag/pocsag.go) (POCSAG parser), [`internal/utils/util.go`](https://github.com/dhogborg/go-pocsag/blob/master/internal/utils/util.go) (Bit utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Input and scanning"]
  node_cli["CLI workflow<br/>[main.go]"]
  node_wavread["WAV reader<br/>[file.go]"]
  node_wavformat["WAV parser<br/>[wav.go]"]
  node_scanner["Transmission scanner<br/>[stream.go]"]
end

subgraph group_decode["POCSAG decoding"]
  node_protocol["POCSAG parser<br/>[pocsag.go]"]
  node_sync["Batch synchronization<br/>[pocsag.go]"]
  node_batch["Batch decoding<br/>[pocsag.go]"]
  node_codeword["Codeword decoding<br/>[pocsag.go]"]
  node_correction["Parity correction<br/>[pocsag.go]"]
  node_assembly["Message assembly<br/>[pocsag.go]"]
  node_textdecode["BCD / alpha decoding<br/>[pocsag.go]"]
end

subgraph group_output["Message output"]
end

subgraph group_core["Shared primitives"]
  node_samplebits["Sample-to-bit conversion<br/>[util.go]"]
  node_bitutils["Bit utilities<br/>[util.go]"]
  node_bittype["Bit type<br/>[bit.go]"]
end

node_user(("Operator / input"))
node_rtl["rtl_fm"]
node_terminal["Terminal"]
node_filesystem["Output files"]

node_user -->|"provides input"| node_cli
node_rtl -.->|"streams samples"| node_cli
node_cli -->|"reads WAV"| node_wavread
node_wavread -->|"parses file"| node_wavformat
node_cli -->|"starts scan"| node_scanner
node_scanner -->|"converts samples"| node_samplebits
node_scanner -->|"sends bit batches"| node_cli
node_cli -->|"parses bits"| node_protocol
node_protocol -->|"finds batches"| node_sync
node_sync -->|"checks preamble"| node_bitutils
node_sync -->|"decodes batch"| node_batch
node_batch -->|"decodes words"| node_codeword
node_codeword -->|"corrects errors"| node_correction
node_codeword -->|"converts bits"| node_bitutils
node_protocol -->|"assembles messages"| node_assembly
node_assembly -->|"decodes payload"| node_textdecode
node_cli -->|"prints messages"| node_terminal
node_cli -->|"writes messages"| node_filesystem
node_samplebits -->|"creates bits"| node_bittype
node_bitutils -->|"converts bits"| node_bittype

click node_cli "https://github.com/dhogborg/go-pocsag/blob/master/main.go"
click node_wavread "https://github.com/dhogborg/go-pocsag/blob/master/internal/pocsag/file.go"
click node_wavformat "https://github.com/dhogborg/go-pocsag/blob/master/internal/wav/wav.go"
click node_scanner "https://github.com/dhogborg/go-pocsag/blob/master/internal/pocsag/stream.go"
click node_samplebits "https://github.com/dhogborg/go-pocsag/blob/master/internal/utils/util.go"
click node_protocol "https://github.com/dhogborg/go-pocsag/blob/master/internal/pocsag/pocsag.go"
click node_sync "https://github.com/dhogborg/go-pocsag/blob/master/internal/pocsag/pocsag.go"
click node_batch "https://github.com/dhogborg/go-pocsag/blob/master/internal/pocsag/pocsag.go"
click node_codeword "https://github.com/dhogborg/go-pocsag/blob/master/internal/pocsag/pocsag.go"
click node_correction "https://github.com/dhogborg/go-pocsag/blob/master/internal/pocsag/pocsag.go"
click node_assembly "https://github.com/dhogborg/go-pocsag/blob/master/internal/pocsag/pocsag.go"
click node_textdecode "https://github.com/dhogborg/go-pocsag/blob/master/internal/pocsag/pocsag.go"
click node_bitutils "https://github.com/dhogborg/go-pocsag/blob/master/internal/utils/util.go"
click node_bittype "https://github.com/dhogborg/go-pocsag/blob/master/internal/datatypes/bit.go"

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_cli,node_wavread,node_wavformat,node_scanner toneBlue
class node_protocol,node_sync,node_batch,node_codeword,node_correction,node_assembly,node_textdecode toneAmber
class node_samplebits,node_bitutils,node_bittype toneRose
class node_user,node_rtl,node_terminal,node_filesystem toneIndigo
```

## Components

### Input and scanning

- [CLI workflow](https://github.com/dhogborg/go-pocsag/blob/master/main.go): `main.go`
- [WAV reader](https://github.com/dhogborg/go-pocsag/blob/master/internal/pocsag/file.go): `internal/pocsag/file.go`
- [WAV parser](https://github.com/dhogborg/go-pocsag/blob/master/internal/wav/wav.go): `internal/wav/wav.go`
- [Transmission scanner](https://github.com/dhogborg/go-pocsag/blob/master/internal/pocsag/stream.go): `internal/pocsag/stream.go`

### POCSAG decoding

- [POCSAG parser](https://github.com/dhogborg/go-pocsag/blob/master/internal/pocsag/pocsag.go): `internal/pocsag/pocsag.go`
- [Batch synchronization](https://github.com/dhogborg/go-pocsag/blob/master/internal/pocsag/pocsag.go): `internal/pocsag/pocsag.go`
- [Batch decoding](https://github.com/dhogborg/go-pocsag/blob/master/internal/pocsag/pocsag.go): `internal/pocsag/pocsag.go`
- [Codeword decoding](https://github.com/dhogborg/go-pocsag/blob/master/internal/pocsag/pocsag.go): `internal/pocsag/pocsag.go`
- [Parity correction](https://github.com/dhogborg/go-pocsag/blob/master/internal/pocsag/pocsag.go): `internal/pocsag/pocsag.go`
- [Message assembly](https://github.com/dhogborg/go-pocsag/blob/master/internal/pocsag/pocsag.go): `internal/pocsag/pocsag.go`
- [BCD / alpha decoding](https://github.com/dhogborg/go-pocsag/blob/master/internal/pocsag/pocsag.go): `internal/pocsag/pocsag.go`

### Shared primitives

- [Sample-to-bit conversion](https://github.com/dhogborg/go-pocsag/blob/master/internal/utils/util.go): `internal/utils/util.go`
- [Bit utilities](https://github.com/dhogborg/go-pocsag/blob/master/internal/utils/util.go): `internal/utils/util.go`
- [Bit type](https://github.com/dhogborg/go-pocsag/blob/master/internal/datatypes/bit.go): `internal/datatypes/bit.go`

### Other components

- **Operator / input**
- **rtl_fm**
- **Terminal**
- **Output files**

## Connections

- Operator / input → CLI workflow: provides input
- rtl_fm → CLI workflow: streams samples
- CLI workflow → WAV reader: reads WAV
- WAV reader → WAV parser: parses file
- CLI workflow → Transmission scanner: starts scan
- Transmission scanner → Sample-to-bit conversion: converts samples
- Transmission scanner → CLI workflow: sends bit batches
- CLI workflow → POCSAG parser: parses bits
- POCSAG parser → Batch synchronization: finds batches
- Batch synchronization → Bit utilities: checks preamble
- Batch synchronization → Batch decoding: decodes batch
- Batch decoding → Codeword decoding: decodes words
- Codeword decoding → Parity correction: corrects errors
- Codeword decoding → Bit utilities: converts bits
- POCSAG parser → Message assembly: assembles messages
- Message assembly → BCD / alpha decoding: decodes payload
- CLI workflow → Terminal: prints messages
- CLI workflow → Output files: writes messages
- Sample-to-bit conversion → Bit type: creates bits
- Bit utilities → Bit type: converts bits