Architecture Evolution

Architecture Evolution

This page records why the architecture changed. It is historical context, not a second roadmap or behavioural specification.

Original baseline

AISMixer began as a practical Python stream service centered on:

• network ingress;
• extraction and normalization of AIS NMEA text;
• multipart assembly;
• NMEA TAG handling;
• near-real-time deduplication; and
• UDP forwarding.

Logical source_id and target_id routing, immutable routing snapshots, and the optional local control plane were added later. Legacy broadcast behavior was retained for configurations without an active routing table.

Campaign A: behavioural contract

Campaign A preserved Python as the reference implementation while making observable processing behavior explicit.

Its main architectural outcomes were:

• a normative behavioural contract;
• precise ingress and extraction boundaries;
• explicit multipart ordering, duplicate, conflict, and completion behavior;
• clear separation of routing identity and emitted TAG metadata;
• group-atomic multipart deduplication;
• one immutable routing decision per accepted string event;
• deterministic clock and generator seams for tests; and
• a defined surface for future differential comparison.

Campaign A did not select a native API or change the data-plane implementation language.

Campaign B: explicit state and limits

Campaign B focused on state as an architectural responsibility rather than an incidental collection of containers.

Deduplication

• One authoritative process-local owner.
• Monotonic TTL with exact boundary behavior.
• Duplicate non-refresh.
• Optional instance-wide capacity.
• Expiry before deterministic oldest-live eviction.
• Explicit reset and immutable statistics.

Multipart assembly and TAG context

• Explicit per-generation assembler state.
• Unique-progress timestamps and exact duplicate non-refresh.
• Single-sentence and invalid/limit paths isolated from multipart state.
• Optional fragment and pending-group limits.
• Deterministic lifecycle outcomes and discarded keys.
• Forwarding-owned TAG s, c, and g cleanup synchronized with assembler conflict, expiry, capacity, completion, and reset boundaries.

Secure ingress

• One SecureState owner for replay records, sessions, and per-session nonces.
• Separation of protocol wall time from local monotonic lifecycle time.
• Hard replay, session, and nonce capacities.
• Deterministic expiry, replacement, and eviction behavior.
• Traffic-driven cleanup and restart loss made explicit.
• Immutable statistics with mutually exclusive removal accounting.

Closure baseline

The source repository records a Campaign B audit baseline in its canonical behavioural contract. That snapshot confirms a point in project history; its test counts are not permanent compatibility guarantees.

Campaign C: data representation

Campaign C changed the production representation path while preserving the Campaign A and B observable and lifecycle semantics:

• built-in UDP and UDPSEC producers enqueue immutable IngressFrame values, while valid legacy IngressEvent inputs cross one compatibility adapter;
• each accepted frame receives one routing snapshot and, only for an active table, one match against frame.source_id;
• the scanner works on bytes and returns immutable half-open spans;
• ParsedSentence carries parse-once fragment and relevant TAG metadata; and
• production assembly enters through feed_parsed_outcome(), while the valid legacy string feed_outcome() API converges on the same lifecycle.

The Python assembler still materializes and stores sentence strings, and forwarding output remains string-based. Campaign C did not add a stable processor API or ABI, native code, end-to-end zero-copy processing, benchmarks, or multiprocessing.

Architectural result

The current Python reference now makes representation boundaries explicit and these questions answerable for each contract-relevant state item:

Who owns it?
What is its identity?
Which clock applies?
When does it expire?
What is its capacity?
What refreshes it?
Why was it removed?
Is it durable or shared?

This is the basis for the State, Lifecycle, and Limits model and the Native-Ready Reference Foundation.

Future direction

The maintained Roadmap describes possible staged work without dates:

• a coordinator plus dedicated ingress and egress workers;
• lifecycle supervision and failure handling;
• IPC distribution of routing snapshots;
• optional routing-state restoration or persistence research;
• safe configuration reload or watch behavior;
• rollback history and richer operational observability;
• additional egress and control transports;
• maritime security, spoof/anomaly, and feed-quality research.

Separately, the behavioural contract supplies the observable Python reference for possible future differential conformance. A stable processor contract, native implementation or bindings, bytes-native assembler/output state, and benchmarks remain deferred; the roadmap does not commit to such a processor.

These are directions, not implemented guarantees. In particular, there is no multiprocessing coordinator, IPC state sharing, persistent routing, automatic reload, spoof detector, or native processor today.

Sources

• Normative behavioural contract
• Project roadmap
• Trilingual README