<p align="center">
  <img src="assets/banner.png" alt="Mission Control Dashboard" width="100%" />
</p>

# Mission Control Dashboard

A learning project that teaches three real-time data transport patterns by
building a live asset tracking dashboard from scratch.

| Pattern                | Data Source     | What You See                      |
|------------------------|-----------------|-----------------------------------|
| **Polling**            | OpenSky Network | Aircraft updating every 10s       |
| **WebSocket**          | Custom VPS      | Drones and vehicles streaming 1s  |
| **Server-Sent Events** | MBTA API        | Boston buses pushing live updates |

By the end, all three patterns feed the same map — you understand the
trade-offs viscerally, not just theoretically.

## Tech Stack

- [TanStack Start](https://tanstack.com/start/latest) — file-based routing and server functions
- [XState](https://stately.ai/docs/xstate) — state machines for connection lifecycles
- [Leaflet](https://leafletjs.com/) + react-leaflet — interactive mapping
- Node.js + ws — WebSocket server (deployed on VPS)
- EventSource — browser-native SSE

## Getting Started

```bash
npx @tanstack/cli@latest create mission-control
cd mission-control
npm install leaflet react-leaflet xstate @xstate/react
npm install -D @types/leaflet
npm run dev
```

## Documentation

All docs live in `doc/` and follow the [Diataxis framework](https://diataxis.fr/):

| Type            | File                                                     | Purpose                         |
|-----------------|----------------------------------------------------------|---------------------------------|
| **Tutorial**    | `doc/tutorials/tutorial_mission_control_dashboard.org`   | Step-by-step guided build       |
| **Explanation** | `doc/explanation/explanation_realtime_data_patterns.org` | Polling vs WS vs SSE trade-offs |
| **How-to**      | `doc/howto/howto_connect_opensky.org`                    | Connect to OpenSky Network      |
| **How-to**      | `doc/howto/howto_websocket_server.org`                   | Deploy the WebSocket server     |
| **How-to**      | `doc/howto/howto_consume_sse_react.org`                  | Consume SSE with XState         |
| **Reference**   | `doc/reference/ref_api_contracts.org`                    | API field shapes                |

Start with the tutorial. Read the explanation when you want to go deeper. Check
the reference when you need exact details.

## License

[GPL-3.0](LICENSE)

What you can do:

  - Use the code for any purpose
  - Read and study the source code
  - Modify the code and make derivative works
  - Distribute copies (free or for a fee)

  What you MUST do (the copyleft obligation)

  - Share source code — if you distribute the software (compiled or modified),
    you must make the full source available under GPL v3
  - Keep the license — derivative works must also be GPL v3. You can't take your
    code and relicense it as proprietary
  - Mark changes — modified versions must be clearly noted as changed
  - Include the license text — every copy must include the GPL v3

  What you CANNOT do

  - Make it proprietary — no one can take this code and close-source it
  - Add restrictions — no additional terms that limit the freedoms GPL grants
  - Patent-lock it — contributors grant patent rights; no one can sue users for
    patent infringement on their contributions

  What it does NOT cover

  - No warranty — the software is provided "as is"
  - No liability — I'm not responsible for damages from its use
  - Network use — if you run it on a server without distributing it, You
    don't have to share source (that's AGPL, not GPL)