BSFG Object Topology

Purpose

This page defines the concrete object topology of the reference implementation: which objects exist, where they live, and which interfaces connect them.

Object Layers

flowchart TB
  subgraph APP["Application Layer"]
    PROD["Producers"]
    CONS["Consumers"]
  end

  subgraph SVC["BSFG Service Layer"]
    RPC["Connect RPC Server
AppendFact
FetchFacts
ConfirmReceipt
PutObject"]
    COORD["Boundary Coordinator
mode + routing + policy"]
    CURSOR["Cursor Tracker"]
  end

  subgraph STORE["Durability Layer"]
    ISB["ISB Store Buffer"]
    IFB["IFB Forward Buffer"]
    ESB["ESB Store Buffer"]
    EFB["EFB Forward Buffer"]
    OBJ["Artifact Object Store"]
  end

  subgraph SUB["Substrate Layer (NATS/JetStream)"]
    JS["JetStream Streams + Durable Consumers"]
    ACC["NATS Accounts + ACLs"]
  end

  PROD --> RPC
  RPC --> COORD
  COORD --> ISB
  COORD --> ESB
  COORD --> IFB
  COORD --> EFB
  COORD --> CURSOR
  RPC --> OBJ
  CONS --> RPC

  ISB --> JS
  IFB --> JS
  ESB --> JS
  EFB --> JS
  CURSOR --> JS
  JS --> ACC

Zone Topology (Per Direction)

flowchart LR
  subgraph EZ["External Zone"]
    EZ_RPC["BSFG Node (external)"]
    EZ_ISB["ISB"]
    EZ_EFB["EFB"]
    EZ_RPC --> EZ_ISB
    EZ_EFB --> EZ_RPC
  end

  subgraph IZ["Internal Zone"]
    IZ_RPC["BSFG Node (internal)"]
    IZ_IFB["IFB"]
    IZ_ESB["ESB"]
    IZ_IFB --> IZ_RPC
    IZ_RPC --> IZ_ESB
  end

  EZ_ISB -->|"async handoff"| IZ_IFB
  IZ_ESB -->|"async handoff"| EZ_EFB

Structural Ownership

• Zone-owned objects: ISB, IFB, ESB, EFB, object store, account credentials.
• Boundary-owned logic: coordinator, gate-mode transitions, cursor advancement.
• Shared-nothing rule: no cross-zone shared DB/stream/object bucket.

Where Definitions Live (Code)

• Runtime composition: apps/bsfg-gateway
• Protocol/domain rules: packages/bsfg-core
• Contracts: packages/proto-contracts
• Substrate adapters: packages/nats-adapters
• Docs build topology references: apps/docs/docs/deployment