1 files changed, 214 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7066826
--- /dev/null
+++ b/README.md
@@ -0,0 +1,214 @@
+# ggj26-comp
+
+Extracted components from ggj26: build system, logging, and hub-and-spoke networking.
+
+## Components
+
+### Build System
+Makefile-based build system for MoonScript/Lua projects:
+- Compiles `.moon` files to `.lua`
+- Embeds JavaScript files with jshint validation
+- Runs tests with busted
+
+**Usage:**
+```bash
+make          # Build all sources
+make test     # Run tests
+make clean    # Clean build artifacts
+```
+
+### Logging Utility
+`src/log.moon` - Singleton logger with level-based and tag-based filtering.
+
+**Features:**
+- Log levels: debug, info, warn, error, panic
+- Tag-based filtering for organizing logs
+- Observer pattern for real-time monitoring
+- Message stream with time tracking
+
+**Usage:**
+```lua
+log = require "log"
+
+-- Log with level and tags
+log.info("User connected", {"network", "auth"})
+log.error("Connection failed", {"network"})
+
+-- Filter by level
+log.of_level("error", function(msg)
+    print(msg.message)
+end)
+
+-- Filter by tags
+log.of_tags({"network"}, function(msg)
+    print(msg.message)
+end)
+
+-- Listen to all messages
+log.listen(function(msg)
+    if msg.level == "panic" then
+        -- handle critical error
+    end
+end)
+```
+
+### Networking - Hub and Spoke Model
+
+#### Core (`src/net.moon`)
+Low-level WebRTC peer connection abstraction using PeerJS:
+- Peer creation and connection management
+- Message validation and routing
+- JavaScript bridge for browser integration
+
+#### Hub (`src/hub.moon`)
+Server-side hub that manages client connections:
+- Maintains registry of connected clients
+- Routes messages between clients (unicast, multicast, broadcast)
+- Connection/disconnection event handling
+
+**Usage:**
+```lua
+Hub = require("hub").Hub
+hub = Hub()
+hub:initialize()
+
+-- Get hub ID to share with clients
+hub_id = hub:get_peer_id()
+
+-- Listen for client events
+hub:on_connect(function(client_id)
+    print("Client connected:", client_id)
+end)
+
+hub:on_disconnect(function(client_id)
+    print("Client disconnected:", client_id)
+end)
+
+-- Update loop
+function love.update(dt)
+    hub:pump()
+end
+```
+
+#### Client (`src/client.moon`)
+Client-side with router registration system:
+- Connect to hub
+- Register message handlers (routers) by message type
+- Send messages to specific clients or broadcast
+
+**Usage:**
+```lua
+Client = require("client").Client
+client = Client("player1")
+
+-- Connect to hub
+client:connect_to_hub(hub_id)
+
+-- Register router for message type
+client:register_router("chat", function(from_id, data)
+    print("Chat from", from_id, ":", data.message)
+end)
+
+client:register_router("game_state", function(from_id, data)
+    -- handle game state update
+end)
+
+-- Send messages
+client:send_to(other_client_id, "chat", {message = "Hello!"})
+client:broadcast("game_state", {position = {x=10, y=20}})
+
+-- Update loop
+function love.update(dt)
+    client:pump()
+end
+```
+
+#### Testing Utilities (`src/channel.moon`)
+Channel abstractions for testing:
+- `SimpleChannel` - Basic in-memory channel
+- `FaultyChannel` - Simulates network latency and packet loss
+
+### Utility Functions (`src/util.lua`)
+Helper functions including:
+- `typecheck(tbl, ...)` - Validate table fields and types
+- `peer_to_code(str)` / `code_to_peer(str)` - Convert peer IDs to shareable codes
+
+## Architecture
+
+### Hub-and-Spoke Networking
+
+```
+        [Client A]
+            |
+            v
+    [Hub] ←-→ [Client B]
+            |
+            v
+        [Client C]
+```
+
+- **Hub**: Single peer that accepts all client connections
+- **Clients**: Connect to hub, register message handlers (routers)
+- **Message Flow**: Client → Hub → Target Client(s)
+- **Routing**: Hub handles unicast, multicast, and broadcast
+
+This replaces the previous RAFT-based peer-to-peer model with a simpler, centralized approach suitable for game lobbies and small multiplayer sessions.
+
+## Requirements
+
+- MoonScript compiler (`moonc`)
+- Lua
+- Busted (for unit testing)
+- Node.js/npm (for jshint)
+- Python 3.8+ (for integration testing)
+- Chrome browser (for Selenium tests)
+
+## Installation
+
+```bash
+# Install Node.js dependencies
+npm install
+
+# Install Python test dependencies (for integration testing)
+pip install -r requirements-test.txt
+```
+
+## Testing
+
+### Run All Tests
+Run both unit tests and integration tests:
+```bash
+make test1
+```
+
+### Unit Tests (Lua/Busted)
+Run Lua unit tests with busted:
+```bash
+make test
+```
+
+### Integration Tests (Selenium)
+Run browser-based integration tests:
+
+```bash
+# Using Make
+make test-integration                # Run with visible browser
+make test-integration-headless       # Run in headless mode
+```
+
+Or use the PowerShell script:
+```powershell
+.\run-integration-tests.ps1           # Run all tests
+.\run-integration-tests.ps1 -Headless # Headless mode
+.\run-integration-tests.ps1 -Smoke    # Smoke tests only
+.\run-integration-tests.ps1 -UI       # UI interaction tests
+```
+
+Or use pytest directly:
+```bash
+pytest                    # Run all integration tests
+pytest -m smoke           # Run smoke tests only
+pytest -v                 # Verbose output
+```
+
+See `tests/integration/README.md` for more details on integration testing.