docs: add comprehensive client and server architecture documentation

Architecture-Client.md

@@ -0,0 +1,67 @@
+# Tekton Dash Armageddon - Client Architecture
+
+## Core Game Flow
+
+Tekton uses a heavily decoupled Singleton (Autoload) architecture mixed with standard Godot High-Level Multiplayer RPCs.
+
+1. **Boot:** `boot_screen.tscn` is the entry point. It verifies version via `GameUpdateManager`, downloads `patch.pck` if available, and then loads `login_screen.tscn`.
+2. **Auth:** `AuthManager` handles Nakama login/sessions. Upon success, loads `lobby.tscn`.
+3. **Lobby:** Players form parties, select game modes, and pull Gacha. `LobbyManager` holds the selected `game_mode` string.
+4. **Match Start:** Host transitions to `main.tscn`. The `Main` script inspects `LobbyManager.game_mode` and dynamically instantiates the correct Mode Manager (`GauntletManager`, `StopNGoManager`, etc.).
+5. **Spawning:** `main.gd` asks `PlayerManager` to instantiate `player.tscn` for all connected peers based on `GameStateManager` player IDs.
+
+## Singletons & Autoloads (`scripts/managers/`)
+
+There are ~74 manager scripts. Key singletons include:
+
+### State & Networking
+- **`NakamaManager` / `AuthManager`:** Connects to the backend VPS for authentication, leaderboards, storage (friends, inbox), and matchmaking.
+- **`LobbyManager`:** Tracks pre-match state, chat, room configuration, and connected peers.
+- **`GameStateManager`:** Tracks active players, bots, and the authoritative "match active" flags.
+
+### Actor Control (`player.gd` delegates)
+- **`PlayerMovementManager`:** Validates and executes GridMap translation. `try_push()` handles collision/smacking mechanics.
+- **`PlayerInputManager`:** Reads keyboard/gamepad and touch inputs, polling every frame to instruct `PlayerMovementManager`.
+- **`PlayerActionManager`:** Handles grid interactions (grabbing, dropping) and tracks Action Points (AP).
+
+### Economy & Meta
+- **`UserProfileManager`:** Manages the authoritative `wallet` (Gold/Star balances), cosmetic inventory, and fragments. Fetches from Nakama Storage.
+- **`GachaManager`:** Reads backend gacha configs, calls Lua RPCs to roll, and grants fragments/skins.
+- **`SkinManager`:** Dynamically applies unlocked materials to base meshes.
+
+### Game Modes
+- **`StopNGoManager`:** Classic mode — green light / red light movement blocking.
+- **`GauntletManager`:** Candy Pump Survival — waves of expanding sticky bubbles, center cannon shooting projectiles, invisible ghost mechanics.
+- **`PortalModeManager`:** Tekton Doors — maze running and teleporters.
+
+### UI & Render
+- **`UIManager`:** Binds `player.gd` state to CanvasLayers. Specifically handles the 5x5 Grid `playerboard_ui`.
+- **`SfxManager` / `MusicManager`:** Global audio pooling.
+
+## Major UI Components (`scenes/ui/`)
+
+- `lobby_main_menu.tscn`: Holds the primary game mode selection, Shop, and Gacha buttons.
+- `shop_panel.tscn`: Reads `UserProfileManager` to buy Gold (IAP) or convert Gold to Stars.
+- `gacha_panel.tscn`: 1x/10x pulls for Skins and Fragments.
+- `daily_reward_panel.tscn`: Daily login progression matrix.
+- `admin_panel.tscn`: Server moderation tools (requires Admin flag from Nakama).
+
+## Dependency Graph
+
+```mermaid
+flowchart TD
+    LobbyManager -->|Match Start| Main[main.tscn]
+    Main -->|Instantiates| PlayerManager
+    PlayerManager -->|Spawns| Player[player.tscn]
+    
+    Main -->|Game Logic| ModeManagers[StopNGo/Gauntlet/Portal]
+    
+    Player -->|Delegates Input| PlayerInputManager
+    PlayerInputManager -->|Commands| PlayerMovementManager
+    PlayerMovementManager -->|Collisions| SfxManager
+    
+    Lobby[lobby.tscn] -->|Meta| UserProfileManager
+    Lobby -->|Pulls| GachaManager
+    UserProfileManager <--> NakamaManager
+    GachaManager <--> NakamaManager
+```

Architecture-Server.md

@@ -0,0 +1,58 @@
+# Tekton Dash Armageddon - Server Architecture
+
+## Nakama Backend (`server/nakama/lua/`)
+
+The backend runs on Nakama, written in Lua. It provides authoritative server-side logic for the economy, anti-cheat, mail, and gacha pulls. 
+
+Godot clients call these endpoints via `BackendService.api_rpc_async()`.
+
+### Key Lua Modules
+- **`economy.lua`:**
+  - `buy_currency`: Validates mock/Google/Apple receipts and directly adds Gold or subtracts Gold for Stars via `nk.wallet_update`.
+  - `purchase_item`: Buys cosmetic items from the shop catalog. Validates wallet funds and writes to `inventory` storage.
+- **`gacha.lua`:**
+  - `perform_gacha_pull`: Reads banner drop rates, rolls RNG on the server, manages pity counters, and deducts the pull cost from the wallet. Prevents client-side RNG manipulation.
+- **`inbox.lua`:**
+  - `get_mail` / `claim_mail_reward`: Server-authoritative mail system. Rewards attached to mail are granted directly to the wallet on claim.
+- **`user.lua` & `admin.lua`:**
+  - `admin_topup_gold`: Admin-only RPC to grant 999,999 gold.
+  - `admin_ban_player`: Banning tool.
+  - Profile and friend sync logic.
+
+## Client / Server Wallet Synchronization
+
+There is **only one authoritative wallet** per user stored on the Nakama backend.
+
+1. Lua calls `nk.wallet_update(changeset)` upon any transaction.
+2. The Godot client calls `UserProfileManager._reload_wallet()`.
+3. Godot fetches the new JSON string from `account.wallet`.
+4. `UserProfileManager` emits `profile_updated`.
+5. All connected UI components (Lobby Top Bar, Shop Panel, Gacha Panel) instantly update their text labels to reflect the unified `gold` and `star` balances.
+
+## CI/CD and Hot-Patching Pipeline (`.gitea/workflows/`)
+
+The game features two distinct automated deployment pipelines.
+
+### Full Releases (`ci.yml`)
+- **Trigger:** Pushing a git tag (e.g. `v3.0.0`).
+- **Purpose:** Compiling heavy native binaries (Windows `.exe`, Linux binaries, macOS `.app`).
+- **Flow:**
+  1. Clones repository.
+  2. Pulls cached Godot 4.7 binary and export templates from `/cache/` on the runner to skip the 1.3GB download.
+  3. Runs `godot --headless --export-release` for each platform.
+  4. Zips outputs and uploads to Gitea's release asset API.
+- **Player Experience:** Must download and replace their entire game folder/executable.
+
+### Hot-Patching (`deploy_patch.yml`)
+- **Trigger:** Manual `workflow_dispatch` button from the Gitea UI.
+- **Purpose:** Pushing lightweight Godot asset changes (Scripts, Scenes, VFX, Sounds) instantly.
+- **Flow:**
+  1. Python script `generate_version_json.py` consumes `CHANGELOG_DRAFT.md` and bumps `version.json`.
+  2. Runs `godot --headless --export-pack` to build a single, shared `patch.pck` file.
+  3. Force-pushes `patch.pck` and `version.json` to the orphan `patches` git branch.
+  4. A `gitea-pages` Docker container serves this branch publicly at `https://raw.klud.top`.
+- **Player Experience:** 
+  1. Game boots to `boot_screen.tscn`.
+  2. Fetches `https://raw.klud.top/danchie/tekton/version.json`.
+  3. Downloads `patch.pck` if the version is newer.
+  4. Mounts it into `user://` to override the base `res://` filesystem seamlessly.

Home.md

@@ -24,6 +24,8 @@ First-time SSH setup:
 
 ## Pages
 
+- [Architecture - Client](./Architecture-Client) — Core Godot game loop, Singletons, and Node dependencies.
+- [Architecture - Server](./Architecture-Server) — Nakama Lua backend, Wallets, and CI/CD Build pipelines.
 - [Skin Creation Workflow](./Skin-Creation-Workflow) — Authoring skin materials and registering them in the catalog.
 - [Nakama Deployment](./Nakama-Deployment) — Pushing the shop/gacha backend to the Nakama VPS.
 - [Patch Release Workflow](./Patch-Release-Workflow) — Building, versioning, and shipping patches to live clients.