From fa039f28208e9a17e92f6dd6c109223941b95053 Mon Sep 17 00:00:00 2001 From: narawat Date: Mon, 23 Mar 2026 13:33:26 +0700 Subject: [PATCH] update architecture.md --- docs/architecture.md | 95 ++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 88 insertions(+), 7 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 2697ccf..d33127a 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -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.* ---