BlueGit

blue-star tribegen

Files

tribegen / web / docs / FILE_BASED_ARCHITECTURE.md

FILE_BASED_ARCHITECTURE.md

various fixes
timfa Tim · pushed by timfa · 9 months ago
49730f61 History
FILE_BASED_ARCHITECTURE.md 9.5 KiB Download Raw

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() exist
  • Kobold.save() exists (now no-op)
  • All game logic unchanged

❌ Breaking changes:

  • Tribe::load() now requires $userId parameter
  • Kobold::generate() now requires $userId parameter
  • 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```
15tribegen/
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
68new Tribe($saveId)
69Tribe::create($userId, $saveName)
70Tribe::load($saveId)
71$tribe->save() // Used database
72```
73
74**After:**
75```php
76new Tribe($userId, $saveId, $name)
77Tribe::create($userId, $saveName) // Auto-generates saveId via SaveManager
78Tribe::load($userId, $saveId) // Requires userId
79$tribe->save() // Saves to JSON files
80```
81
82### Kobold
83
84**Before:**
85```php
86new Kobold($id, $saveId, $name, $age, $spriteMorph)
87Kobold::generate($saveId, $age)
88$kobold->save() // Database INSERT/UPDATE
89$kobold->addInjury($type, $category, $severity) // Database INSERT
90```
91
92**After:**
93```php
94new Kobold($id, $userId, $saveId, $name, $age, $spriteMorph)
95Kobold::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
106new Item($id, $saveId, $name, $description, $itemType)
107// Loaded modifications from database via constructor
108```
109
110**After:**
111```php
112new Item($id, $saveId, $name, $description, $itemType, $statModifications)
113Item::fromArray($data) // Create from JSON
114$item->toArray() // Serialize to JSON
115```
116
117### NPC
118
119**Before:**
120```php
121NPC::create($saveId, $name, $npcType, $isRival) // Database INSERT
122NPC::load($id) // Database SELECT
123$npc->save() // Database UPDATE
124```
125
126**After:**
127```php
128NPC::create($saveId, $name, $npcType, $isRival) // Generates uniqid
129NPC::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
138User::register($email, $password) // Still uses database
139User::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
149class 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
172users
173saves
174kobolds
175injuries
176items
177kobold_items
178item_modifications
179events_enabled
180injuries_enabled
181npcs
182-- (plus other tables)
183```
184
185### After (1 table)
186```sql
187users (id, email, password_hash, created_at)
188```
189
190All 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
220SELECT * FROM saves WHERE user_id = ? ORDER BY last_played DESC
221```
222
223**After:**
224```php
225SaveManager.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
234SELECT * FROM saves WHERE id = ?
235SELECT * FROM kobolds WHERE save_id = ?
236-- Multiple queries with JOINs
237```
238
239**After:**
240```php
241Tribe::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
251If 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");
259foreach ($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
2781. **SaveManager Abstraction**: All file I/O goes through one class for consistency
2792. **Numeric Save IDs**: Simple incrementing IDs (1, 2, 3...) per user
2803. **Array Serialization**: Kobolds/Items/NPCs stored as JSON arrays, not individual files
2814. **No Foreign Keys**: JSON doesn't enforce relationships; parent_id/mother_id are simple strings
2825. **Uniqid for PKs**: No auto-increment in JSON; use `uniqid('prefix_')` for unique IDs
2836. **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
3381. **Cloud Sync**: Upload saves to server, sync across devices
3392. **Save Versioning**: Keep multiple versions of saves
3403. **Shared Saves**: Allow cooperative play (merge saves)
3414. **Analytics**: Track which saves are most played
3425. **Export Formats**: Convert to CSV, Excel, or other formats