ARCHITECTURE.md

# Architecture Notes

## Long-Poll Pattern (ESP32 ↔ Server)

The ESP32 polls `GET /api/elevator/command` when IDLE. Instead of returning immediately with "no command", the server *holds* the HTTP connection open for up to 10 seconds using `asyncio.wait_for`:

```
ESP32                          Server
  |---GET /api/elevator/command-->|
  |                               | await event.wait() (up to 10s)
  |                               |
  |   (dashboard sends POST)      |
  |                               | event.set() → command available
  |<------{"cmd":"CALL_3"}---------| returns immediately
  |                               |
  |---GET /api/elevator/command-->| (next cycle after move completes)
  |                               | no command → timeout after 10s
  |<------{"cmd":"NONE"}-----------| returns after 10s
```

**Why this matters:** The naive approach polls every 500 ms — 120 requests/minute. Long-poll reduces this to ~6 requests/minute (one per timeout cycle), and delivers commands with near-zero latency when they do arrive.

**Implementation detail:** A single `asyncio.Event` guards a single command slot. After the ESP32 reads the command, both the slot and the Event are cleared so the next poll cycle starts clean. The ESP32 sets `http.setTimeout(15000)` to ensure the socket stays open past the 10-second server hold.

## SSE Pattern (Server → Dashboard)

The dashboard opens one persistent HTTP connection to `GET /api/events`. The server keeps this connection alive and pushes JSON-encoded events whenever elevator or robot state changes:

```
Browser                          Server
  |---GET /api/events------------>|
  |                               | registers asyncio.Queue
  |<--data:{"type":"elevator"...}-| on ESP32 POST /status
  |<--data:{"type":"robot"...}----| on Jetson POST /status
  |                               |
  | (client disconnects)          |
  |                               | queue removed from set (finally block)
```

**Why this matters:** Polling every 500 ms from the browser creates 120 requests/minute regardless of whether anything changed. SSE pushes updates only when state changes, with zero polling overhead and no perceptible latency.

**Implementation detail:** Each connected browser gets its own `asyncio.Queue`. The `broadcast()` function in `state.py` pushes a copy of every state change to every registered queue. When the browser disconnects (tab closed, network drop), the `finally` block in the async generator removes the queue from the set, preventing memory leaks.

## Component Interaction Summary

```
[ESP32]                [Jetson / ROS2]         [Browser]
   |                         |                     |
   |--POST /api/elevator/status-->            SSE <--|
   |<--GET /api/elevator/command-- (long-poll)       |
   |                         |--POST /api/robot/status-->
   |                         |<--GET /api/robot/goal-- (long-poll)
   |                                    POST /api/robot/goal <--|
   |<-- (elevator_cmd_event set by robot/goal handler)          |
```

`POST /api/robot/goal` is the single mission-dispatch entry point. It sets both the robot nav goal and the elevator call command in one atomic operation, ensuring the elevator is already summoned when the robot arrives.