From 95e1d07406ea0d747c4e0ab13a62f1b29e45237c Mon Sep 17 00:00:00 2001
From: aetos <aetoskia@gmail.com>
Date: Mon, 1 Dec 2025 08:40:02 +0000
Subject: [PATCH] Update README.md

---
 README.md | 160 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 159 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 6c2f121..478a4f4 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,159 @@
-# Lila Games
\ No newline at end of file
+# 🎮 Lila Games
+
+### **Authoritative Multiplayer Game Systems • Real-time Networking • Scalable Infrastructure**
+
+Welcome to **Lila Games**, a studio focused on building small, tightly engineered multiplayer experiences with production-grade backend systems.
+
+We specialize in:
+
+* **Server-authoritative gameplay**
+* **Real-time WebSocket networking**
+* **Go-based engine plugins**
+* **Cloud-ready ARM & x86 infrastructure**
+* **Modern DevOps (Drone CI/CD + Traefik)**
+
+Our flagship project: a fully authoritative **Multiplayer Tic-Tac-Toe Platform** built on **Nakama + Go**.
+
+---
+
+## 🚀 Projects
+
+### 🔷 **1. tic-tac-toe (Backend)**
+
+**Nakama 3 + Go Plugin • Authoritative Multiplayer Server**
+
+* Device authentication
+* Matchmaking queues
+* Authoritative match handler
+* Win/loss/draw validation
+* Disconnect → forfeit
+* Leaderboards
+* ARM-optimized Docker build
+* Automated CI/CD with Drone
+* Traefik WebSocket routing (`/ws`)
+
+🔗 **Repo:** [https://git.aetoskia.com/lila-games/tic-tac-toe](https://git.aetoskia.com/lila-games/tic-tac-toe)
+
+---
+
+### 🔶 **2. tic-tac-toe-ui (Frontend)**
+
+**React + TypeScript + Vite**
+Production-grade multiplayer game client.
+
+* Device auth
+* Matchmaking
+* Real-time WebSocket gameplay
+* Authoritative board sync
+* Leaderboards
+* BusyBox-powered production Docker build
+
+🔗 **Repo:** [https://git.aetoskia.com/lila-games/tic-tac-toe-ui](https://git.aetoskia.com/lila-games/tic-tac-toe-ui)
+
+---
+
+## 🧩 System Architecture
+
+```mermaid
+flowchart LR
+    UI[Frontend (React + TS + Vite)] -->|WebSocket + HTTP| Traefik
+    Traefik --> Nakama[Nakama 3.21.0 ARM]
+    Nakama --> Plugin[Go Plugin (main.so)]
+    Nakama --> Postgres[(PostgreSQL 16)]
+    Dev[Drone CI/CD] -->|Build + Push| Registry[Private Docker Registry]
+    Registry -->|Deploy Image| Nakama
+```
+
+---
+
+## 🛠 Infrastructure
+
+### **Traefik Routing**
+
+* `https://games.aetoskia.com` – UI
+* `https://nakama.aetoskia.com` – Nakama (HTTP + WS)
+* Full CORS configuration
+* WebSocket upgrade headers
+* Automatic Let's Encrypt TLS
+
+---
+
+### **PostgreSQL Stack**
+
+Lila Games uses a production-ready PostgreSQL 16 setup with:
+
+* `pg_stat_statements` enabled for performance insights
+* Persistent storage volumes
+* `.env`-driven secure configuration
+* Optional pgAdmin 4 UI for database administration
+
+This stack powers the authoritative match state, player accounts, and leaderboards.
+
+---
+
+## 🤖 CI/CD Pipeline
+
+Powered by **Drone CI**, our automated pipeline handles:
+
+* Auto-detecting the latest Git tags
+* Skipping builds if an image already exists
+* Building Nakama + Go plugin (CGO-enabled)
+* Pushing production images to the private registry
+* Stopping old containers and deploying new ones
+* Supporting ARM/x86 builds
+
+### Deployment Flowchart
+
+```mermaid
+flowchart TD
+    DevPush[Developer pushes Git tag] --> Drone[Drone CI Pipeline]
+    Drone --> FetchTags[Fetch latest Git tags]
+    FetchTags --> CheckImage[Check if Docker image exists]
+    CheckImage -->|Image missing| Build[Build Docker Image]
+    CheckImage -->|Image exists| Skip[Skip Build]
+    Build --> Push[Push Image to Private Registry]
+    Skip --> Deploy[Deploy Step]
+    Push --> Deploy[Deploy Step]
+    Deploy --> StopOld[Stop Old Nakama Container]
+    StopOld --> RunNew[Run New Nakama Container]
+    RunNew --> Live[Production Server Updated]
+```
+
+Powered by **Drone CI**:
+
+* Auto-detect latest Git tags
+* Skip builds if image exists
+* Build Nakama Go plugin (CGO-enabled)
+* Push to private registry
+* Stop old containers + deploy new
+* ARM-compatible builds for Raspberry Pi clusters
+
+---
+
+## 🐳 Docker & Deployment
+
+Our entire stack runs via Docker:
+
+* Backend image (`heroiclabs/nakama:arm`)
+* Go plugin layer
+* Frontend: Node → Vite → BusyBox
+* Traefik reverse proxy
+* PostgreSQL + pgAdmin
+
+Cloud-ready for:
+
+* Google Cloud (Compute Engine + Cloud SQL)
+* AWS EC2
+* Bare metal
+* Raspberry Pi homelabs
+
+
+## 📫 Contact
+
+Want to collaborate or review the backend architecture?
+
+**Website:** [https://games.aetoskia.com](https://games.aetoskia.com)
+**GitHub:** [https://git.aetoskia.com/lila-games](https://git.aetoskia.com/lila-games)
+**Tech Stack:** Go, Nakama, PostgreSQL, React, Vite, Docker, Traefik, Drone CI
+
+---