What a mess

docs/WORLD_STORAGE_ANALYSIS.md

@@ -0,0 +1,59 @@
+# World Data Storage: JSON vs Database Analysis
+
+## Decision: Keep JSON-based Storage ✅
+
+**Status:** JSON approach is working well and should be maintained.
+
+## Current State: JSON-based
+
+World data (locations, connections, interactables) is stored in JSON files:
+- `gamedata/locations.json` - 14 locations with interactables
+- `gamedata/interactables.json` - Templates for searchable objects
+- `gamedata/items.json` - Item definitions
+- `gamedata/npcs.json` - NPC definitions
+
+**Why JSON works well:**
+- ✅ Easy to edit and version control (Git-friendly)
+- ✅ Fast iteration - edit JSON and restart API
+- ✅ Loaded once at startup, kept in memory (very fast access)
+- ✅ Simple structure, human-readable
+- ✅ No database migrations needed for world changes
+- ✅ Easy to backup/restore entire world state
+- ✅ **Web map editor already works perfectly for editing**
+- ✅ Current scale (14 locations) fits well in memory
+- ✅ Zero additional complexity
+
+**When to reconsider database storage:**
+- If world grows to 1000+ locations (memory concerns)
+- If you need runtime world modifications from gameplay (destructible buildings)
+- If you need complex spatial queries
+- If multiple admins need concurrent editing with conflict resolution
+
+For now, the JSON approach is the right choice. Don't fix what isn't broken!
+
+## Alternative: Database Storage (For Future Reference)
+
+If the world grows significantly (1000+ locations) or requires runtime modifications, here are the database approaches that could be considered:
+
+### Option 1: Separate connections table
+```sql
+CREATE TABLE locations (id, name, description, image_path, x, y);
+CREATE TABLE connections (from_location, to_location, direction, stamina_cost);
+```
+- Most flexible approach
+- Easy to add/remove connections
+- Can store metadata per connection
+
+### Option 2: Directional columns
+```sql
+CREATE TABLE locations (id, name, north, south, east, west, ...);
+```
+- Simpler queries
+- Less flexible (fixed directions)
+
+### Option 3: Hybrid (JSON + Database)
+- Keep JSON as source of truth
+- Load into database at startup for querying
+- Export back to JSON for version control
+
+**Current assessment:** None of these are needed now. JSON + web editor is the right solution for current scale.