Update README.md

2025-12-01 08:33:28 +00:00 · 2025-12-01 08:33:01 +00:00 · 2025-12-01 08:32:29 +00:00 · 2025-12-01 08:27:57 +00:00 · 2025-11-30 02:06:50 +05:30 · 2025-11-30 02:04:41 +05:30
1 changed files with 194 additions and 209 deletions
--- a/README.md
+++ b/README.md
@@ -1,287 +1,272 @@
-# ✅ Project Status Report
+# tic-tac-toe — Authoritative Multiplayer Game Server (Nakama + Go)
-## Multiplayer Tic-Tac-Toe Platform
+A production-grade, server-authoritative multiplayer backend built using **Nakama 3**, **Go plugins**, and **PostgreSQL**, deployed via **Drone CI/CD** and exposed securely through **Traefik**.
 **To:** CTO & Technical Interview Panel
 **Date:** November 28, 2025
 **Version:** v0.2.0
 ---
-## **1. Objective**
+## 🚀 Overview
-Design and implement a lightweight, scalable, server-authoritative multiplayer game system using **Nakama + Go plugins
+This repository contains a fully authoritative Tic-Tac-Toe backend built on **Nakama 3.21.0 ARM**, using a custom **Go plugin** to implement game logic, matchmaking, validation, leaderboards, and session management.
-**, supporting authentication, matchmaking, authoritative gameplay, leaderboards, and a functional UI — deployable to
+
-Google Cloud for demonstration.
+The server ensures:
 * **Zero client trust**
 * **Deterministic gameplay**
 * **Secure matchmaking**
 * **Validated moves**
 * **Authoritative outcomes**
 Designed for scalability, extensibility, and cloud deployment (GCP, AWS, or ARM homelab environments).
 ---
-## **2. Current Completion Summary**
+## ⭐ Key Features
-| Requirement                                  | Status                   |
+* **Authoritative Go match handler** (`tictactoe`)
-|----------------------------------------------|--------------------------|
+* Device-ID authentication + JWT session
-| Install Nakama + PostgreSQL                  | ✅ Completed              |
+* Matchmaking queue support
-| Custom Go server plugins                     | ✅ Completed              |
+* Deterministic game validation
-| Server-authoritative Tic-Tac-Toe             | ✅ Completed              |
+* Match lifecycle handling
-| Real-time WebSocket communication            | ✅ Completed              |
+* Disconnect handling & forfeit detection
-| Device-based authentication                  | ✅ Completed              |
+* Leaderboards creation + scoring
-| JWT-based session management                 | ✅ Completed              |
+* Production-grade CI/CD with Drone
-| Match creation & joining                     | ✅ Completed              |
+* Automated ARM Docker builds
-| **Matchmaking queue support**                | ✅ Completed              |
+* Full Traefik routing (HTTP + WebSocket)
-| **Game state validation & turn enforcement** | ✅ Completed              |
+* Compatible with x86/ARM/GCP
 | **Leaderboard system**                       | ✅ Completed              |
 | **UI Game Client**                           | 🟡 Partially Implemented |
 | Google Cloud deployment                      | 🟡 Not Started           |
 ✅ **Backend is fully authoritative and complete**
 🟡 **UI functional but missing polish, UX, and failure handling**
 ---
-## **3. Core Technical Architecture**
+## 🧩 Architecture
-* **Backend Framework:** Nakama 3.x
+### High-Level System Diagram
-* **Business Logic:** Custom Go runtime module
+
-* **Frontend:** React + Vite + Nakama JS
+```mermaid
-* **Database:** PostgreSQL 14
+flowchart LR
-* **Transport:** WebSockets (real-time)
+    UI[(React + Vite)] --> Traefik
-* **Authentication:** Device-ID based auth → JWT session returned
+    Traefik --> Nakama[Nakama Server]
-* **State Management:** Fully server-authoritative
+    Nakama --> Plugin[Go Plugin]
-* **Build & Deployment:** Docker-based
+    Nakama --> Postgres[(PostgreSQL)]
    Drone[Drone CI/CD] --> Registry[Private Docker Registry]
    Registry --> Nakama
 ```
 ---
-## **4. Authentication**
+## 🛠 Tech Stack
-### Backend
+**Backend**
-* Device authentication, auto-account creation
+* Nakama 3.21.0 ARM
-* JWT returned and used for RT connections
+* Go 1.21.6 (plugin ABI compatible)
 * PostgreSQL 16
 * Docker / multi-stage builds
 * Drone CI/CD
 * Traefik reverse proxy
-### UI
+**Cloud/Infra**
-* Generates a device UUID and authenticates via `client.authenticateDevice()`
+* GCP-ready
-* Stores and manages session state in React context
+* ARM homelab deployments
 * Private registry support
 ---
-## **5. Game Server Logic (Go)**
+## 📦 Repository Structure
-Significant enhancements made:
+```
-
+tic-tac-toe/
-### **✔ Initial State Broadcast**
+│── plugins/
-
+│    ├── main.go
-* When the second player joins, the server immediately sends the full authoritative state.
+│    ├── match.go
-
+│    └── matchmaking.go
-### **✔ Complete Turn + Move Validation**
+│
-
+│── Dockerfile
-Rejects:
+│── go.mod
-
+│── go.sum
-* out-of-bounds moves
+│── README.md
-* occupied cells
+```
 * wrong player's turn
 * invalid payloads
 ### **✔ Forfeit Handling**
 * When a user disconnects or leaves, match ends in `forfeit`
 * Final state broadcast to remaining player
 ### **✔ Authoritative State Updates**
 * Only broadcasts when state actually changes
 * Robust structured logging
 Result:
 **Absolute server authority, zero trust in client.**
 ---
-## **6. Real-Time Networking**
+## 🔌 Registered Server Components
-Communication validated end-to-end:
+### 📌 Match Handler
-* `match_create`
+Name: **`tictactoe`**
 * `match_join`
 * `matchmaker_add` / `matchmaker_matched`
 * `match_data_send` for moves (OpCode 1)
 * Server broadcasts state (OpCode 2)
-Python simulators and UI both confirm:
+Handles:
-* move ordering
+* Turn validation
-* correct enforcement of turn rules
+* State updates
-* correct state sync
+* Win/loss/draw
-* stable WebSocket behavior
+* Disconnect forfeit
 * Broadcasting authoritative state
 ### 📌 RPCs
 | RPC Name                | Purpose                                  |
 | ----------------------- | ---------------------------------------- |
 | **`leave_matchmaking`** | Allows clients to exit matchmaking queue |
 ### 📌 Matchmaker Hook
 | Hook                    | Purpose                                                   |
 | ----------------------- | --------------------------------------------------------- |
 | **`MatchmakerMatched`** | Validates matchmaker tickets and instantiates a new match |
 ---
-## **7. Matchmaking System (Go + UI)**
+## 🎮 Gameplay Protocol
-### **Backend (Go)**
+### OpCodes
-* Implements `MatchmakerMatched` hook
+| OpCode | Direction       | Meaning                       |
-* Ensures both players:
+| ------ | --------------- | ----------------------------- |
-
+| **1**  | Client → Server | Submit move `{x, y}`          |
-    * have valid `mode`
+| **2**  | Server → Client | Full authoritative game state |
    * match modes
    * exactly two players
 * Creates authoritative matches server-side
 * RPC `leave_matchmaking` added
 ### **UI**
 * Integrates matchmaking: mode selection → queue → ticket → matched → auto-join
 * Uses Nakama JS `socket.addMatchmaker()`
 **Status:** Fully functional end-to-end
 ---
-## **8. Leaderboard System (Go + UI)**
+## 🧠 Authoritative Flow Diagram
-### **Backend (Go)**
+```mermaid
 sequenceDiagram
    participant C1 as Client 1
    participant C2 as Client 2
    participant S as Nakama + Go Plugin
-* Leaderboard auto-created on startup
+    C1->>S: Matchmaker Join
-* On win:
+    C2->>S: Matchmaker Join
    S->>S: MatchmakerMatched()
    S-->>C1: Matched
    S-->>C2: Matched
-    * winner identified
+    C1->>S: OpCode 1 (Move)
-    * username resolved
+    S->>S: Validate Move
-    * score incremented (+1 win)
+    S-->>C1: OpCode 2 (Updated State)
-    * metadata logged
+    S-->>C2: OpCode 2 (Updated State)
-
+```
 ### **UI**
 * Implements leaderboard view using `client.listLeaderboardRecords()`
 * Read-only UI display works
 ### **Remaining**
 * UI sorting, layout, styling
 * No leaderboard write actions needed from UI
 ---
-## **9. UI Implementation Status (React + Vite)**
+## ⚙️ Build & Development
-### **What Is Implemented**
+### Build Go Plugin
- ✔ Authentication flow (device auth)
+```
- ✔ WebSocket session handling
+CGO_ENABLED=1 go build \
- ✔ Matchmaking (classic/blitz modes)
+    --trimpath \
- ✔ Automatic match join
+    --buildmode=plugin \
- ✔ Move sending (OpCode 1)
+    -o build/main.so \
- ✔ State updates (OpCode 2)
+    ./plugins
- ✔ Board rendering and interactive cells
+```
 - ✔ End-of-game messaging
 - ✔ Leaderboard display
-### **Partially Implemented**
+### Run Nakama Locally
- 🟡 Match mode UI selection wired but not visually emphasized
+```
- 🟡 Context handles all RT states but missing error handling
+nakama migrate up --database.address "$DB_ADDR"
-
+nakama \
-### **Not Implemented / Missing**
+  --database.address "$DB_ADDR" \
-
+  --socket.server_key="$SERVER_KEY"
- 🔴 Reconnect flow (UI does not recover session after WS drop)
+```
 - 🔴 No error UI for: matchmaking failure, move rejection, disconnects
 - 🔴 No UI for leaving match or returning to lobby
 - 🔴 No rematch button / flow
 - 🔴 No transitions, animations, or mobile layout
 - 🔴 No global app shell (Routing, Home Screen, etc.)
 **Summary:** UI is *functional* and capable of playing full authoritative games, but lacks UX polish and failure
 handling.
 ---
-## **10. Testing & Validation**
+## 🐳 Docker Build (Multi-Stage)
-### Backend
+```dockerfile
 FROM --platform=linux/arm64 golang:1.21.6 AS plugin_builder
-* Extensive scenario tests: draws, wins, illegal moves, disconnects
+RUN go mod download
-* Matchmaking simulation across N clients
+COPY . .
 RUN CGO_ENABLED=1 go build --buildmode=plugin -o build/main.so ./plugins
-### UI
+FROM heroiclabs/nakama:3.21.0-arm
-
+COPY --from=plugin_builder /workspace/build/main.so /nakama/data/modules/main.so
-* Verified:
+ENTRYPOINT ...
-
+```
    * matchmaking
    * game correctness
    * leaderboard retrieval
    * state sync
 * Missing:
    * stress testing
    * reconnection scenarios
    * mobile layout testing
 ---
-## **11. Google Cloud Deployment**
+## 🤖 CI/CD — Drone Pipeline
-Planned architecture remains:
+Drone performs:
-| Component     | GCP Service                   |
+1. Fetch latest Git tag
-|---------------|-------------------------------|
+2. Check if Docker image already exists
-| Nakama server | Compute Engine VM (Docker)    |
+3. Build Nakama + plugin
-| PostgreSQL    | Cloud SQL (shared tier)       |
+4. Push to private registry
-| Game UI       | Cloud Run or Firebase Hosting |
+5. Stop old container
-| Networking    | Static IP + HTTPS             |
+6. Deploy new Nakama server automatically
 | Auth secrets  | Secret Manager (optional)     |
-Estimated setup time: **6–8 hours**
+Full pipeline included in repository (`.drone.yml`).
 ---
-## **12. Risks & Considerations**
+## 🌐 Traefik Routing
-| Risk                           | Mitigation                     |
+### HTTPS
 |--------------------------------|--------------------------------|
 | UI lacks error/reconnect logic | Add retry + reconnection flows |
 | No rematch or lobby UX         | Add match lifecycle UI         |
 | No mobile layout               | Add responsive CSS             |
 | Cloud deployment pending       | Prioritize after UI polish     |
 | Matchmaking UX is minimal      | Add feedback, loading states   |
-None of these affect core backend stability.
+```
 nakama.aetoskia.com
  /      → HTTP API
  /ws    → WebSocket (real-time)
 ```
 Includes:
 * CORS rules
 * WebSocket upgrade headers
 * Certificate resolver
 * Secure default middlewares
 ---
-## **13. Next Steps**
+## 🔧 Environment Variables
-### **UI Tasks**
+| Variable        | Description                  |
-
+| --------------- | ---------------------------- |
-1. Add reconnect + error-handling UI
+| `DB_ADDR`       | PostgreSQL connection string |
-2. Create lobby → gameplay → results, flow
+| `SERVER_KEY`    | Nakama server key            |
-3. Add rematch capability
+| `REGISTRY_HOST` | Private registry             |
 4. Add responsive + polished UI
 5. Add loading indicators & animations
 Estimated remaining effort: **6 to 8 hours**
 ---
-## **Executive Summary**
+## 📊 Leaderboards
-### Issues faced
+* Created during server start
-Several unexpected integration challenges during UI setup contributed to the additional day of work. These included:
+* Score: `+1` on win
- Aligning the UI’s matchmaking flow with the new authoritative Go-based matchmaking logic.
+* Metadata logged (mode, player IDs)
 - Handling Nakama JS WebSocket behaviors, especially around session timing, matchmaker ticket handling, and match join events.
 - Ensuring OpCode handling and server-produced state updates matched the server’s authoritative model.
 - Resolving environment-related issues (Vite dev server, Node version mismatches, and WebSocket URL configuration).
 - Debugging cross-origin and connection-reset issues during early WebSocket initialization.
-These challenges required deeper synchronization between the backend and frontend layers, resulting in an additional **+1 day** of engineering time.
+---
-### Project Progress
+## 🧪 Testing
 The system now features a fully authoritative backend with matchmaking, gameplay logic, and leaderboards implemented
 completely in Go. The UI is functional and integrates correctly with all backend systems, supporting end-to-end
 matchmaking and gameplay.
-Key remaining work involves UI polish, recovery/error handling, and deployment setup. No major architectural risks
+* Win/loss/draw simulation
-remain.
+* Invalid move rejection
 * Disconnect → forfeit
 * Load testing matchmaking
-**The project is now fully playable, technically solid, and ready for final UI enhancements and cloud deployment.**
+---
 ## 📈 Production Deployment
 Supported on:
 * ARM homelabs (Raspberry Pi)
 * Google Cloud (Compute Engine + Cloud SQL)
 * AWS EC2
 * Kubernetes (optional)
 ---
 ## 🤝 Contributing
 1. Fork repo
 2. Create feature branch
 3. Write tests
 4. Submit PR
 Coding style: Go fmt + idiomatic Go; follow Nakama plugin constraints.
 ---
Author	SHA1	Message	Date
aetos	70669fc856	Update README.md	2025-12-01 08:33:28 +00:00
aetos	1752bfaed4	Update README.md	2025-12-01 08:33:01 +00:00
aetos	74e75de577	Update README.md	2025-12-01 08:32:29 +00:00
aetos	7983be56e4	Update README.md	2025-12-01 08:27:57 +00:00
Vishesh 'ironeagle' Bangotra	e9eb37f665	fixes	2025-11-30 02:06:50 +05:30
Vishesh 'ironeagle' Bangotra	7a7c6adc47	updated report	2025-11-30 02:04:41 +05:30