From b0c5ecb9423f1b2585763176d2e19200beaef6d3 Mon Sep 17 00:00:00 2001 From: narawat Date: Mon, 23 Mar 2026 13:03:27 +0700 Subject: [PATCH] update walkthrough doc --- docs/walkthrough.md | 75 +++++++++++++++++++++++++++++++++++++++------ 1 file changed, 66 insertions(+), 9 deletions(-) diff --git a/docs/walkthrough.md b/docs/walkthrough.md index 92fc129..3c86170 100644 --- a/docs/walkthrough.md +++ b/docs/walkthrough.md @@ -1,23 +1,40 @@ # Walkthrough: NATSBridge **Version**: 1.0.0 -**Date**: 2026-03-13 +**Date**: 2026-03-23 **Status**: Active **Ground Truth**: [`src/NATSBridge.jl`](../src/NATSBridge.jl) --- -## Executive Summary +## 1. Executive Summary -This document provides the **story of flow** 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. +This document provides the **end-to-end trace** 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. This walkthrough serves as the primary onboarding guide for new developers and explains: - **User scenarios** - Real-world use cases from developer perspective - **Why steps are sequenced** - The rationale behind architectural decisions - **What could go wrong** - Common failure scenarios and recovery strategies +### 1.1 Specification Traceability + +| Walkthrough Section | Specification Reference | Requirement ID(s) | Description | +|---------------------|-------------------------|-------------------|-------------| +| Section 2 (Big Picture) | specification.md:2, specification.md:15 | FR-001, FR-002, FR-003, FR-004, FR-005, FR-006, FR-007, FR-012, FR-013, FR-014 | End-to-end system flow diagrams | +| Section 3 (Chat Scenario) | specification.md:2, specification.md:3, specification.md:5, specification.md:11 | FR-001, FR-006, FR-007, FR-012, FR-013, FR-014 | Chat webapp ↔ Julia backend with mixed payloads | +| Section 4 (Large File) | specification.md:6, specification.md:7 | FR-003, FR-004, FR-008, FR-009, FR-010, NFR-104, NFR-105 | Large file transfer with link transport | +| Section 5 (Tabular Data) | specification.md:5, specification.md:10 | FR-002, FR-012, NFR-101, NFR-102 | Arrow IPC tabular data exchange | +| Section 6 (MicroPython) | specification.md:13, specification.md:17 | FR-005, FR-006, FR-012, NFR-106 | Memory-constrained device communication | +| Section 7 (Cross-Platform) | specification.md:3, specification.md:4, 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 | Multi-platform chat application | +| Section 8 (Error Handling) | specification.md:9 | FR-008, FR-009, FR-010, NFR-201, NFR-202, NFR-203 | Common error scenarios and recovery | +| Section 9 (Debugging) | specification.md:4, specification.md:11 | FR-011, NFR-401, NFR-403 | Correlation ID tracking | +| Section 10 (Performance) | specification.md:7, specification.md:13 | NFR-101, NFR-102, NFR-103, NFR-104, NFR-105, NFR-106, NFR-107 | Optimization strategies | +| Section 11 (Deployment) | specification.md:12, specification.md:18 | FR-013, FR-014, NFR-201, NFR-203 | Infrastructure requirements | + --- +## 2. Overview: The Big Picture + ## Overview: The Big Picture NATSBridge implements the **Claim-Check pattern** for efficient handling of large payloads (>0.5MB): @@ -718,13 +735,53 @@ log_trace(correlation_id, "Published to NATS") --- -## References +## 12. References -- [`docs/requirements.md`](./requirements.md) - Business requirements and user stories -- [`docs/spec.md`](./spec.md) - Technical specification and contracts -- [`docs/architecture.md`](./architecture.md) - System architecture diagrams -- [`src/NATSBridge.jl`](../src/NATSBridge.jl) - Ground truth implementation -- [`README.md`](../README.md) - Project overview +### 12.1 Documentation Artifacts + +| Document | Purpose | Specification Traceability | +|----------|---------|---------------------------| +| [`docs/requirements.md`](./requirements.md) | Business requirements and user stories | 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) | +| [`docs/ui-specification.md`](./ui-specification.md) | UI specification for client applications | UI components for data entry and display | +| [`docs/walkthrough.md`](./walkthrough.md) | End-to-end system flow | This document | +| [`docs/architecture.md`](./architecture.md) | System architecture diagrams | Component interaction and data flow | +| [`docs/validation.md`](./validation.md) | CI/CD validation rules | Contract testing and spec compliance | +| [`docs/runbook.md`](./runbook.md) | Operational runbook | Deployment, scaling, and troubleshooting | + +### 12.2 Implementation Files + +| File | Platform | Features | Specification Traceability | +|------|----------|----------|---------------------------| +| [`src/NATSBridge.jl`](../src/NATSBridge.jl) | Julia | Full feature set, Arrow IPC, multiple dispatch | specification.md:2-19 (all sections) | +| [`src/natsbridge_ssr.js`](../src/natsbridge_ssr.js) | Node.js | Arrow IPC, async/await | specification.md:2-19 (all sections) | +| [`src/natsbridge_csr.js`](../src/natsbridge_csr.js) | Browser | JSON table only, WebSocket NATS | specification.md:2-19 (all sections) | +| [`src/natsbridge.py`](../src/natsbridge.py) | Python | Arrow IPC, async/await | specification.md:2-19 (all sections) | +| [`src/natsbridge_mpy.py`](../src/natsbridge_mpy.py) | MicroPython | Limited to direct transport | specification.md:2-19 (all sections) | + +--- + +## 13. Change Log + +| Date | Version | Changes | Specification Reference | +|------|---------|---------|------------------------| +| 2026-03-23 | 1.0.0 | Updated to ASG Framework walkthrough guidelines | All sections | +| 2026-03-13 | 1.0.0 | Initial walkthrough documentation | specification.md:2-19 (all sections) | + +--- + +## 14. 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? | ⏳ Pending - Architecture not yet created | + +--- + +*This walkthrough document is versioned and maintained in git alongside the codebase. All implementations must adhere to this documentation.* ---