# bertoldvdb/go-ais architecture

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

- Interactive diagram: https://gitdiagram.com/bertoldvdb/go-ais
- Repository: https://github.com/bertoldvdb/go-ais

## Overview

1. **Repository purpose**
   - This is a Go library for AIS packet encoding and decoding.
   - The architecture is intentionally split into two layers: a **core AIS codec** and an optional **NMEA sentence wrapper** for VDM/VDO input/output.

2. **Core AIS subsystem (`ais` root package)**
   - The root package is the main data-processing engine.
   - It works on AIS payloads as bit-oriented data, not on NMEA strings.
   - Public entry points are centered around `CodecNew`, `DecodePacket`, and `EncodePacket`, which convert between raw AIS bits and strongly typed Go message structs.

3. **Message model and generated codec tables**
   - `messages.go` defines the typed AIS message structures used by the decoder/encoder.
   - `codec.go` plus `codec_gen.go` contain the codec logic and generated message-field handling.
   - This suggests a code-generated mapping between AIS message IDs/fields and Go structs, which is important for both completeness and maintainability.

4. **Build-time code generation**
   - `parser_generator/main.go` is the generator that produces `codec_gen.go`.
   - Architecturally, this means the message schema is not hand-coded in full; the parser/generator pipeline is part of the repo’s build process and drives the core codec implementation.

5. **NMEA convenience layer (`aisnmea`)**
   - The `aisnmea` package is a higher-level adapter for AIS messages carried inside NMEA sentences.
   - It handles sentence parsing, multi-fragment assembly, and NMEA tag blocks, then hands the recovered AIS payload to the core codec.
   - This keeps the AIS standard logic separate from transport/framing concerns, which is one of the repo’s explicit design goals.

6. **NMEA framing and assembly**
   - `aisnmea/nmea.go` and `aisnmea/assembler.go` cover sentence parsing and fragment reassembly.
   - `aisnmea/tagblocks.go` handles NMEA tag blocks, which are metadata prefixes often attached to VDM/VDO sentences.
   - The flow here is: **NMEA sentence(s) → assembled AIS payload → core decode**.

7. **Fast parsing path (`aisnmeafast`)**
   - `aisnmeafast/parse.go` is a separate optimized parser implementation.
   - Its presence indicates a performance-oriented path for parsing NMEA-related input without changing the AIS codec itself.
   - In the architecture diagram, this belongs on the NMEA side, alongside the convenience wrapper rather than inside the AIS codec core.

8. **Decode and encode data flow**
   - **Decode path:** raw AIS bits or NMEA-framed AIS → parser/assembler → `DecodePacket` → typed AIS struct.
   - **Encode path:** typed AIS struct → `EncodePacket` → AIS bit payload → NMEA encoder if the caller wants a sentence format.
   - The repo treats AIS message semantics and NMEA transport as distinct stages, with a clean handoff between them.

9. **Validation and regression coverage**
   - The repository includes extensive tests: `decode_test.go`, `encode_fail_test.go`, `reencode_test.go`, `frequency_test.go`, `regression_test.go`, and fuzz tests.
   - `testmsg/` and `testdata/` provide real-world or corpus-based fixtures, including fuzz inputs and a sample NMEA file.
   - This indicates the architecture is protected by corpus validation and round-trip checks, not just unit tests.

10. **Practical boundary for diagramming**
   - If you are drawing the architecture, the key boundary is between:
     - **transport/framing**: NMEA sentences, tag blocks, fragment assembly, fast parsing
     - **domain codec**: AIS packet interpretation, typed messages, encode/decode generation
   - The core library can operate without NMEA, while `aisnmea` is a convenience layer for AIS-in-NMEA integrations.

Main entry points: [`codec.go`](https://github.com/bertoldvdb/go-ais/blob/master/codec.go) (Codec API), [`aisnmea/nmea.go`](https://github.com/bertoldvdb/go-ais/blob/master/aisnmea/nmea.go) (NMEA wrapper), [`aisnmea/tagblocks.go`](https://github.com/bertoldvdb/go-ais/blob/master/aisnmea/tagblocks.go) (Tag blocks), [`aisnmeafast/parse.go`](https://github.com/bertoldvdb/go-ais/blob/master/aisnmeafast/parse.go) (Fast parse)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core AIS codec"]
  node_codec["Codec API<br/>ais package<br/>[codec.go]"]
  node_messages["Messages<br/>AIS structs<br/>[messages.go]"]
  node_codecgen["Codec tables<br/>generated mapping<br/>[codec_gen.go]"]
end

subgraph group_nmea["NMEA layer"]
  node_nmeaapi["NMEA wrapper<br/>aisnmea package<br/>[nmea.go]"]
  node_assembler["Assembler<br/>fragment reassembly<br/>[assembler.go]"]
  node_tagblocks["Tag blocks<br/>metadata parser<br/>[tagblocks.go]"]
  node_fastparse["Fast parse<br/>optimized parser<br/>[parse.go]"]
end

subgraph group_build["Code generation"]
  node_generator["Generator<br/>codegen tool<br/>[main.go]"]
end

subgraph group_validation["Validation corpus"]
  node_decode_test["Decode tests<br/>round-trip tests<br/>[decode_test.go]"]
  node_encode_fail_test["Encode tests<br/>failure tests"]
  node_reencode_test["Reencode tests<br/>round-trip tests<br/>[reencode_test.go]"]
  node_regression_test["Regression tests<br/>corpus tests<br/>[regression_test.go]"]
  node_fast_parse_test["Fast parse tests<br/>parser tests<br/>[fast_parse_test.go]"]
  node_aisnmea_test["NMEA tests<br/>wrapper tests<br/>[nmea_test.go]"]
  node_tagblocks_test["Tag tests<br/>metadata tests<br/>[tagblocks_test.go]"]
  node_fuzzdata[("Fuzz corpus<br/>fuzz inputs")]
  node_testmsg[("Message corpus<br/>sample messages")]
  node_nmeadata["NMEA sample<br/>fixture file<br/>[aistest.nmea]"]
end

node_generator -->|"generates"| node_codecgen
node_codecgen -->|"drives"| node_codec
node_messages -->|"typed model"| node_codec
node_codec -.->|"verified by"| node_decode_test
node_codec -.->|"verified by"| node_encode_fail_test
node_codec -.->|"verified by"| node_reencode_test
node_codec -.->|"verified by"| node_regression_test
node_testmsg -->|"fixtures"| node_reencode_test
node_fuzzdata -->|"corpus"| node_decode_test
node_nmeaapi -->|"uses"| node_assembler
node_nmeaapi -->|"uses"| node_tagblocks
node_assembler -->|"hands off"| node_codec
node_tagblocks -->|"feeds"| node_nmeaapi
node_fastparse -->|"accelerates"| node_nmeaapi
node_nmeadata -->|"fixtures"| node_aisnmea_test
node_nmeaapi -.->|"verified by"| node_aisnmea_test
node_tagblocks -.->|"verified by"| node_tagblocks_test
node_fastparse -.->|"verified by"| node_fast_parse_test
node_codec -.->|"optional output"| node_nmeaapi

click node_codec "https://github.com/bertoldvdb/go-ais/blob/master/codec.go"
click node_messages "https://github.com/bertoldvdb/go-ais/blob/master/messages.go"
click node_codecgen "https://github.com/bertoldvdb/go-ais/blob/master/codec_gen.go"
click node_generator "https://github.com/bertoldvdb/go-ais/blob/master/parser_generator/main.go"
click node_nmeaapi "https://github.com/bertoldvdb/go-ais/blob/master/aisnmea/nmea.go"
click node_assembler "https://github.com/bertoldvdb/go-ais/blob/master/aisnmea/assembler.go"
click node_tagblocks "https://github.com/bertoldvdb/go-ais/blob/master/aisnmea/tagblocks.go"
click node_fastparse "https://github.com/bertoldvdb/go-ais/blob/master/aisnmeafast/parse.go"
click node_decode_test "https://github.com/bertoldvdb/go-ais/blob/master/decode_test.go"
click node_encode_fail_test "https://github.com/bertoldvdb/go-ais/blob/master/encode_fail_test.go"
click node_reencode_test "https://github.com/bertoldvdb/go-ais/blob/master/reencode_test.go"
click node_regression_test "https://github.com/bertoldvdb/go-ais/blob/master/regression_test.go"
click node_fast_parse_test "https://github.com/bertoldvdb/go-ais/blob/master/fast_parse_test.go"
click node_aisnmea_test "https://github.com/bertoldvdb/go-ais/blob/master/aisnmea/nmea_test.go"
click node_tagblocks_test "https://github.com/bertoldvdb/go-ais/blob/master/aisnmea/tagblocks_test.go"
click node_fuzzdata "https://github.com/bertoldvdb/go-ais/tree/master/testdata/fuzz/FuzzDecode"
click node_testmsg "https://github.com/bertoldvdb/go-ais/tree/master/testmsg"
click node_nmeadata "https://github.com/bertoldvdb/go-ais/blob/master/aisnmea/testdata/aistest.nmea"

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_codec,node_messages,node_codecgen toneBlue
class node_nmeaapi,node_assembler,node_tagblocks,node_fastparse toneAmber
class node_generator toneMint
class node_decode_test,node_encode_fail_test,node_reencode_test,node_regression_test,node_fast_parse_test,node_aisnmea_test,node_tagblocks_test,node_fuzzdata,node_testmsg,node_nmeadata toneRose
```

## Components

### Core AIS codec

Bit-level AIS encoding and decoding, independent of NMEA framing.

- [Codec API](https://github.com/bertoldvdb/go-ais/blob/master/codec.go): ais package · Public entry points for creating codecs and decoding/encoding AIS packets. · `codec.go`
- [Messages](https://github.com/bertoldvdb/go-ais/blob/master/messages.go): AIS structs · Typed AIS message definitions used by the codec. · `messages.go`
- [Codec tables](https://github.com/bertoldvdb/go-ais/blob/master/codec_gen.go): generated mapping · Generated field and message handling used by the core codec. · `codec_gen.go`

### NMEA layer

Sentence parsing, assembly, and convenience wrappers around AIS payloads.

- [NMEA wrapper](https://github.com/bertoldvdb/go-ais/blob/master/aisnmea/nmea.go): aisnmea package · Higher-level entry point for AIS carried in NMEA sentences. · `aisnmea/nmea.go`
- [Assembler](https://github.com/bertoldvdb/go-ais/blob/master/aisnmea/assembler.go): fragment reassembly · Combines multi-fragment NMEA sentences into complete AIS payloads. · `aisnmea/assembler.go`
- [Tag blocks](https://github.com/bertoldvdb/go-ais/blob/master/aisnmea/tagblocks.go): metadata parser · Parses NMEA tag blocks attached to VDM/VDO sentences. · `aisnmea/tagblocks.go`
- [Fast parse](https://github.com/bertoldvdb/go-ais/blob/master/aisnmeafast/parse.go): optimized parser · Performance-oriented NMEA parsing path. · `aisnmeafast/parse.go`

### Code generation

Build-time generation that feeds the codec tables.

- [Generator](https://github.com/bertoldvdb/go-ais/blob/master/parser_generator/main.go): codegen tool · Build-time generator that produces the codec table source. · `parser_generator/main.go`

### Validation corpus

Tests and fixtures that protect decoding, encoding, and round-trip behavior.

- [Decode tests](https://github.com/bertoldvdb/go-ais/blob/master/decode_test.go): round-trip tests · Core decode regression and correctness coverage. · `decode_test.go`
- [Encode tests](https://github.com/bertoldvdb/go-ais/blob/master/encode_fail_test.go): failure tests · Checks encoding failures and invalid cases. · `encode_fail_test.go`
- [Reencode tests](https://github.com/bertoldvdb/go-ais/blob/master/reencode_test.go): round-trip tests · Validates decode/encode symmetry over messages. · `reencode_test.go`
- [Regression tests](https://github.com/bertoldvdb/go-ais/blob/master/regression_test.go): corpus tests · Protects against previously observed decoding issues. · `regression_test.go`
- [Fast parse tests](https://github.com/bertoldvdb/go-ais/blob/master/fast_parse_test.go): parser tests · Covers the optimized NMEA parsing path. · `fast_parse_test.go`
- [NMEA tests](https://github.com/bertoldvdb/go-ais/blob/master/aisnmea/nmea_test.go): wrapper tests · Tests for sentence parsing, assembly, and tag blocks. · `aisnmea/nmea_test.go`
- [Tag tests](https://github.com/bertoldvdb/go-ais/blob/master/aisnmea/tagblocks_test.go): metadata tests · Validates NMEA tag block parsing. · `aisnmea/tagblocks_test.go`
- [Fuzz corpus](https://github.com/bertoldvdb/go-ais/tree/master/testdata/fuzz/FuzzDecode): fuzz inputs · Corpus used to harden AIS decoding against malformed inputs. · `testdata/fuzz/FuzzDecode`
- [Message corpus](https://github.com/bertoldvdb/go-ais/tree/master/testmsg): sample messages · Sample AIS message fixtures for round-trip and regression validation. · `testmsg`
- [NMEA sample](https://github.com/bertoldvdb/go-ais/blob/master/aisnmea/testdata/aistest.nmea): fixture file · Sample NMEA sentence data used by the wrapper tests. · `aisnmea/testdata/aistest.nmea`

## Connections

- Generator → Codec tables: generates · Produces the generated codec table source.
- Codec tables → Codec API: drives · Supplies message-field handling for encoding and decoding.
- Messages → Codec API: typed model · Defines the structured AIS messages handled by the codec.
- Codec API → Decode tests: verified by · Core decode behavior is exercised by tests.
- Codec API → Encode tests: verified by · Invalid encode paths are covered by tests.
- Codec API → Reencode tests: verified by · Round-trip behavior is validated against fixtures.
- Codec API → Regression tests: verified by · Regression coverage protects the core codec.
- Message corpus → Reencode tests: fixtures · Sample messages feed round-trip checks.
- Fuzz corpus → Decode tests: corpus · Fuzz corpus hardens decode behavior.
- NMEA wrapper → Assembler: uses · Wrapper relies on fragment assembly.
- NMEA wrapper → Tag blocks: uses · Wrapper parses NMEA metadata prefixes.
- Assembler → Codec API: hands off · Recovered AIS payload is decoded by the core codec.
- Tag blocks → NMEA wrapper: feeds · Tag block metadata is attached to parsed sentences.
- Fast parse → NMEA wrapper: accelerates · Optimized path for NMEA-oriented parsing.
- NMEA sample → NMEA tests: fixtures · Sample NMEA data supports wrapper tests.
- NMEA wrapper → NMEA tests: verified by · NMEA wrapper behavior is covered by tests.
- Tag blocks → Tag tests: verified by · Tag parsing is tested directly.
- Fast parse → Fast parse tests: verified by · Optimized parsing path is covered by tests.
- Codec API → NMEA wrapper: optional output · Core AIS payloads can be wrapped into NMEA sentences by higher-level callers.