From bf603c3314c5d74dcedfe6fcc504d9d8abfb0a86 Mon Sep 17 00:00:00 2001 From: Cameron Bielstein Date: Sun, 8 Oct 2023 21:04:08 -0700 Subject: [PATCH 1/9] Add text descriptions of diagrams I am going to add --- README.md | 39 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index cdf7743..bb4407e 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,46 @@ # AprsWeather -Weather maps backed by data from the Automatic Position Reporting System (APRS). +Weather maps backed by data from the Automatic Packet Reporting System (APRS). Deployed at: [hamwx.bielstein.dev](https://hamwx.bielstein.dev) +## Diagrams + +As the [Automatic Packet Reporting System](http://aprs.org/) and its component +[Automatic Packet Reporting System - Internet Service](https://aprs-is.net/) may not be familiar to +all who wish to work on this project, I've included a few diagrams on the architecture of this app, +how it relates to existing APRS infrastructure, and how data will typically flow through the full +system. + +### Architecture + +This diagram lays out the following pieces: + +1. AprsWeather frontend (WebAssembly in the browser for visualization) +2. AprsWeather backend (web server receiving and storing APRS packets from the APRS-IS and serving to frontend via a RESTful API) +3. APRS-IS servers streaming data via TCP +4. APRS iGate radio stations receiving and decoding packets from radio transmissions + +```mermaid +``` + +### Data Flow Example + +This diagram lays out a a flow for a weather report to move through the APRS, APRS-IS, and AprsWeather +systems from the weather station to the end user. +Steps are: + +1. A weather station takes measurements +2. A radio transmitter encodes those measurements in an APRS data packet and transmits the packet over the air +3. An APRS iGate station receives the packet via antenna and receiver then decodes and forwards to the APRS-IS servers +4. APRS-IS server infrastructure forward messages through network +5. APRS-IS servers forward message to subscribed servers (based on [filters](https://aprs-is.net/javAPRSFilter.aspx)) via TCP connection +6. AprsWeather backend receives packet via TCP, decodes, and stores +7. AprsWeather frontend requests reports via REST API from backend and displays to user + +```mermaid +``` + ## Running Locally Before running, you'll have to set a value for the `APRS_IS_CALLSIGN` environment variable. From cce9e41ec64155a294e3b2d2a3589a9bf240ebb4 Mon Sep 17 00:00:00 2001 From: Cameron Bielstein Date: Mon, 9 Oct 2023 20:49:34 -0700 Subject: [PATCH 2/9] First diagram of system context. --- README.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/README.md b/README.md index bb4407e..2c0d1cd 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,34 @@ This diagram lays out the following pieces: 4. APRS iGate radio stations receiving and decoding packets from radio transmissions ```mermaid +C4Context + title System architecture diagram for AprsWeather and APRS + + Person(webUser, "AprsWeather User", "Someone Checking the AprsWeather web app for nearby weather reports") + + System_Boundary(aprsWeather, "AprsWeather") { + System(aprsWeatherFrontend, "AprsWeather frontend", "WebAssembly UI") + System(aprsWeatherBackend, "AprsWeather backend", ".NET Server Process") + + Rel(aprsWeatherFrontend, aprsWeatherBackend, "calls") + } + + Rel(webUser, aprsWeatherFrontend, "uses") + + System_Boundary(aprsIs, "APRS-IS", "Internet Service for APRS") { + System(aprsServer, "APRS-IS Server", "One of many APRS-IS servers") + System(iGate, "iGate", "Internet Gateway Service") + + Rel(iGate, aprsServer, "forwards packet") + } + + Rel(aprsServer, aprsWeatherBackend, "forwards packet") + + System_Boundary(aprsRf, "APRS Radio Network", "The network of radio transceivers communicating via radio frequency transmissions") { + System(transmitter, "Radio Transmitter", "Origin of a report") + } + + Rel(transmitter, iGate, "RF transmission") ``` ### Data Flow Example From 02553810b9ca3db60d1c76a8a3e3868df9285b6b Mon Sep 17 00:00:00 2001 From: Cameron Bielstein Date: Mon, 9 Oct 2023 21:32:48 -0700 Subject: [PATCH 3/9] First pass at data flowchart --- README.md | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2c0d1cd..f40f094 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ C4Context Rel(webUser, aprsWeatherFrontend, "uses") System_Boundary(aprsIs, "APRS-IS", "Internet Service for APRS") { - System(aprsServer, "APRS-IS Server", "One of many APRS-IS servers") + System(aprsServer, "APRS-IS Server Network", "Network of many APRS-IS servers") System(iGate, "iGate", "Internet Gateway Service") Rel(iGate, aprsServer, "forwards packet") @@ -67,6 +67,31 @@ Steps are: 7. AprsWeather frontend requests reports via REST API from backend and displays to user ```mermaid +flowchart TD + + station["Weather Station"] + digi["APRS Digital Repeater (digipeater)"] + radio["Radio Transmitter"] + igate["APRS Internet Gateway (iGate)"] + aprsIs((("APRS Servers"))) + backend["AprsWeather Backend: AprsIsClient"] + db[("AprsWeather Backend: In-Memory Storage")] + api{{"AprsWeather Backend: API Query"}} + frontend[/"AprsWeather Frontend"/] + user["user"] + + station-- report measurements (physical connection) ---radio + radio-. "transmit packet (radio freq.)" .->digi + radio-. "transmit packet (radio freq.)" .->igate + digi-. "repeat packet (radio freq.)" .->igate + + igate-- forward packet (TCP) -->aprsIs + aprsIs-- forward packet to subscribers (TCP) -->backend + + backend-- save packet ---db + db-- retrieve packet ---api + api-. fetch data (REST) .->frontend + frontend-. "view reports!" .-user ``` ## Running Locally From ec98fa94382557f985e47dc7bcd40e7489e2c986 Mon Sep 17 00:00:00 2001 From: Cameron Bielstein Date: Mon, 9 Oct 2023 21:40:10 -0700 Subject: [PATCH 4/9] Switch to define graph instead of flowchart for github --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f40f094..ed9387c 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ Steps are: 7. AprsWeather frontend requests reports via REST API from backend and displays to user ```mermaid -flowchart TD +graph TD station["Weather Station"] digi["APRS Digital Repeater (digipeater)"] From 094115baae7cbbb849e457173f49684d1fe19a79 Mon Sep 17 00:00:00 2001 From: Cameron Bielstein Date: Mon, 9 Oct 2023 21:41:21 -0700 Subject: [PATCH 5/9] Attempt to use semi-colons for github --- README.md | 49 ++++++++++++++++++++++++------------------------- 1 file changed, 24 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index ed9387c..8d42c64 100644 --- a/README.md +++ b/README.md @@ -67,31 +67,30 @@ Steps are: 7. AprsWeather frontend requests reports via REST API from backend and displays to user ```mermaid -graph TD - - station["Weather Station"] - digi["APRS Digital Repeater (digipeater)"] - radio["Radio Transmitter"] - igate["APRS Internet Gateway (iGate)"] - aprsIs((("APRS Servers"))) - backend["AprsWeather Backend: AprsIsClient"] - db[("AprsWeather Backend: In-Memory Storage")] - api{{"AprsWeather Backend: API Query"}} - frontend[/"AprsWeather Frontend"/] - user["user"] - - station-- report measurements (physical connection) ---radio - radio-. "transmit packet (radio freq.)" .->digi - radio-. "transmit packet (radio freq.)" .->igate - digi-. "repeat packet (radio freq.)" .->igate - - igate-- forward packet (TCP) -->aprsIs - aprsIs-- forward packet to subscribers (TCP) -->backend - - backend-- save packet ---db - db-- retrieve packet ---api - api-. fetch data (REST) .->frontend - frontend-. "view reports!" .-user +graph TD; + station["Weather Station"]; + digi["APRS Digital Repeater (digipeater)"]; + radio["Radio Transmitter"]; + igate["APRS Internet Gateway (iGate)"]; + aprsIs((("APRS Servers"))); + backend["AprsWeather Backend: AprsIsClient"]; + db[("AprsWeather Backend: In-Memory Storage")]; + api{{"AprsWeather Backend: API Query"}}; + frontend[/"AprsWeather Frontend"/]; + user["user"]; + + station-- report measurements (physical connection) ---radio; + radio-. "transmit packet (radio freq.)" .->digi; + radio-. "transmit packet (radio freq.)" .->igate; + digi-. "repeat packet (radio freq.)" .->igate; + + igate-- forward packet (TCP) -->aprsIs; + aprsIs-- forward packet to subscribers (TCP) -->backend; + + backend-- save packet ---db; + db-- retrieve packet ---api; + api-. fetch data (REST) .->frontend; + frontend-. "view reports!" .-user; ``` ## Running Locally From c66ed15f1af3968795e9c80b754cde987dd157f0 Mon Sep 17 00:00:00 2001 From: Cameron Bielstein Date: Mon, 9 Oct 2023 21:44:21 -0700 Subject: [PATCH 6/9] Revert "Attempt to use semi-colons for github" This reverts commit 094115baae7cbbb849e457173f49684d1fe19a79. --- README.md | 49 +++++++++++++++++++++++++------------------------ 1 file changed, 25 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 8d42c64..ed9387c 100644 --- a/README.md +++ b/README.md @@ -67,30 +67,31 @@ Steps are: 7. AprsWeather frontend requests reports via REST API from backend and displays to user ```mermaid -graph TD; - station["Weather Station"]; - digi["APRS Digital Repeater (digipeater)"]; - radio["Radio Transmitter"]; - igate["APRS Internet Gateway (iGate)"]; - aprsIs((("APRS Servers"))); - backend["AprsWeather Backend: AprsIsClient"]; - db[("AprsWeather Backend: In-Memory Storage")]; - api{{"AprsWeather Backend: API Query"}}; - frontend[/"AprsWeather Frontend"/]; - user["user"]; - - station-- report measurements (physical connection) ---radio; - radio-. "transmit packet (radio freq.)" .->digi; - radio-. "transmit packet (radio freq.)" .->igate; - digi-. "repeat packet (radio freq.)" .->igate; - - igate-- forward packet (TCP) -->aprsIs; - aprsIs-- forward packet to subscribers (TCP) -->backend; - - backend-- save packet ---db; - db-- retrieve packet ---api; - api-. fetch data (REST) .->frontend; - frontend-. "view reports!" .-user; +graph TD + + station["Weather Station"] + digi["APRS Digital Repeater (digipeater)"] + radio["Radio Transmitter"] + igate["APRS Internet Gateway (iGate)"] + aprsIs((("APRS Servers"))) + backend["AprsWeather Backend: AprsIsClient"] + db[("AprsWeather Backend: In-Memory Storage")] + api{{"AprsWeather Backend: API Query"}} + frontend[/"AprsWeather Frontend"/] + user["user"] + + station-- report measurements (physical connection) ---radio + radio-. "transmit packet (radio freq.)" .->digi + radio-. "transmit packet (radio freq.)" .->igate + digi-. "repeat packet (radio freq.)" .->igate + + igate-- forward packet (TCP) -->aprsIs + aprsIs-- forward packet to subscribers (TCP) -->backend + + backend-- save packet ---db + db-- retrieve packet ---api + api-. fetch data (REST) .->frontend + frontend-. "view reports!" .-user ``` ## Running Locally From 3de367d37a326aff584adf76d04612c46b94441d Mon Sep 17 00:00:00 2001 From: Cameron Bielstein Date: Mon, 9 Oct 2023 21:44:32 -0700 Subject: [PATCH 7/9] Revert "Switch to define graph instead of flowchart for github" This reverts commit ec98fa94382557f985e47dc7bcd40e7489e2c986. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ed9387c..f40f094 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ Steps are: 7. AprsWeather frontend requests reports via REST API from backend and displays to user ```mermaid -graph TD +flowchart TD station["Weather Station"] digi["APRS Digital Repeater (digipeater)"] From 6d90fba21c80574064e70be2ebe898ddb6838527 Mon Sep 17 00:00:00 2001 From: Cameron Bielstein Date: Mon, 9 Oct 2023 21:52:36 -0700 Subject: [PATCH 8/9] Add subgraphs to flowchart to delinate systems --- README.md | 30 +++++++++++++++++++++--------- 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index f40f094..1dcbe19 100644 --- a/README.md +++ b/README.md @@ -69,15 +69,27 @@ Steps are: ```mermaid flowchart TD - station["Weather Station"] - digi["APRS Digital Repeater (digipeater)"] - radio["Radio Transmitter"] - igate["APRS Internet Gateway (iGate)"] - aprsIs((("APRS Servers"))) - backend["AprsWeather Backend: AprsIsClient"] - db[("AprsWeather Backend: In-Memory Storage")] - api{{"AprsWeather Backend: API Query"}} - frontend[/"AprsWeather Frontend"/] + subgraph weatherStation [Weather Station] + station["Weather Station"] + radio["Radio Transmitter"] + end + + subgraph aprsPhysical [APRS Physical Network] + digi["APRS Digital Repeater (digipeater)"] + igate["APRS Internet Gateway (iGate)"] + end + + subgraph aprsIsSystem [APRS Internet System] + aprsIs((("APRS Servers"))) + end + + subgraph aprsWeather [AprsWeather] + backend["AprsWeather Backend: AprsIsClient"] + db[("AprsWeather Backend: In-Memory Storage")] + api{{"AprsWeather Backend: API Query"}} + frontend[/"AprsWeather Frontend"/] + end + user["user"] station-- report measurements (physical connection) ---radio From 6ccaf03c72f8242be12d9ee0158f4ad134b74c5c Mon Sep 17 00:00:00 2001 From: Cameron Bielstein Date: Mon, 9 Oct 2023 21:57:40 -0700 Subject: [PATCH 9/9] Add note about extensions. --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 1dcbe19..6e611d2 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,8 @@ all who wish to work on this project, I've included a few diagrams on the archit how it relates to existing APRS infrastructure, and how data will typically flow through the full system. +The following diagrams are written in [Mermaid](https://mermaid.js.org) and may require an [editor extension](https://mermaid.js.org/ecosystem/integrations-community.html#editor-plugins) to render properly in your dev environment. + ### Architecture This diagram lays out the following pieces: