Audience: Solution architects, delivery teams. Use: Produce project-specific deployment specifications and statements of work.
Overview
This template provides a structured format for creating a Statement of Work (SOW), implementation proposal, or formal deployment specification based on the BSFG architecture. It ensures all technical, operational, and contractual aspects of a BSFG deployment are clearly documented before implementation begins.
How to use this template: Fill in each section with your specific project details. Replace bracketed text like [FILL IN] with your actual values. Use the example rows as guidance; add or remove rows as needed for your project.
Project Context
Describe the integration challenge and BSFG's role. Example:
Template: This project integrates [ENTERPRISE SYSTEMS] in the Enterprise zone with [OT SYSTEMS] in Plant A and Plant B OT zones, while maintaining strict network segmentation per [COMPLIANCE STANDARD]. BSFG acts as the boundary primitive, enabling asynchronous fact exchange across firewall boundaries without requiring durable middleware at the network perimeter.
Include:
- Business drivers (regulatory compliance, operational resilience, system modernization)
- Network topology constraints (air gaps, DMZ presence, cloud integration requirements)
- Data sensitivity and retention requirements
Zone Topology
Define the zones and their characteristics. Add or remove rows as needed.
Instructions: Each zone is a trust boundary and operational domain. List all zones in the deployment. For each zone, describe its purpose, resident systems, and network characteristics.
| Zone Name | Description | Resident Systems | Network Characteristics | Owner/Team |
|---|---|---|---|---|
| [Zone Name] | Corporate IT, cloud integrations, analytics | ERP, data lake, business apps | Internet-connected, cloud-capable | [Owner] |
| [Zone Name] | Industrial DMZ mediation zone (optional) | BSFG node, firewalls, VPN terminators | Firewalled both sides, no internet, zone-owned durable state allowed | [Owner] |
| [Zone Name] | Manufacturing network | MES, PLC, historians, batch systems | Closed network, air-gapped from IT | [Owner] |
BSFG Node Placement
Define which zones host BSFG nodes and their durability requirements.
Critical rule: Durable middleware must not live in the boundary network itself. If IDMZ is modeled as a real zone, it may host a zone-owned BSFG node with its own durable state. See ADR-0001.
| Zone | BSFG Node Hostname | Durability Substrate | HA Configuration | Capacity |
|---|---|---|---|---|
| [Zone Name] | enterprise-bsfg | JetStream cluster (3-node) + S3 object store | Active-active, multi-region failover | 100+ GB JetStream, 10+ TB S3 |
| [IDMZ, if present] | idmz-bsfg | JetStream (compact) + compact object store, zone-owned | Single-node or HA pair | 1–5 GB JetStream, compact object store |
| [Plant Zone] | plant-a-bsfg | JetStream (single or dual-node) + NAS/SSD | Single-node or replicated WAL | 1–5 GB JetStream, 1–5 TB local storage |
Network Connectivity
Define firewall rules and RPC endpoint exposure.
Key principle: Only BSFG RPC endpoints are exposed across zone boundaries. JetStream and object storage remain zone-local. All cross-zone communication uses mTLS over Connect RPC.
| Source Node | Destination Node | Port | Protocol | Purpose | Firewall Rule ID |
|---|---|---|---|---|---|
| enterprise-bsfg | plant-a-bsfg | 9443 (or TBD) | mTLS + Connect RPC | Bidirectional fact replication | [FW Rule ID] |
| plant-a-bsfg | enterprise-bsfg | 9443 (or TBD) | mTLS + Connect RPC | Bidirectional fact replication | [FW Rule ID] |
Network assumptions:
- All BSFG RPC endpoints are reachable via DNS names (FQDNs) or static IPs
- mTLS certificate validation succeeds (CA trust chain is established)
- JetStream cluster (if multi-node) operates within the zone only, not across zones
- Object storage is zone-local (S3, NAS, or equivalent)
Identity and Certificates
Define the mTLS certificate structure and zone identities.
Requirement: Each BSFG node has a certificate whose CN (Common Name) identifies the zone. Peer zones validate the CN to ensure they are communicating with the correct counterpart. See Identity Model.
| BSFG Node | Certificate CN | Issuer CA | Validity Period | Renewal Date |
|---|---|---|---|---|
| enterprise-bsfg | enterprise-bsfg | Enterprise Internal CA | 1 year (YYYY-MM-DD to YYYY-MM-DD) | [Date 30 days before expiry] |
| plant-a-bsfg | plant-a-bsfg | Enterprise Internal CA | 1 year (YYYY-MM-DD to YYYY-MM-DD) | [Date 30 days before expiry] |
Certificate requirements:
- Key usage: TLS Server Authentication + TLS Client Authentication
- Subject Alternative Name (SAN): FQDN and/or IP address of the BSFG node
- Signed by a shared CA trusted by all zones
- Certificate chain must be complete and retrievable
Storage Configuration
Define JetStream domains and artifact storage for each zone.
Principle: Each zone owns its JetStream domain and artifact storage. There is no shared substrate at the boundary. Facts are replayed from zone to zone, not mirrored in real-time.
| Zone | JetStream Domain Name | Artifact Storage Type | Artifact Storage Path/Bucket | Retention Policy |
|---|---|---|---|---|
| Enterprise | enterprise-domain | AWS S3 | s3://enterprise-bsfg-artifacts/ | batch-files: 10 years, alarms: 3 months, documents: 7 years |
| Plant A | plant-a-domain | Local NAS or SSD | /mnt/bsfg-artifacts/ | batch-files: 7 years, alarms: 1 year |
Stream configuration: Each JetStream domain contains a small fixed set of streams per subject kind:
facts.operational— production events (orders, batches, process data)facts.audit— system events (access logs, changes, errors)facts.documents— document references and metadata
Artifact buckets organize by subject kind:
batch-files— batch records, recipes, instructionsasset-files— CAD drawings, equipment specificationsalarm-files— alarm logs and historical trendsdocument-files— general documents and reports
Replication Relationships
Define which zones synchronize facts with each other.
Model: Replication is receiver-driven. The receiving zone calls FetchFacts from the sending zone via BSFG peer RPC, retrieves facts, and confirms receipt. This is asynchronous and decouples producer throughput from consumer processing speed.
| Receiving Zone | Sending Zone | Fact Types | Update Cadence | Consumer Name |
|---|---|---|---|---|
| Plant A | Enterprise | order_created, order_modified, order_shipped | Real-time pull (1–5 second latency) | plant-a-from-enterprise |
| Enterprise | Plant A | batch_started, batch_completed, production_event | Real-time pull (1–5 second latency) | enterprise-from-plant-a |
See Peer Replication for detailed protocol specification.
Producer Integration
Define which systems emit facts into BSFG.
Requirement: Producers must generate a stable message_id from the business event (e.g., hash of order ID + timestamp). This enables idempotent retry: if a producer crashes after appending a fact, it can safely re-append the same message with the same ID without creating duplicates. See Producer Guide.
| System | Zone | Fact Types Emitted | Message ID Derivation | Expected Throughput |
|---|---|---|---|---|
| ERP System | Enterprise | order_created, order_modified, shipment_created | SHA256(order_id + event_type) | 100 facts/second |
| MES | Plant A | batch_started, batch_completed, machine_event | SHA256(batch_id + sequence_number) | 50 facts/second |
Artifact handling: For each producer that references artifacts (PDFs, images, batch files), specify:
- Artifact types (e.g., batch recipes, inspection reports)
- Upload sequence (PutObject before AppendFact)
- Object bucket assignment
- Artifact retention period
Consumer Integration
Define which systems consume facts from BSFG.
Requirement: Consumers must process facts idempotently. At-least-once delivery is the boundary guarantee: the same fact may be delivered more than once, especially during network recovery. Consumers must either deduplicate by message ID or be naturally idempotent. See Consumer Guide.
| System | Zone | Consumed Fact Types | Idempotency Strategy | Consumer Name |
|---|---|---|---|---|
| Data Lake | Enterprise | production_event, batch_completed, shipment_created | Natural upsert on batch_id | data-lake-consumer |
| MES Dashboard | Plant A | order_created, order_modified | Deduplicate by message_id before update | mes-dashboard-consumer |
Confirmation requirement: Consumers must persist their business outcome durably (e.g., to database, data warehouse) before calling ConfirmReceipt. If a consumer confirms early and then crashes before persisting, facts will be replayed on recovery and may create duplicates.
Monitoring and Operations
Define metrics, alerts, and operational procedures.
Key Metrics
Implement monitoring dashboards for:
| Metric | Unit | Healthy Range | Warning Threshold | Alert Threshold |
|---|---|---|---|---|
| Replication Lag (ISB → IFB) | milliseconds | <100 ms | 100–500 ms | >1000 ms |
| Consumer Backlog | number of facts | 0–100 | 100–10,000 | >10,000 |
| Buffer Fill Percentage | % | <50% | 50–80% | >80% |
| Fact Append Rate | facts/second | [Baseline] | [±20%] | [±50% or zero for >60s] |
| mTLS Handshake Errors | count/minute | 0 | N/A | >0 (immediate alert) |
| RPC Latency (p99) | milliseconds | <50 ms | 50–200 ms | >500 ms |
Alert Escalation
Define alert routing:
- Tier 1 (Operational): Replication lag, consumer backlog, buffer fill — notify ops team for investigation
- Tier 2 (Security): mTLS errors, certificate expiry — escalate to security/ops immediately
- Tier 3 (Business): Zero append rate for >5 minutes — escalate to platform team and business owner
See Operations Runbook for detailed failure mode recovery procedures.
Acceptance Criteria
Define testable verification items for deployment readiness.
Before production: All items below must pass verification. Document test results and sign off.
- ☐ Producer can append facts when remote zone is unreachable (autonomous operation)
- ☐ Facts replicate after network restoration with no data loss
- ☐ Duplicate replayed facts do not corrupt consumer state (idempotent processing confirmed)
- ☐ Artifact upload succeeds and referenced facts reference correct artifacts
- ☐ Artifact retrieval succeeds from consumer zone
- ☐ Replication lag <100 ms under normal load
- ☐ Consumer backlog drains within 5 minutes of producer availability
- ☐ mTLS handshakes succeed from all peer zones
- ☐ Certificate rotation completed without service interruption
- ☐ Monitoring dashboards display all required metrics
- ☐ Alert thresholds trigger correctly
- ☐ Producer message_id derivation is stable across restarts
- ☐ Consumer confirmation is durable (survives crash/restart)
- ☐ Backpressure policy activates correctly (reject or drop oldest)
- ☐ Network partition recovery completes without manual intervention (reconciliation mode)
Sign-Off and Approval
This deployment specification must be reviewed and approved by all stakeholders before implementation.
| Role | Name | Organization | Signature / Date | Approval |
|---|---|---|---|---|
| Enterprise Platform Team | [Name] | [Org] | [Date] | ☐ Approved |
| Plant Engineering Lead | [Name] | [Org] | [Date] | ☐ Approved |
| Network Operations | [Name] | [Org] | [Date] | ☐ Approved |
| Security / Compliance | [Name] | [Org] | [Date] | ☐ Approved |
References and Supporting Documentation
- BSFG Architecture Map — One-page structural overview
- Boundary Roles — ISB, IFB, ESB, EFB explanations
- Peer Replication Protocol — Cross-zone synchronization details
- Integration Contract — Producer and consumer obligations
- Producer Guide — Implementation patterns for emitters
- Consumer Guide — Implementation patterns for consumers
- Enterprise + IDMZ + Plant Topology — Reference deployment architecture
- Enterprise + IDMZ + 2 Plants Reference Deployment — Detailed production example
- Network Policy — mTLS and firewall requirements
- Identity Model — Zone identity and certificate binding
- Operations Runbook — Monitoring, failure modes, recovery procedures
- ADR Index — Complete decision history (43 ADRs)