Architecture

Architecture

AISMixer is organized around a continuously running data plane and an optional local control plane. The data plane receives AIS transport packets, builds internal events, captures one routing snapshot for each event, matches the event source, extracts NMEA sentences, assembles multipart messages, deduplicates output, constructs TAG output, and forwards to UDP destinations.

The control plane is disabled by default. When enabled, it accepts local Unix-domain NDJSON requests and delegates routing changes to the same process-local RoutingState used by the data plane.

For deployment and security boundaries, see Operations and Deployment and Security Model.

Component Model

Event-level processing:

plain UDP sockets          UDPSEC listener
      |                         |
      v                         v
 UDP ingress adapter      UDPSEC ingress adapter
      |                         |
      +----------+--------------+
                 |
                 v
            IngressEvent
                 |
                 v
 RoutingState snapshot capture
                 |
                 v
 source_id match against snapshot
                 |
                 v
 matched target IDs, or legacy broadcast

Sentence-level processing for that event:

 raw line and matched event routing decision
                 |
                 v
 sentence extraction and TAG parsing
                 |
                 v
 multipart NMEA assembly
                 |
                 v
 global or target-scoped deduplication
                 |
                 v
            TAG output
                 |
                 v
             UDP egress

 optional local control plane:

 aismixerctl
      |
      v
 RoutingControlUnixClient
      |
      v
 RoutingControlUnixServer
      |
      v
 RoutingControlProtocol
      |
      v
 RoutingControlService
      |
      v
 RoutingState

Data Plane Components

Component	Role
UDP ingress adapter	Receives datagrams from configured udp_inputs and builds IngressEvent objects.
UDPSEC ingress adapter	Receives authenticated encrypted station traffic through the secure server path and builds IngressEvent objects.
IngressEvent	Internal event carrying kind, source_id, optional TAG s alias, remote IP, assembler key, and raw input line.
Routing snapshot	Immutable RoutingTable captured from RoutingState once per IngressEvent.
Source matching	Matches IngressEvent.source_id against the captured snapshot once for the event.
Sentence extraction	Finds AIS NMEA !AIVDM/!AIVDO sentences in the raw line and separates any immediately preceding TAG block.
TAG parsing	Reads ingress TAG s, c, and g metadata for output decisions.
Multipart assembler	Reassembles NMEA fragments using the ingress assembler identity plus NMEA fragment fields.
Deduplicator	Suppresses near-real-time duplicates globally in legacy mode or per matched target ID in routing mode.
TAG output	Constructs the outbound TAG block after deduplication accepts the sentence for output.
Forwarder	Sends to all configured UDP targets in legacy mode or selected named UDP targets in routing mode.

Control Plane Components

Component	Role
RoutingControlUnixServer	Owns the Unix-domain socket listener and newline-delimited JSON framing.
RoutingControlProtocol	Validates versioned JSON envelopes and dispatches routing.status, routing.replace, and routing.disable.
RoutingControlService	Compiles and validates candidate routing sections before installing them.
RoutingState	Owns the process-local generation number and active immutable routing snapshot.
forward_loop	Reads RoutingState snapshots for data-plane event processing.

RoutingControlUnixClient is the one-request Unix-domain client used by aismixerctl. It validates response framing and request ID correlation, but routing semantics remain server-side.

Boundaries

Adapters interpret transport namespaces. Plain UDP creates source IDs such as udp:roof_receiver, while UDPSEC creates source IDs such as udpsec:rPiAIS002.

The routing core treats source IDs and target IDs as opaque strings. It does not parse IP addresses, vessel data, TAG values, or transport-specific identity rules.

RoutingTable is immutable after compilation. Zone resolution and route definitions are compiled into a reusable snapshot.

RoutingState owns process-local generations. A replacement creates a new snapshot and increments the generation; existing snapshots are not mutated.

forward_loop captures one routing snapshot per IngressEvent. A control update affects subsequent events, not an event already being processed.

Multiprocessing coordination and IPC are not implemented. Runtime routing state does not synchronize across multiple AISMixer processes.