🎮 Sister Brawl — Deep Architecture Audit

Date: 2026-06-04 (updated from 2026-05-31) Auditor: Hermes (OWL) Scope: Full-stack audit — frontend, backend, config, deploy, docs, fun audit v2 Game ID: sisterbrawl (alias: sister-brawl)

📋 Table of Contents

1. Executive Summary
2. Architecture Overview
3. Frontend Game Code
4. Nakama Match Handler
5. K8s & Monitoring Deploy
6. Known Issues & Fixes
7. Perfection Cycle — What’s New
8. Operational Runbooks
9. Doc Map

1. Executive Summary

2. Architecture Overview

┌─────────────────────────────────────────────────────────┐
│ Browser (Client)                                        │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Game.svelte (~1,285 LOC)                         │  │
│  │  ├── Threlte <Canvas> → 3D arena + entities       │  │
│  │  ├── 2D Canvas fallback (solo/headless)           │  │
│  │  ├── gameStore.svelte.ts (507 LOC)                │  │
│  │  │   ├── Client-side prediction + reconciliation   │  │
│  │  │   ├── Entity interpolation (lerp)               │  │
│  │  │   ├── Hit-stop (freeze-frame on big hits)       │  │
│  │  │   ├── Floating damage numbers                   │  │
│  │  │   └── Progression data (XP/levels)              │  │
│  │  ├── spectatorStore.ts (175 LOC)                   │  │
│  │  ├── audio.ts (250 LOC) — layered music + 14+ SFX │  │
│  │  ├── particleSystem.ts (80 LOC)                    │  │
│  │  ├── screenShake.ts (119 LOC)                      │  │
│  │  └── UI: CharacterSelect, HUD, Results, Replay     │  │
│  │       SpectatorViewport, TutorialOverlay (NEW)     │  │
│  └───────────────────────────────────────────────────┘  │
│                    ↕ Nakama WebSocket                    │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│ Nakama Server (K3s)                                     │
│  ┌───────────────────────────────────────────────────┐  │
│  │  match_handler.ts (~1,491 LOC)                    │  │
│  │  ├── 60Hz tick → input → physics → broadcast      │  │
│  │  ├── 6 character definitions + balance            │  │
│  │  ├── Character-specific specials (NEW)             │  │
│  │  │   ├── Ember: Fireball + burn DOT               │  │
│  │  │   ├── Frost: Ice Wall obstacle                 │  │
│  │  │   ├── Volt: Dash Strike AoE                    │  │
│  │  │   ├── Shade: Teleport Crit                     │  │
│  │  │   ├── Terra: Ground Pound stun                 │  │
│  │  │   └── Aqua: Water Shield reflect + heal        │  │
│  │  ├── Kill threshold match end (10 kills)          │  │
│  │  ├── Dramatic finish (last 10s slow-mo)            │  │
│  │  ├── XP/Level progression (Nakama storage)         │  │
│  │  ├── Replay recording (10 Hz, Nakama storage)      │  │
│  │  ├── Free camera spectator mode                    │  │
│  │  └── 3 RPCs: replay, metrics, spectate            │  │
│  │                                                     │  │
│  │  metrics.ts (187 LOC)                              │  │
│  │  └── 4 Prometheus metrics                          │  │
│  └───────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Metrics Sidecar (Python, :9101)                  │  │
│  │  └── Polls RPC → serves Prometheus text            │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

3. Frontend Game Code

File Inventory

Character Roster

4. Nakama Match Handler

Opcodes

Game Constants

New: Character Specials (Server-Side)

All 6 characters now have unique special abilities on the server:

• Ember: Fireball projectile with burn DOT (2 DPS, 3s)
• Frost: Ice Wall obstacle (blocks movement/projectiles, 10s lifetime)
• Volt: Dash Strike AoE (damage + chain to all enemies within 4 units)
• Shade: Teleport behind nearest enemy + guaranteed 2x crit
• Terra: Ground Pound AoE (damage + 1s stun in 5-unit radius)
• Aqua: Water Shield (reflects nearby projectiles + self-heal 15 HP)

New: Progression System

• XP per match: 10 base + 5 per kill + 10 win bonus
• Streak bonus: 3+ win streak = 2x XP
• Levels: 100 XP per level
• Stored in Nakama storage: collection=“progression”, key=“{userId}/xp”
• Included in GAME_OVER payload for client display

New: Match End Conditions

• Kill threshold: First team to 10 kills wins immediately
• Timeout: 5-minute fallback (team with most kills wins)
• Dramatic finish: Last 10 seconds when kill leader ≥ 8 (client indicator)

5. K8s & Monitoring Deploy

Prometheus Alerts

6. Known Issues & Fixes

✅ Resolved

🟡 Remaining

7. Perfection Cycle — What’s New

Fun Audit v2 Results

Changes in This Cycle

1. Character-specific specials — All 6 characters now have unique server-side abilities
2. Match-end kill threshold — First to 10 kills wins immediately
3. Hit-stop — 2-3 frame freeze on KO and special hits
4. Damage numbers — Floating text on 2D canvas showing damage taken
5. Audio upgrade — Layered kick/bass/lead music with 100→140 BPM tempo ramp
6. Tutorial overlay — 3-step first-fight onboarding (move → attack → special)
7. Progression system — XP/levels/streaks with Nakama storage
8. Dramatic finish — Last 10 seconds indicator when kill leader ≥ 8

8. Operational Runbooks

Deploy Nakama Module

cd /home/usr/funday/nakama-modules && npm run build
sudo kubectl rollout restart deployment nakama -n funday-platform
sudo kubectl logs -n funday-platform deployment/nakama --tail=20

Deploy Frontend

bash /home/usr/funday/scripts/build-atomic.sh
systemctl is-active funday-frontend
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/play/sisterbrawl

Deploy K8s

sudo kubectl apply -f games/sisterbrawl/deploy/k3s-deployment.yaml
sudo kubectl apply -f games/sisterbrawl/deploy/k3s-metrics-deployment.yaml
sudo kubectl get pods -n funday-platform -l app=sisterbrawl

Health Checks

curl -sf http://127.0.0.1:3000/health                          # Frontend
curl -sf https://funday.gg/v2/healthcheck                       # Nakama
sudo journalctl -u funday-frontend -f                            # Frontend logs
sudo k3s kubectl logs -n funday-platform -l app=nakama --tail=50 # Nakama logs

9. Doc Map