TribeGen: File-Based Architecture - Complete Mapping
Architecture Overview
Hybrid Storage Model
- SQLite Database: User authentication only
- JSON Files: All game saves and state
- No Relationships: All data is self-contained within save directories
---
Directory Structure
tribegen/
├── src/
│ ├── api/
│ │ ├── auth.php # Authentication endpoints (unchanged)
│ │ └── game.php # Game endpoints (REFACTORED)
│ ├── Classes/
│ │ ├── User.php # Auth + getSaves() (REFACTORED)
│ │ ├── Tribe.php # Tribe state (REFACTORED to use SaveManager)
│ │ ├── Kobold.php # Individual kobold (REFACTORED)
│ │ ├── Item.php # Items (REFACTORED)
│ │ ├── NPC.php # NPCs (REFACTORED)
│ │ ├── Injury.php # Injury data (unchanged)
│ │ └── Events/
│ │ ├── Event.php # Base event class (unchanged)
│ │ ├── HuntingEvent.php # Hunting event (unchanged)
│ │ ├── ExplorationEvent.php
│ │ └── FarmingEvent.php
│ ├── Database/
│ │ └── Database.php # Connection manager (SIMPLIFIED)
│ ├── System/
│ │ └── SaveManager.php # File I/O abstraction (NEW)
│ └── Utilities/
│ ├── GameHelper.php # Game helpers (unchanged)
│ └── EventManager.php # Event orchestration (unchanged)
├── data/
│ └── saves/ # All game saves directory
│ └── {userId}/
│ ├── 1/ # Save file 1
│ │ ├── save.json
│ │ ├── kobolds.json
│ │ ├── items.json
│ │ └── npcs.json
│ ├── 2/ # Save file 2
│ └── kobolds/
│ └── {koboldId}/sprites/ # Modified sprites
├── public/
│ ├── index.php # Router (minimal changes)
│ ├── index.html # SPA (unchanged)
│ ├── js/
│ │ └── game.js # Client logic (unchanged)
│ └── css/
│ └── style.css # Styles (unchanged)
└── vendor/ # Composer dependencies
---
Class Signatures (Before → After)
Tribe
Before:
new Tribe($saveId)
Tribe::create($userId, $saveName)
Tribe::load($saveId)
$tribe->save() // Used database
After:
new Tribe($userId, $saveId, $name)
Tribe::create($userId, $saveName) // Auto-generates saveId via SaveManager
Tribe::load($userId, $saveId) // Requires userId
$tribe->save() // Saves to JSON files
Kobold
Before:
new Kobold($id, $saveId, $name, $age, $spriteMorph)
Kobold::generate($saveId, $age)
$kobold->save() // Database INSERT/UPDATE
$kobold->addInjury($type, $category, $severity) // Database INSERT
After:
new Kobold($id, $userId, $saveId, $name, $age, $spriteMorph)
Kobold::generate($userId, $saveId, $age)
$kobold->save() // No-op (saved via Tribe)
$kobold->fromArray($data) // Deserialize from JSON
$kobold->toArray() // Serialize to JSON
$kobold->addInjury() // Uses uniqid() instead of database
Item
Before:
new Item($id, $saveId, $name, $description, $itemType)
// Loaded modifications from database via constructor
After:
new Item($id, $saveId, $name, $description, $itemType, $statModifications)
Item::fromArray($data) // Create from JSON
$item->toArray() // Serialize to JSON
NPC
Before:
NPC::create($saveId, $name, $npcType, $isRival) // Database INSERT
NPC::load($id) // Database SELECT
$npc->save() // Database UPDATE
After:
NPC::create($saveId, $name, $npcType, $isRival) // Generates uniqid
NPC::fromArray($data) // Create from JSON
$npc->toArray() // Serialize to JSON
$npc->save() // No-op (saved via Tribe)
User
Before & After:
User::register($email, $password) // Still uses database
User::login($email, $password) // Still uses database
$user->getSaves() // WAS: SELECT from saves table
// NOW: SaveManager.listUserSaves()
---
SaveManager API
class SaveManager {
// Directory Management
public function getUserSavesPath($userId) // Create/return /data/saves/{userId}/
public function getSavePath($userId, $saveId) // Create/return /data/saves/{userId}/{saveId}/
public function getKoboldSpritePath($userId, $koboldId) // Create/return sprites dir
// JSON Persistence
public function saveJson($filePath, $data) // Write with error handling
public function loadJson($filePath) // Read with error handling
// Save Management
public function listUserSaves($userId) // Return array of saves, sorted
public function generateSaveId($userId) // Auto-increment numeric ID
public function deleteSave($userId, $saveId) // Recursive delete
}
---
Database Changes
Before (13 tables)
users
saves
kobolds
injuries
items
kobold_items
item_modifications
events_enabled
injuries_enabled
npcs
-- (plus other tables)
After (1 table)
users (id, email, password_hash, created_at)
All other data is stored in JSON files under /data/saves/.
---
API Endpoint Changes
POST /api/game/generation
Before:
{
"userId": 1,
"saveName": "My First Tribe"
}
// Returned: saveId from database
After:
{
"userId": 1,
"saveName": "My First Tribe"
}
// Returns: saveId from SaveManager.generateSaveId()
// Creates: /data/saves/1/1/save.json with tribe metadata
// /data/saves/1/1/kobolds.json with 20 kobolds
GET /api/game/list
Before:
SELECT * FROM saves WHERE user_id = ? ORDER BY last_played DESC
After:
SaveManager.listUserSaves($userId)
// Scans /data/saves/{userId}/ directory
// Loads save.json from each subdirectory
// Returns sorted array
GET /api/game/load
Before:
SELECT * FROM saves WHERE id = ?
SELECT * FROM kobolds WHERE save_id = ?
-- Multiple queries with JOINs
After:
Tribe::load($userId, $saveId)
// Reads /data/saves/{userId}/{saveId}/save.json
// Reads /data/saves/{userId}/{saveId}/kobolds.json
// Reconstructs objects from JSON
---
Data Migration (Optional)
If you have existing saves in the old database:
// Pseudo-code for migration
$saveManager = new SaveManager();
// Get all old saves from database
$stmt = $pdo->query("SELECT * FROM saves");
foreach ($stmt->fetchAll() as $saveRow) {
// Load tribe from old database
$tribe = Tribe::load($saveRow['id']);
// Tribe now reads from database in constructor
// Save to JSON via SaveManager
$tribe->save();
// Now JSON files exist at /data/saves/{userId}/{saveId}/
}
// Can then safely drop old tables
$pdo->exec("DROP TABLE IF EXISTS saves, kobolds, injuries, ...");
---
Key Design Decisions
1. SaveManager Abstraction: All file I/O goes through one class for consistency 2. Numeric Save IDs: Simple incrementing IDs (1, 2, 3...) per user 3. Array Serialization: Kobolds/Items/NPCs stored as JSON arrays, not individual files 4. No Foreign Keys: JSON doesn't enforce relationships; parent_id/mother_id are simple strings 5. Uniqid for PKs: No auto-increment in JSON; use uniqid('prefix_') for unique IDs 6. Single User Table: Database only needed for authentication; all else is file-based
---
Performance Implications
Advantages
- No network latency for game operations (local file I/O)
- No query planning overhead
- Easier caching (just load JSON into memory)
- Faster writes (JSON serialization is fast)
Considerations
- Loading full tribe into memory (not streaming)
- No partial reads (always load entire save)
- No indexing (linear scans for save lists)
- File locking for concurrent access (minor issue with single-player)
Optimization Opportunities (Future)
- Cache loaded tribues in-memory with TTL
- Lazy-load kobolds on demand
- Save only changed objects instead of full serialization
- Use MessagePack instead of JSON for binary efficiency
---
Backwards Compatibility
✅ Public API preserved (with signature updates):
Tribe::create(),Tribe::load()existKobold.save()exists (now no-op)- All game logic unchanged
❌ Breaking changes:
Tribe::load()now requires$userIdparameterKobold::generate()now requires$userIdparameter- Database queries replaced with SaveManager calls
---
Testing Checklist
0 of 8 tasks completed
- Create new save → saves to /data/saves/{userId}/{saveId}/
- Load save → reads from JSON files
- List saves → returns correct order by last_played
- End month → updates save.json with new month/season
- Food consumption → persists food_count in save.json
- Delete save → removes /data/saves/{userId}/{saveId}/ directory
- Multiple saves per user → no conflicts with numeric IDs
- Offline editing → can modify JSON and load in game
---
Future Enhancements
1. Cloud Sync: Upload saves to server, sync across devices 2. Save Versioning: Keep multiple versions of saves 3. Shared Saves: Allow cooperative play (merge saves) 4. Analytics: Track which saves are most played 5. Export Formats: Convert to CSV, Excel, or other formats
Source
| 1 | # TribeGen: File-Based Architecture - Complete Mapping |
| 2 | |
| 3 | ## Architecture Overview |
| 4 | |
| 5 | ### Hybrid Storage Model |
| 6 | - **SQLite Database**: User authentication only |
| 7 | - **JSON Files**: All game saves and state |
| 8 | - **No Relationships**: All data is self-contained within save directories |
| 9 | |
| 10 | --- |
| 11 | |
| 12 | ## Directory Structure |
| 13 | |
| 14 | ``` |
| 15 | tribegen/ |
| 16 | ├── src/ |
| 17 | │ ├── api/ |
| 18 | │ │ ├── auth.php # Authentication endpoints (unchanged) |
| 19 | │ │ └── game.php # Game endpoints (REFACTORED) |
| 20 | │ ├── Classes/ |
| 21 | │ │ ├── User.php # Auth + getSaves() (REFACTORED) |
| 22 | │ │ ├── Tribe.php # Tribe state (REFACTORED to use SaveManager) |
| 23 | │ │ ├── Kobold.php # Individual kobold (REFACTORED) |
| 24 | │ │ ├── Item.php # Items (REFACTORED) |
| 25 | │ │ ├── NPC.php # NPCs (REFACTORED) |
| 26 | │ │ ├── Injury.php # Injury data (unchanged) |
| 27 | │ │ └── Events/ |
| 28 | │ │ ├── Event.php # Base event class (unchanged) |
| 29 | │ │ ├── HuntingEvent.php # Hunting event (unchanged) |
| 30 | │ │ ├── ExplorationEvent.php |
| 31 | │ │ └── FarmingEvent.php |
| 32 | │ ├── Database/ |
| 33 | │ │ └── Database.php # Connection manager (SIMPLIFIED) |
| 34 | │ ├── System/ |
| 35 | │ │ └── SaveManager.php # File I/O abstraction (NEW) |
| 36 | │ └── Utilities/ |
| 37 | │ ├── GameHelper.php # Game helpers (unchanged) |
| 38 | │ └── EventManager.php # Event orchestration (unchanged) |
| 39 | ├── data/ |
| 40 | │ └── saves/ # All game saves directory |
| 41 | │ └── {userId}/ |
| 42 | │ ├── 1/ # Save file 1 |
| 43 | │ │ ├── save.json |
| 44 | │ │ ├── kobolds.json |
| 45 | │ │ ├── items.json |
| 46 | │ │ └── npcs.json |
| 47 | │ ├── 2/ # Save file 2 |
| 48 | │ └── kobolds/ |
| 49 | │ └── {koboldId}/sprites/ # Modified sprites |
| 50 | ├── public/ |
| 51 | │ ├── index.php # Router (minimal changes) |
| 52 | │ ├── index.html # SPA (unchanged) |
| 53 | │ ├── js/ |
| 54 | │ │ └── game.js # Client logic (unchanged) |
| 55 | │ └── css/ |
| 56 | │ └── style.css # Styles (unchanged) |
| 57 | └── vendor/ # Composer dependencies |
| 58 | ``` |
| 59 | |
| 60 | --- |
| 61 | |
| 62 | ## Class Signatures (Before → After) |
| 63 | |
| 64 | ### Tribe |
| 65 | |
| 66 | **Before:** |
| 67 | ```php |
| 68 | new Tribe($saveId) |
| 69 | Tribe::create($userId, $saveName) |
| 70 | Tribe::load($saveId) |
| 71 | $tribe->save() // Used database |
| 72 | ``` |
| 73 | |
| 74 | **After:** |
| 75 | ```php |
| 76 | new Tribe($userId, $saveId, $name) |
| 77 | Tribe::create($userId, $saveName) // Auto-generates saveId via SaveManager |
| 78 | Tribe::load($userId, $saveId) // Requires userId |
| 79 | $tribe->save() // Saves to JSON files |
| 80 | ``` |
| 81 | |
| 82 | ### Kobold |
| 83 | |
| 84 | **Before:** |
| 85 | ```php |
| 86 | new Kobold($id, $saveId, $name, $age, $spriteMorph) |
| 87 | Kobold::generate($saveId, $age) |
| 88 | $kobold->save() // Database INSERT/UPDATE |
| 89 | $kobold->addInjury($type, $category, $severity) // Database INSERT |
| 90 | ``` |
| 91 | |
| 92 | **After:** |
| 93 | ```php |
| 94 | new Kobold($id, $userId, $saveId, $name, $age, $spriteMorph) |
| 95 | Kobold::generate($userId, $saveId, $age) |
| 96 | $kobold->save() // No-op (saved via Tribe) |
| 97 | $kobold->fromArray($data) // Deserialize from JSON |
| 98 | $kobold->toArray() // Serialize to JSON |
| 99 | $kobold->addInjury() // Uses uniqid() instead of database |
| 100 | ``` |
| 101 | |
| 102 | ### Item |
| 103 | |
| 104 | **Before:** |
| 105 | ```php |
| 106 | new Item($id, $saveId, $name, $description, $itemType) |
| 107 | // Loaded modifications from database via constructor |
| 108 | ``` |
| 109 | |
| 110 | **After:** |
| 111 | ```php |
| 112 | new Item($id, $saveId, $name, $description, $itemType, $statModifications) |
| 113 | Item::fromArray($data) // Create from JSON |
| 114 | $item->toArray() // Serialize to JSON |
| 115 | ``` |
| 116 | |
| 117 | ### NPC |
| 118 | |
| 119 | **Before:** |
| 120 | ```php |
| 121 | NPC::create($saveId, $name, $npcType, $isRival) // Database INSERT |
| 122 | NPC::load($id) // Database SELECT |
| 123 | $npc->save() // Database UPDATE |
| 124 | ``` |
| 125 | |
| 126 | **After:** |
| 127 | ```php |
| 128 | NPC::create($saveId, $name, $npcType, $isRival) // Generates uniqid |
| 129 | NPC::fromArray($data) // Create from JSON |
| 130 | $npc->toArray() // Serialize to JSON |
| 131 | $npc->save() // No-op (saved via Tribe) |
| 132 | ``` |
| 133 | |
| 134 | ### User |
| 135 | |
| 136 | **Before & After:** |
| 137 | ```php |
| 138 | User::register($email, $password) // Still uses database |
| 139 | User::login($email, $password) // Still uses database |
| 140 | $user->getSaves() // WAS: SELECT from saves table |
| 141 | // NOW: SaveManager.listUserSaves() |
| 142 | ``` |
| 143 | |
| 144 | --- |
| 145 | |
| 146 | ## SaveManager API |
| 147 | |
| 148 | ```php |
| 149 | class SaveManager { |
| 150 | // Directory Management |
| 151 | public function getUserSavesPath($userId) // Create/return /data/saves/{userId}/ |
| 152 | public function getSavePath($userId, $saveId) // Create/return /data/saves/{userId}/{saveId}/ |
| 153 | public function getKoboldSpritePath($userId, $koboldId) // Create/return sprites dir |
| 154 | |
| 155 | // JSON Persistence |
| 156 | public function saveJson($filePath, $data) // Write with error handling |
| 157 | public function loadJson($filePath) // Read with error handling |
| 158 | |
| 159 | // Save Management |
| 160 | public function listUserSaves($userId) // Return array of saves, sorted |
| 161 | public function generateSaveId($userId) // Auto-increment numeric ID |
| 162 | public function deleteSave($userId, $saveId) // Recursive delete |
| 163 | } |
| 164 | ``` |
| 165 | |
| 166 | --- |
| 167 | |
| 168 | ## Database Changes |
| 169 | |
| 170 | ### Before (13 tables) |
| 171 | ```sql |
| 172 | users |
| 173 | saves |
| 174 | kobolds |
| 175 | injuries |
| 176 | items |
| 177 | kobold_items |
| 178 | item_modifications |
| 179 | events_enabled |
| 180 | injuries_enabled |
| 181 | npcs |
| 182 | -- (plus other tables) |
| 183 | ``` |
| 184 | |
| 185 | ### After (1 table) |
| 186 | ```sql |
| 187 | users (id, email, password_hash, created_at) |
| 188 | ``` |
| 189 | |
| 190 | All other data is stored in JSON files under `/data/saves/`. |
| 191 | |
| 192 | --- |
| 193 | |
| 194 | ## API Endpoint Changes |
| 195 | |
| 196 | ### POST /api/game/generation |
| 197 | **Before:** |
| 198 | ```json |
| 199 | { |
| 200 | "userId": 1, |
| 201 | "saveName": "My First Tribe" |
| 202 | } |
| 203 | // Returned: saveId from database |
| 204 | ``` |
| 205 | |
| 206 | **After:** |
| 207 | ```json |
| 208 | { |
| 209 | "userId": 1, |
| 210 | "saveName": "My First Tribe" |
| 211 | } |
| 212 | // Returns: saveId from SaveManager.generateSaveId() |
| 213 | // Creates: /data/saves/1/1/save.json with tribe metadata |
| 214 | // /data/saves/1/1/kobolds.json with 20 kobolds |
| 215 | ``` |
| 216 | |
| 217 | ### GET /api/game/list |
| 218 | **Before:** |
| 219 | ```sql |
| 220 | SELECT * FROM saves WHERE user_id = ? ORDER BY last_played DESC |
| 221 | ``` |
| 222 | |
| 223 | **After:** |
| 224 | ```php |
| 225 | SaveManager.listUserSaves($userId) |
| 226 | // Scans /data/saves/{userId}/ directory |
| 227 | // Loads save.json from each subdirectory |
| 228 | // Returns sorted array |
| 229 | ``` |
| 230 | |
| 231 | ### GET /api/game/load |
| 232 | **Before:** |
| 233 | ```sql |
| 234 | SELECT * FROM saves WHERE id = ? |
| 235 | SELECT * FROM kobolds WHERE save_id = ? |
| 236 | -- Multiple queries with JOINs |
| 237 | ``` |
| 238 | |
| 239 | **After:** |
| 240 | ```php |
| 241 | Tribe::load($userId, $saveId) |
| 242 | // Reads /data/saves/{userId}/{saveId}/save.json |
| 243 | // Reads /data/saves/{userId}/{saveId}/kobolds.json |
| 244 | // Reconstructs objects from JSON |
| 245 | ``` |
| 246 | |
| 247 | --- |
| 248 | |
| 249 | ## Data Migration (Optional) |
| 250 | |
| 251 | If you have existing saves in the old database: |
| 252 | |
| 253 | ```php |
| 254 | // Pseudo-code for migration |
| 255 | $saveManager = new SaveManager(); |
| 256 | |
| 257 | // Get all old saves from database |
| 258 | $stmt = $pdo->query("SELECT * FROM saves"); |
| 259 | foreach ($stmt->fetchAll() as $saveRow) { |
| 260 | // Load tribe from old database |
| 261 | $tribe = Tribe::load($saveRow['id']); |
| 262 | |
| 263 | // Tribe now reads from database in constructor |
| 264 | // Save to JSON via SaveManager |
| 265 | $tribe->save(); |
| 266 | |
| 267 | // Now JSON files exist at /data/saves/{userId}/{saveId}/ |
| 268 | } |
| 269 | |
| 270 | // Can then safely drop old tables |
| 271 | $pdo->exec("DROP TABLE IF EXISTS saves, kobolds, injuries, ..."); |
| 272 | ``` |
| 273 | |
| 274 | --- |
| 275 | |
| 276 | ## Key Design Decisions |
| 277 | |
| 278 | 1. **SaveManager Abstraction**: All file I/O goes through one class for consistency |
| 279 | 2. **Numeric Save IDs**: Simple incrementing IDs (1, 2, 3...) per user |
| 280 | 3. **Array Serialization**: Kobolds/Items/NPCs stored as JSON arrays, not individual files |
| 281 | 4. **No Foreign Keys**: JSON doesn't enforce relationships; parent_id/mother_id are simple strings |
| 282 | 5. **Uniqid for PKs**: No auto-increment in JSON; use `uniqid('prefix_')` for unique IDs |
| 283 | 6. **Single User Table**: Database only needed for authentication; all else is file-based |
| 284 | |
| 285 | --- |
| 286 | |
| 287 | ## Performance Implications |
| 288 | |
| 289 | ### Advantages |
| 290 | - No network latency for game operations (local file I/O) |
| 291 | - No query planning overhead |
| 292 | - Easier caching (just load JSON into memory) |
| 293 | - Faster writes (JSON serialization is fast) |
| 294 | |
| 295 | ### Considerations |
| 296 | - Loading full tribe into memory (not streaming) |
| 297 | - No partial reads (always load entire save) |
| 298 | - No indexing (linear scans for save lists) |
| 299 | - File locking for concurrent access (minor issue with single-player) |
| 300 | |
| 301 | ### Optimization Opportunities (Future) |
| 302 | - Cache loaded tribues in-memory with TTL |
| 303 | - Lazy-load kobolds on demand |
| 304 | - Save only changed objects instead of full serialization |
| 305 | - Use MessagePack instead of JSON for binary efficiency |
| 306 | |
| 307 | --- |
| 308 | |
| 309 | ## Backwards Compatibility |
| 310 | |
| 311 | ✅ Public API preserved (with signature updates): |
| 312 | - `Tribe::create()`, `Tribe::load()` exist |
| 313 | - `Kobold.save()` exists (now no-op) |
| 314 | - All game logic unchanged |
| 315 | |
| 316 | ❌ Breaking changes: |
| 317 | - `Tribe::load()` now requires `$userId` parameter |
| 318 | - `Kobold::generate()` now requires `$userId` parameter |
| 319 | - Database queries replaced with SaveManager calls |
| 320 | |
| 321 | --- |
| 322 | |
| 323 | ## Testing Checklist |
| 324 | |
| 325 | - [ ] Create new save → saves to /data/saves/{userId}/{saveId}/ |
| 326 | - [ ] Load save → reads from JSON files |
| 327 | - [ ] List saves → returns correct order by last_played |
| 328 | - [ ] End month → updates save.json with new month/season |
| 329 | - [ ] Food consumption → persists food_count in save.json |
| 330 | - [ ] Delete save → removes /data/saves/{userId}/{saveId}/ directory |
| 331 | - [ ] Multiple saves per user → no conflicts with numeric IDs |
| 332 | - [ ] Offline editing → can modify JSON and load in game |
| 333 | |
| 334 | --- |
| 335 | |
| 336 | ## Future Enhancements |
| 337 | |
| 338 | 1. **Cloud Sync**: Upload saves to server, sync across devices |
| 339 | 2. **Save Versioning**: Keep multiple versions of saves |
| 340 | 3. **Shared Saves**: Allow cooperative play (merge saves) |
| 341 | 4. **Analytics**: Track which saves are most played |
| 342 | 5. **Export Formats**: Convert to CSV, Excel, or other formats |