echoes-of-the-ash/docs/WORLD_STORAGE_ANALYSIS.md

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

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

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.