feat: Add comprehensive documentation for project architecture, troubleshooting, and setup
This commit is contained in:
MayaTheShy
291
ARCHITECTURE.md
Normal file
291
ARCHITECTURE.md
Normal file
@@ -0,0 +1,291 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user