Architectural Primitive

Overview

Bidirectional Store-and-Forward Gateway

ISA-95 · IEC 62264 · IEC 62541-14 · EIP

BSFG is a specialized, hardened subset of EIP principles optimized for IT/OT boundary resilience rather than general-purpose enterprise integration

Problem: Industrial plants integrating modern IT/OT systems face critical resilience gaps. When enterprise systems (ERP, cloud, corporate networks) become unreachable due to network partitions, GC pauses, or infrastructure failures, plant operations typically face blocking producers, data loss, or forced shutdowns.

Solution: BSFG is a hexagonal boundary primitive with four boundary store/forward roles (ISB/IFB, ESB/EFB) and optional first-class zone-local intra-zone buffers. These roles and local continuity constructs may share the same zone-owned substrate, while preserving distinct semantics. This decouples connectivity from communication and enables autonomous operation: when the boundary seals, each zone continues via local durable and intra-zone buffering; when reconnected, boundary handoff resumes with eventual consistency and no duplication at the boundary.

Guarantee: Producer non-blocking writes, effectively-once delivery at the boundary, and transactional autonomy per zone — with zero shared state or distributed transactions.

Delivery ladder: At-least-once transport → idempotent materialization at the boundary via putIfAbsent → application-owned idempotent consumption downstream.

Motivation

BSFG exists to solve a narrow but critical problem: preserving operational autonomy at an IT/OT boundary when connectivity becomes unreliable. The goal is not to provide a general integration platform, but to make sure each zone can continue operating safely, durably, and independently when the other side is slow, partitioned, or unavailable.

That focus drives both the architecture and the documentation structure on this site. The architecture material defines the invariant boundary behavior BSFG must preserve. The reference implementation material records how the current realization satisfies those constraints in practice, including integration choices, deployment patterns, and accepted design tradeoffs.

Documentation Path

Start with Concepts to understand the architecture, then move to Integration for implementation details, and Deployment for operational guidance. Use the ADR Index to review the concrete design choices and tradeoffs made for the current reference implementation target.

→ Architecture Map

One-page structural overview

 → Concepts

Boundary roles, messages, replay

 → Integration

Producer & consumer guides

 → Deployment

Topology, security, operations

 → ADR Index

Reference implementation decisions, tradeoffs, and rationale

Interactive Model

Explore the four-buffer topology and handoff protocol in an interactive 3D scene. Click to produce or consume data from the ingress and egress lanes. Watch buffer fill states update in real time and observe how the gate controls flow between zones.

→ Open 3D Interactive Model

Standards & Normative References

BSFG aligns with the following industrial standards and patterns:

ISA-95 IEC 62264 IEC 62541-14 EIP

Documentation

Architecture

Normative and conceptual material that defines what BSFG is, what guarantees it makes, and what architectural boundaries it preserves.

Executive Brief

1-PAGER

The concise summary of the BSFG architecture and its role in industrial resilience. Covers the IT/OT integration challenge, the four-buffer topology mechanism, core guarantees, and standards alignment.

Key Topics:

  • The resilience gap problem in IT/OT integration
  • Four-buffer decomposition: ISB, IFB, ESB, EFB
  • Producer non-blocking, effectively-once boundary, fast swappability, no shared state
  • Standards compliance: ISA-95, IEC 62264, OPC UA PubSub, Enterprise Integration Patterns
Read Full Document

Technical Overview

2-PAGER

Intermediate-level technical documentation for architects and engineers. Covers the autonomy model (Normal vs. Autonomous modes), the four-step handoff protocol, hexagonal architecture with TypeScript interface contracts, backend matrix options, and proof-by-exclusion via EIP analysis.

Key Topics:

  • Autonomy requirement and mode transitions
  • Objectives vs. non-objectives table
  • Cursor management (also called the contiguous frontier)
  • Interface contracts: StoreBuffer, ForwardBuffer
  • Backend matrix: Kafka, PostgreSQL, S3, Redis, etcd
  • Backpressure and safety analysis
Read Full Document

Technical Specification (Normative)

5-PAGER

Full normative specification for implementers and standards compliance. Covers foundational constraints (objectives O1–O4, non-objectives N1–N7), minimal factorization concept, formal TypeScript interface contracts, operational modes (Normal/Autonomous/Reconciliation), failure mode analysis, threat model, and safety certification context (IEC 61508).

Key Topics:

  • Formal objectives and non-objectives
  • Minimal factorization principle
  • Typed interfaces for pluggable backends
  • Data integrity and idempotency without active reconciliation
  • Failure mode analysis and threat model tables
  • Verification matrix and safety certification roadmap
Read Full Document

Architecture Map

OVERVIEW

A one-page structural map of BSFG that reconciles principle, runtime, and substrate layers. Clarifies how the first-class boundary roles (ISB, IFB, ESB, EFB) are implemented by BSFG nodes and zone-local substrates.

Key Topics:

  • Three-layer ontology: principle/topology, logical system, substrate
  • Four-buffer topology as stable architectural primitive
  • BSFG node role implementation via JetStream, object storage, and Connect RPC
  • Message model: envelope + fact
  • Deployment patterns and invariants
Read Architecture Map

Hexagonal Architecture & BSFG

BACKGROUND

Brief explainer on Alistair Cockburn's hexagonal (ports and adapters) architecture pattern and how it applies to BSFG. Illustrates the separation between BSFG core logic (handoff protocol, cursor advancement) and pluggable storage backends.

Key Concepts:

  • Port: Interface definition (what). Example: StoreBuffer, ForwardBuffer, CursorTracker
  • Adapter: Concrete implementation (how). Example: Kafka adapter, PostgreSQL adapter, S3 adapter, Redis adapter
  • Application Core: BSFG business logic, isolated from storage implementations
  • Benefits: testability, deployment flexibility, fast backend swappability
Read Full Document

Security Model

CONCEPT

Trust boundaries, authentication, and data integrity mechanisms in BSFG deployments. Explains how BSFG maintains secure cross-zone communication using mutual TLS, zone isolation, idempotent append semantics, and immutable fact logs.

Key Topics:

  • Core security principles: zone isolation, authenticated communication, tamper resistance
  • Trust boundaries and zone independence
  • Mutual TLS authentication with certificate-based zone identity
  • Zone-based authorization and firewall policy
  • Data integrity: idempotent append, canonical JSON, content-addressed artifacts
  • Artifact security: zone-local storage, access control, immutability
  • Threat model and mitigations (MITM, unauthorized access, tampering)
  • Operational hardening: certificate rotation, audit logging, anomaly detection
Read Security Model

Reference Implementation

Implementation-facing material that explains how the current BSFG realization is integrated, named, deployed, governed, and justified.

Naming & Conventions Guide

REFERENCE

Canonical naming grammar for all identifiers in BSFG systems. Defines naming standards for subjects, predicates, schemas, streams, artifacts, and zone identities to prevent semantic drift and ensure consistency across deployments.

Key Topics:

  • Identifier principles: lower_snake_case, stability, domain-oriented naming
  • Subject naming: entity_type:identifier format with hierarchical support
  • Predicate naming: past-tense verb phrases expressing state transitions
  • Schema versioning: predicate_v# and backwards compatibility
  • Stream organization: facts.category[.prefix] with retention policies
  • Artifact paths: structured, hierarchical naming for binary files
  • Zone identity: zone-bsfg format for BSFG nodes
Read Naming & Conventions Guide

Integration Contract

OPERATIONS

Normative specification of what systems integrating with BSFG must implement. Defines the operational obligations for both actor roles that interact with the boundary API.

Key Topics:

  • Producer responsibilities — stable message_id generation, retry-safe append, artifact sequencing
  • Consumer responsibilities — idempotent processing, durable-first confirmation, replay tolerance
  • Retry semantics — what to retry, how, and when it is safe
  • Artifact lifecycle — upload-before-reference, immutability after fact-addressing
  • Delivery semantics — at-least-once transport, idempotent append, replay-based recovery
Read ADR-0043: Producer and Consumer Integration Contract

Message Catalog Framework

REFERENCE

A registry format for documenting the facts exchanged between systems in a BSFG deployment. Provides a standardized message catalog that serves as the semantic contract defining predicates, subject types, schemas, producers, and consumers.

Key Topics:

  • Fact structure: subject, predicate, object_json
  • Message catalog table format and columns
  • Schema ownership and immutability rules
  • Versioning policy and breaking change procedures
  • Example catalog entries for manufacturing integration
Read Message Catalog Framework

SOW / Deployment Specification Template

PROJECT TEMPLATE

A fillable template for creating Statements of Work (SOWs), implementation proposals, and formal deployment specifications. Provides structured sections for zone topology, BSFG node placement, network connectivity, identity configuration, storage layout, replication relationships, producer/consumer integration, monitoring setup, and acceptance criteria.

Key Topics:

  • Zone topology definition and characteristics
  • BSFG node placement and durability substrate
  • Network connectivity and firewall rules
  • mTLS identity and certificate management
  • JetStream and artifact storage configuration
  • Producer and consumer integration specifications
  • Monitoring metrics and alert thresholds
  • Acceptance criteria and sign-off procedures
Read SOW Template

Architecture Decision Records (ADRs)

DECISIONS

Accepted architectural decisions, implementation tradeoffs, and design rationale for the current BSFG realization, including boundary behavior, replay, idempotency, recovery, message model, cross-zone synchronization, and governance rules.