# System Architecture Diagram

## High-Level Overview

```
                         ╔═══════════════════════════╗
                         ║    YOUR COMPUTER          ║
                         ║                           ║
    ┌────────────────────║──────────────────────────║────────────────┐
    │                    ║                           ║                │
    │  ┏━━━━━━━━━━━━━━┓  ║  ┏━━━━━━━━━━━━━━━━━━━┓  ║  ┏━━━━━━━━━━┓ │
    │  ┃   Browser    ┃  ║  ┃   Node.js Server  ┃  ║  ┃ Minecraft┃ │
    │  ┃              ┃  ║  ┃                   ┃  ║  ┃          ┃ │
    │  ┃  React App   ┃◄─╫─►┃  Express + WS     ┃◄─╫─►┃ Bridge   ┃ │
    │  ┃              ┃  ║  ┃                   ┃  ║  ┃ Computer ┃ │
    │  ┃ :3000        ┃  ║  ┃  :3001 / :3002    ┃  ║  ┃          ┃ │
    │  ┗━━━━━━━━━━━━━━┛  ║  ┗━━━━━━━━━━━━━━━━━━━┛  ║  ┗━━━━━━━━━━┛ │
    │                    ║                           ║       │        │
    └────────────────────║──────────────────────────║───────┼────────┘
                         ╚═══════════════════════════╝       │
                                                             │ Modem
                                                             │ Wireless
                                                             ↓
                                                    ┏━━━━━━━━━━━━━━┓
                                                    ┃   Turtle 1   ┃
                                                    ┃   Turtle 2   ┃
                                                    ┃   Turtle N   ┃
                                                    ┗━━━━━━━━━━━━━━┛
```

## Communication Flow

### Status Updates (Turtle → Web)

```
Turtle              Bridge              Server              Web Client
  │                   │                   │                      │
  │ Status Broadcast  │                   │                      │
  ├──────modem───────>│                   │                      │
  │  (channel 102)    │                   │                      │
  │                   │ HTTP POST         │                      │
  │                   ├───────────────────>│                      │
  │                   │ /api/turtle/update│                      │
  │                   │                   │ WebSocket Broadcast  │
  │                   │                   ├─────────────────────>│
  │                   │                   │   turtle_update      │
  │                   │                   │                      │
  │                   │                   │                  ┌───┴───┐
  │                   │                   │                  │Update │
  │                   │                   │                  │3D Map │
  │                   │                   │                  └───────┘
```

### Commands (Web → Turtle)

```
Web Client          Server              Bridge              Turtle
  │                   │                   │                   │
  │ Click "Explore"   │                   │                   │
  ├─────WebSocket────>│                   │                   │
  │   command msg     │                   │                   │
  │                   │ Queue Command     │                   │
  │                   ├──(in memory)      │                   │
  │                   │                   │                   │
  │                   │                   │ Poll for Commands │
  │                   │    HTTP GET       │                   │
  │                   │<──────────────────┤                   │
  │                   │/api/turtle/:id/.. │                   │
  │                   │                   │                   │
  │                   │   Return Commands │                   │
  │                   ├──────────────────>│                   │
  │                   │      JSON         │                   │
  │                   │                   │ Forward via Modem │
  │                   │                   ├──────────────────>│
  │                   │                   │  (channel 100)    │
  │                   │                   │                   │
  │                   │                   │               ┌───┴────┐
  │                   │                   │               │Execute │
  │                   │                   │               │Command │
  │                   │                   │               └────────┘
```

## Component Details

### React Frontend (Port 3000)

```
┌─────────────────────────────────────┐
│           App.jsx                   │
│  ┌───────────────────────────────┐  │
│  │  View Controls (Split/Map/..) │  │
│  └───────────────────────────────┘  │
│                                     │
│  ┌────────────┬──────────────────┐  │
│  │            │                  │  │
│  │  Control   │     Map3D.jsx   │  │
│  │  Panel     │                  │  │
│  │  .jsx      │  ┌────────────┐  │  │
│  │            │  │ Three.js   │  │  │
│  │  - Turtle  │  │ Canvas     │  │  │
│  │    Cards   │  │            │  │  │
│  │  - Details │  │ - Turtles  │  │  │
│  │  - Commands│  │ - Grid     │  │  │
│  │  - Manual  │  │ - Camera   │  │  │
│  │    Control │  │            │  │  │
│  │            │  └────────────┘  │  │
│  └────────────┴──────────────────┘  │
│                                     │
│  ┌───────────────────────────────┐  │
│  │     turtleStore.js            │  │
│  │  - WebSocket connection       │  │
│  │  - State management           │  │
│  │  - Command sending            │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘
```

### Node.js Server (Ports 3001, 3002)

```
┌─────────────────────────────────────┐
│         server.js                   │
│                                     │
│  ┌───────────────────────────────┐  │
│  │   Express HTTP Server         │  │
│  │   Port: 3001                  │  │
│  │                               │  │
│  │  POST /api/turtle/update      │  │
│  │  GET  /api/turtle/:id/commands│  │
│  │  POST /api/turtle/:id/command │  │
│  │  GET  /api/turtles            │  │
│  └───────────────────────────────┘  │
│                                     │
│  ┌───────────────────────────────┐  │
│  │   WebSocket Server            │  │
│  │   Port: 3002                  │  │
│  │                               │  │
│  │  - Broadcast turtle updates   │  │
│  │  - Receive commands           │  │
│  │  - Track connected clients    │  │
│  └───────────────────────────────┘  │
│                                     │
│  ┌───────────────────────────────┐  │
│  │   In-Memory Data Store        │  │
│  │                               │  │
│  │  turtleData Map:              │  │
│  │    turtleID → state           │  │
│  │    - position                 │  │
│  │    - fuel                     │  │
│  │    - inventory                │  │
│  │    - pendingCommands[]        │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘
```

### Minecraft Components

```
┌─────────────────────────────────────┐
│      webbridge.lua                  │
│      (Bridge Computer)              │
│                                     │
│  ┌───────────────────────────────┐  │
│  │  Modem Listener               │  │
│  │  Channels: 101, 102           │  │
│  └───────────────────────────────┘  │
│                 ↕                   │
│  ┌───────────────────────────────┐  │
│  │  HTTP Client                  │  │
│  │  - POST status to server      │  │
│  │  - GET commands from server   │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘
             ↕ (modem)
┌─────────────────────────────────────┐
│         turtle.lua                  │
│         (Each Turtle)               │
│                                     │
│  ┌───────────────────────────────┐  │
│  │  Command Processor            │  │
│  │  Listen: channel 100          │  │
│  └───────────────────────────────┘  │
│                                     │
│  ┌───────────────────────────────┐  │
│  │  Status Broadcaster           │  │
│  │  Send: channel 102 (every 5s) │  │
│  └───────────────────────────────┘  │
│                                     │
│  ┌───────────────────────────────┐  │
│  │  Autonomous AI                │  │
│  │  - Exploration                │  │
│  │  - Mining                     │  │
│  │  - Pathfinding                │  │
│  │  - Fuel management            │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘
```

## Network Ports

```
Port 3000  →  React Dev Server (Vite)
Port 3001  →  Express HTTP API
Port 3002  →  WebSocket Server

Modem Channels:
  100  →  Commands to Turtles
  101  →  Responses from Turtles
  102  →  Status Updates
```

## Data Models

### Turtle State Object

```javascript
{
  turtleID: 123,
  mode: "mining",          // idle, exploring, mining, returning, manual
  position: {
    x: 100,
    y: 64,
    z: 200
  },
  homePosition: {
    x: 95,
    y: 64,
    z: 195
  },
  fuel: 5000,
  inventory: [
    { slot: 1, name: "minecraft:coal_ore", count: 32 },
    { slot: 2, name: "minecraft:iron_ore", count: 16 }
  ],
  lastUpdate: 1234567890,
  pendingCommands: [
    { command: "explore", param: null, timestamp: 1234567890 }
  ]
}
```

### Command Message

```javascript
{
  command: "explore",      // explore, mine, returnHome, stop, forward, etc.
  param: null,             // optional parameter
  target: 123              // turtle ID (for Lua) or turtleID (for web)
}
```

## Technology Stack Summary

```
┌─────────────────────────────────────┐
│  Presentation Layer                 │
│  - React 18                         │
│  - Three.js / React Three Fiber     │
│  - CSS3                             │
└─────────────────────────────────────┘
              ↕
┌─────────────────────────────────────┐
│  State Management                   │
│  - Zustand                          │
│  - WebSocket API                    │
└─────────────────────────────────────┘
              ↕
┌─────────────────────────────────────┐
│  Backend Services                   │
│  - Node.js                          │
│  - Express.js                       │
│  - ws (WebSocket library)           │
└─────────────────────────────────────┘
              ↕
┌─────────────────────────────────────┐
│  Game Integration                   │
│  - ComputerCraft Lua                │
│  - HTTP API                         │
│  - Modem Wireless                   │
└─────────────────────────────────────┘
```

---

This architecture provides:
- ✅ Real-time bidirectional communication
- ✅ Scalable to multiple turtles
- ✅ Web-based interface accessible from any device
- ✅ Backward compatible with existing Lua scripts
- ✅ Clean separation of concerns
- ✅ Easy to extend and modify