update architecture.md
This commit is contained in:
@@ -1,14 +1,14 @@
|
||||
# Architecture Documentation: NATSBridge
|
||||
|
||||
**Version**: 1.1.0
|
||||
**Date**: 2026-03-15
|
||||
**Date**: 2026-03-23
|
||||
**Status**: Active
|
||||
**Ground Truth**: [`src/NATSBridge.jl`](../src/NATSBridge.jl)
|
||||
**Architecture Level**: C4 Container Level
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
## 1. Executive Summary
|
||||
|
||||
This document defines the **blueprint** for NATSBridge - the cross-platform bi-directional data bridge that enables seamless communication between **Julia**, **JavaScript**, **Python**, and **MicroPython** applications using NATS as the message bus.
|
||||
|
||||
@@ -18,8 +18,29 @@ This architecture document serves as the single source of truth for:
|
||||
- **Failure Modes**: How the system handles failures and recovers
|
||||
- **Trade-off Decisions**: The rationale behind architectural decisions
|
||||
|
||||
### 1.1 Specification Traceability
|
||||
|
||||
| Architecture Section | Specification Reference | UI Specification Reference | Requirement ID(s) |
|
||||
|---------------------|-------------------------|---------------------------|-------------------|
|
||||
| Section 2 (Context Diagram) | specification.md:2 | - | FR-001, FR-002, FR-003, FR-004, FR-005, FR-006, FR-007, FR-012, FR-013, FR-014 |
|
||||
| Section 3 (Container Diagram) | specification.md:2, specification.md:3, specification.md:11 | - | FR-001, FR-002, FR-003, FR-004, FR-005, FR-006, FR-007, FR-012, FR-013, FR-014 |
|
||||
| Section 4 (Component Diagram) | specification.md:2, specification.md:3, specification.md:5, specification.md:11 | - | FR-001, FR-002, FR-003, FR-004, FR-005, FR-006, FR-007, FR-012, FR-013, FR-014 |
|
||||
| Section 5 (High-Level) | specification.md:2, specification.md:3, specification.md:5, specification.md:11 | - | FR-001, FR-002, FR-003, FR-004, FR-005, FR-006, FR-007, FR-012, FR-013, FR-014 |
|
||||
| Section 6 (Message Envelope) | specification.md:2, specification.md:3, specification.md:8 | - | FR-011, FR-012, FR-013, FR-014, NFR-401, NFR-403 |
|
||||
| Section 7 (Payload Type) | specification.md:3, specification.md:5, specification.md:6 | - | FR-001, FR-002, FR-003, FR-006, FR-012, NFR-101, NFR-102 |
|
||||
| Section 8 (Transport Strategy) | specification.md:6, specification.md:7 | - | FR-003, FR-004, FR-005, FR-010, NFR-104, NFR-105, NFR-106 |
|
||||
| Section 9 (Platform-Specific) | specification.md:13, specification.md:14 | - | FR-001, FR-002, FR-003, FR-004, FR-005, FR-006, FR-007, FR-012, FR-013, FR-014 |
|
||||
| Section 10 (Scaling) | specification.md:7, specification.md:13 | - | NFR-101, NFR-102, NFR-103, NFR-104, NFR-105, NFR-106, NFR-107 |
|
||||
| Section 11 (Failure Modes) | specification.md:9, specification.md:11 | - | FR-008, FR-009, FR-010, FR-011, NFR-201, NFR-202, NFR-203 |
|
||||
| Section 12 (Trade-offs) | specification.md:2, specification.md:3, specification.md:6, specification.md:7 | - | FR-001, FR-002, FR-003, FR-004, FR-005, FR-006, FR-007, FR-008, FR-009, FR-010, FR-011, FR-012, FR-013, FR-014 |
|
||||
| Section 13 (Deployment) | specification.md:12, specification.md:18 | - | FR-013, FR-014, NFR-201, NFR-203 |
|
||||
| Section 14 (Security) | specification.md:4, specification.md:9, specification.md:12 | - | NFR-301, NFR-302, NFR-303, NFR-401, NFR-402, NFR-403, NFR-404, NFR-405 |
|
||||
| Section 15 (Testing) | specification.md:17 | - | FR-001, FR-002, FR-003, FR-004, FR-005, FR-006, FR-007, FR-012, FR-013, FR-014 |
|
||||
|
||||
---
|
||||
|
||||
## 2. Architecture Overview
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### C4 Context Diagram
|
||||
@@ -766,12 +787,72 @@ flowchart TD
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
## 16. References
|
||||
|
||||
- [`docs/requirements.md`](./requirements.md) - Business requirements and user stories
|
||||
- [`docs/spec.md`](./spec.md) - Technical specification and contracts
|
||||
- [`src/NATSBridge.jl`](../src/NATSBridge.jl) - Ground truth implementation
|
||||
- [`README.md`](../README.md) - Project overview
|
||||
### 16.1 Documentation Artifacts
|
||||
|
||||
| Document | Purpose | Specification Traceability | UI Specification Traceability | Requirement ID(s) |
|
||||
|----------|---------|---------------------------|------------------------------|-------------------|
|
||||
| [`docs/requirements.md`](./requirements.md) | Business requirements and user stories | FR-001 through FR-014, NFR-101 through NFR-405 | - | FR-001 through FR-014, NFR-101 through NFR-405 |
|
||||
| [`docs/specification.md`](./specification.md) | Technical contract for NATSBridge | specification.md:2-19 (all sections) | - | FR-001 through FR-014, NFR-101 through NFR-405 |
|
||||
| [`docs/ui-specification.md`](./ui-specification.md) | UI specification for client applications | - | All UI components and interactions | FR-001 through FR-014, NFR-101 through NFR-405 |
|
||||
| [`docs/walkthrough.md`](./walkthrough.md) | End-to-end system flow | specification.md:2-19 (all sections) | - | FR-001 through FR-014, NFR-101 through NFR-405 |
|
||||
| [`docs/architecture.md`](./architecture.md) | System architecture diagrams | specification.md:2-19 (all sections) | - | FR-001 through FR-014, NFR-101 through NFR-405 |
|
||||
| [`docs/validation.md`](./validation.md) | CI/CD validation rules | specification.md:2-19 (all sections) | - | FR-001 through FR-014, NFR-101 through NFR-405 |
|
||||
| [`docs/runbook.md`](./runbook.md) | Operational runbook | specification.md:2-19 (all sections) | - | FR-001 through FR-014, NFR-101 through NFR-405 |
|
||||
|
||||
### 16.2 Implementation Files
|
||||
|
||||
| File | Platform | Features | Specification Traceability | Requirement ID(s) |
|
||||
|------|----------|----------|---------------------------|-------------------|
|
||||
| [`src/NATSBridge.jl`](../src/NATSBridge.jl) | Julia | Full feature set, Arrow IPC, multiple dispatch | specification.md:2-19 (all sections) | FR-001 through FR-014, NFR-101 through NFR-405 |
|
||||
| [`src/natsbridge_ssr.js`](../src/natsbridge_ssr.js) | Node.js | Arrow IPC, async/await | specification.md:2-19 (all sections) | FR-001 through FR-014, NFR-101 through NFR-405 |
|
||||
| [`src/natsbridge_csr.js`](../src/natsbridge_csr.js) | Browser | JSON table only, WebSocket NATS | specification.md:2-19 (all sections) | FR-001 through FR-014, NFR-101 through NFR-405 |
|
||||
| [`src/natsbridge.py`](../src/natsbridge.py) | Python | Arrow IPC, async/await | specification.md:2-19 (all sections) | FR-001 through FR-014, NFR-101 through NFR-405 |
|
||||
| [`src/natsbridge_mpy.py`](../src/natsbridge_mpy.py) | MicroPython | Limited to direct transport | specification.md:2-19 (all sections) | FR-005, FR-006, FR-012 |
|
||||
|
||||
### 16.3 External Dependencies
|
||||
|
||||
| Platform | Package | Version | Purpose | Specification Traceability | Requirement ID(s) |
|
||||
|----------|---------|---------|---------|---------------------------|-------------------|
|
||||
| Julia | NATS.jl | Latest | NATS client | specification.md:11 | FR-013, FR-014, NFR-201 |
|
||||
| Julia | JSON.jl | Latest | JSON serialization | specification.md:11 | FR-012, NFR-101, NFR-102 |
|
||||
| Julia | Arrow.jl | Latest | Arrow IPC support | specification.md:11 | FR-002, FR-012 |
|
||||
| Julia | HTTP.jl | Latest | HTTP file server | specification.md:11 | FR-008, FR-009 |
|
||||
| Julia | UUIDs.jl | Latest | UUID generation | specification.md:11 | FR-011, NFR-401 |
|
||||
| Node.js | nats | Latest | NATS client (TCP) | specification.md:11 | FR-013, FR-014 |
|
||||
| Node.js | node-fetch | Latest | HTTP file server | specification.md:11 | FR-008, FR-009 |
|
||||
| Browser | nats.ws | Latest | NATS client (WebSocket) | specification.md:11 | FR-013, FR-014 |
|
||||
| Browser | nats | Latest | NATS client (for bundling) | specification.md:11 | FR-013, FR-014 |
|
||||
| Python | nats-py | Latest | NATS client | specification.md:11 | FR-013, FR-014 |
|
||||
| Python | aiohttp | Latest | HTTP file server | specification.md:11 | FR-008, FR-009 |
|
||||
| Python | pyarrow | Latest | Arrow IPC support | specification.md:11 | FR-002, FR-012 |
|
||||
| MicroPython | builtin | N/A | Limited implementation | specification.md:11 | FR-005, FR-006, FR-012 |
|
||||
|
||||
---
|
||||
|
||||
## 17. Change Log
|
||||
|
||||
| Date | Version | Changes | Specification Reference |
|
||||
|------|---------|---------|------------------------|
|
||||
| 2026-03-23 | 1.1.0 | Updated to ASG Framework architecture guidelines | specification.md:2-19 (all sections) |
|
||||
| 2026-03-15 | 1.1.0 | JavaScript connection management | specification.md:2-19 (all sections) |
|
||||
| 2026-03-13 | 1.0.0 | Initial architecture documentation | specification.md:2-19 (all sections) |
|
||||
|
||||
---
|
||||
|
||||
## 18. Gap-Check Validation
|
||||
|
||||
| Stage Transition | Gap-Check Question | Status |
|
||||
|------------------|-------------------|--------|
|
||||
| Requirements → Specification | Does the Specification define all edge cases and conflict scenarios from the Requirements? | ✅ Verified - All FR-XXX requirements have corresponding spec rules |
|
||||
| Specification → UI Specification | Does the UI Specification expose all the data and states defined in the Specification? | ⏳ Pending - UI spec not yet created |
|
||||
| UI Specification → Walkthrough | Does the Walkthrough reflect the complete flow including error states and timing? | ⏳ Pending - UI spec not yet created |
|
||||
| Walkthrough → Architecture | Does the Architecture support the performance and integration requirements defined in the Walkthrough? | ✅ Verified - Architecture supports all walkthrough flows |
|
||||
|
||||
---
|
||||
|
||||
*This architecture document is versioned and maintained in git alongside the codebase. All implementations must adhere to this architecture.*
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user