1  <p align="center">
 2    <img src="assets/banner.png" alt="Mission Control Dashboard" width="100%" />
 3  </p>
 4  
 5  # Mission Control Dashboard
 6  
 7  A learning project that teaches three real-time data transport patterns by
 8  building a live asset tracking dashboard from scratch.
 9  
10  | Pattern                | Data Source     | What You See                      |
11  |------------------------|-----------------|-----------------------------------|
12  | **Polling**            | OpenSky Network | Aircraft updating every 10s       |
13  | **WebSocket**          | Custom VPS      | Drones and vehicles streaming 1s  |
14  | **Server-Sent Events** | MBTA API        | Boston buses pushing live updates |
15  
16  By the end, all three patterns feed the same map — you understand the
17  trade-offs viscerally, not just theoretically.
18  
19  ## Tech Stack
20  
21  - [TanStack Start](https://tanstack.com/start/latest) — file-based routing and server functions
22  - [XState](https://stately.ai/docs/xstate) — state machines for connection lifecycles
23  - [Leaflet](https://leafletjs.com/) + react-leaflet — interactive mapping
24  - Node.js + ws — WebSocket server (deployed on VPS)
25  - EventSource — browser-native SSE
26  
27  ## Getting Started
28  
29  ```bash
30  npx @tanstack/cli@latest create mission-control
31  cd mission-control
32  npm install leaflet react-leaflet xstate @xstate/react
33  npm install -D @types/leaflet
34  npm run dev
35  ```
36  
37  ## Documentation
38  
39  All docs live in `doc/` and follow the [Diataxis framework](https://diataxis.fr/):
40  
41  | Type            | File                                                     | Purpose                         |
42  |-----------------|----------------------------------------------------------|---------------------------------|
43  | **Tutorial**    | `doc/tutorials/tutorial_mission_control_dashboard.org`   | Step-by-step guided build       |
44  | **Explanation** | `doc/explanation/explanation_realtime_data_patterns.org` | Polling vs WS vs SSE trade-offs |
45  | **How-to**      | `doc/howto/howto_connect_opensky.org`                    | Connect to OpenSky Network      |
46  | **How-to**      | `doc/howto/howto_websocket_server.org`                   | Deploy the WebSocket server     |
47  | **How-to**      | `doc/howto/howto_consume_sse_react.org`                  | Consume SSE with XState         |
48  | **Reference**   | `doc/reference/ref_api_contracts.org`                    | API field shapes                |
49  
50  Start with the tutorial. Read the explanation when you want to go deeper. Check
51  the reference when you need exact details.
52  
53  ## License
54  
55  [GPL-3.0](LICENSE)
56  
57  What you can do:
58  
59    - Use the code for any purpose
60    - Read and study the source code
61    - Modify the code and make derivative works
62    - Distribute copies (free or for a fee)
63  
64    What you MUST do (the copyleft obligation)
65  
66    - Share source code — if you distribute the software (compiled or modified),
67      you must make the full source available under GPL v3
68    - Keep the license — derivative works must also be GPL v3. You can't take your
69      code and relicense it as proprietary
70    - Mark changes — modified versions must be clearly noted as changed
71    - Include the license text — every copy must include the GPL v3
72  
73    What you CANNOT do
74  
75    - Make it proprietary — no one can take this code and close-source it
76    - Add restrictions — no additional terms that limit the freedoms GPL grants
77    - Patent-lock it — contributors grant patent rights; no one can sue users for
78      patent infringement on their contributions
79  
80    What it does NOT cover
81  
82    - No warranty — the software is provided "as is"
83    - No liability — I'm not responsible for damages from its use
84    - Network use — if you run it on a server without distributing it, You
85      don't have to share source (that's AGPL, not GPL)