Sprint 1: World Export Foundation #3

New issue

Closed

opened 2026-05-19 05:04:48 +00:00 by foravo_admin · 0 comments

foravo_admin commented

2026-05-19 05:04:48 +00:00

Owner

Imported from GitHub issue conorgregson/worldbuilding-codex#26.

Source: https://github.com/conorgregson/worldbuilding-codex/issues/26
Original author: @conorgregson
Original state: closed

Goal

Add the core world export foundation for Worldbuilding Codex v1.4 by allowing users to download a complete JSON backup of one world.

This sprint establishes the export format that later import validation and restore work will use.

Context

v1.4 focuses on world-level import and export.

Sprint 1 covers the export side of that work. Users should be able to export one world they own as a .json file that includes the world and related lore data.

The exported file should be structured enough for Sprint 2 to validate and Sprint 3 to import safely.

Scope

Add an authenticated world export endpoint.
Export one selected world as JSON.
Confirm users can only export worlds they own.
Include world data in the export payload.
Include entities in the export payload.
Include relationships in the export payload.
Include timeline events in the export payload.
Include event participants where available.
Include tags where available.
Include export metadata such as app name, export version, exported timestamp, and source world ID.
Add a frontend export action.
Download the export as a .json file.
Use a readable export filename.
Add export loading and error states.
Confirm export behavior works locally and in production.

Suggested Route Behavior

GET /api/worlds/:worldId/export

The route should:

Require authentication.
Confirm the requested world belongs to the current user.
Return a stable JSON export payload.
Avoid exposing data from worlds owned by other users.

Acceptance Criteria

Users can export a world they own.
Users cannot export a world they do not own.
Exported JSON includes world data.
Exported JSON includes entities.
Exported JSON includes relationships.
Exported JSON includes timeline events.
Exported JSON includes event participants where available.
Exported JSON includes tags where available.
Exported JSON includes export metadata.
Exported JSON uses a stable structure for future import validation.
The frontend includes a clear export action.
The export action downloads a .json file.
The export filename is readable and world-specific where practical.
Export loading and error states are user-friendly.
The export action is keyboard reachable.
The export action is usable on desktop and narrower screens.
No obvious console errors appear during normal export usage.

Verification Checklist

Local Verification

Run frontend build.
Run backend build.
Log in locally.
Open a world with multiple entities, relationships, timeline events, and participants.
Click the export action.
Confirm a .json file downloads.
Open the downloaded file.
Confirm the export includes metadata.
Confirm the export includes world data.
Confirm the export includes entities.
Confirm the export includes relationships.
Confirm the export includes timeline events.
Confirm the export includes event participants where available.
Confirm the export includes tags where available.
Export a sparse world with little or no related data.
Confirm sparse world export does not crash.
Confirm repeated exports work.
Confirm the export action has a loading or disabled state.
Confirm export errors are handled clearly.
Confirm the export action is keyboard reachable.
Confirm the export layout is usable on desktop.
Confirm the export layout is usable on a narrow viewport.
Confirm no obvious console errors appear.

Production Verification

Hosted frontend loads successfully.
Login/authenticated flow works.
World detail page loads in production.
Export action appears in production.
World export downloads a .json file in production.
Production export includes world data.
Production export includes related lore data.
Production export includes metadata.
Sparse world export works in production.
No obvious production console errors appear.

Out of Scope

Import flow.
Import validation.
Import preview.
Confirmed import/save behavior.
ID remapping.
Duplicate world detection.
Merge import behavior.
Selective import behavior.
Exporting all worlds at once.
Public sharing work.
Printable world bible export.
Markdown/PDF export.

Risks / Notes

Export should defensively handle missing or empty related arrays.
Export should not expose data from worlds owned by other users.
Export format should be stable enough for Sprint 2 validation work.
Original database IDs may be useful as source references, but they should not be reused during import.
Relationship and participant data depend on existing response shapes.
Tags should be included if they exist as structured data. If tags are currently embedded on entities, the export should preserve them through entity records.
Large worlds may create larger JSON files, but v1.4 can keep the first version simple unless performance issues appear.

Imported from GitHub issue `conorgregson/worldbuilding-codex#26`. Source: https://github.com/conorgregson/worldbuilding-codex/issues/26 Original author: @conorgregson Original state: closed  --- ## Goal Add the core world export foundation for Worldbuilding Codex v1.4 by allowing users to download a complete JSON backup of one world. This sprint establishes the export format that later import validation and restore work will use. --- ## Context v1.4 focuses on world-level import and export. Sprint 1 covers the export side of that work. Users should be able to export one world they own as a `.json` file that includes the world and related lore data. The exported file should be structured enough for Sprint 2 to validate and Sprint 3 to import safely. --- ## Scope - Add an authenticated world export endpoint. - Export one selected world as JSON. - Confirm users can only export worlds they own. - Include world data in the export payload. - Include entities in the export payload. - Include relationships in the export payload. - Include timeline events in the export payload. - Include event participants where available. - Include tags where available. - Include export metadata such as app name, export version, exported timestamp, and source world ID. - Add a frontend export action. - Download the export as a `.json` file. - Use a readable export filename. - Add export loading and error states. - Confirm export behavior works locally and in production. --- ## Suggested Route Behavior ```txt GET /api/worlds/:worldId/export ``` The route should: - Require authentication. - Confirm the requested world belongs to the current user. - Return a stable JSON export payload. - Avoid exposing data from worlds owned by other users. --- ## Acceptance Criteria - [x] Users can export a world they own. - [x] Users cannot export a world they do not own. - [x] Exported JSON includes world data. - [x] Exported JSON includes entities. - [x] Exported JSON includes relationships. - [x] Exported JSON includes timeline events. - [x] Exported JSON includes event participants where available. - [x] Exported JSON includes tags where available. - [x] Exported JSON includes export metadata. - [x] Exported JSON uses a stable structure for future import validation. - [x] The frontend includes a clear export action. - [x] The export action downloads a .json file. - [x] The export filename is readable and world-specific where practical. - [x] Export loading and error states are user-friendly. - [x] The export action is keyboard reachable. - [x] The export action is usable on desktop and narrower screens. - [x] No obvious console errors appear during normal export usage. --- ## Verification Checklist ### Local Verification - [x] Run frontend build. - [x] Run backend build. - [x] Log in locally. - [x] Open a world with multiple entities, relationships, timeline events, and participants. - [x] Click the export action. - [x] Confirm a .json file downloads. - [x] Open the downloaded file. - [x] Confirm the export includes metadata. - [x] Confirm the export includes world data. - [x] Confirm the export includes entities. - [x] Confirm the export includes relationships. - [x] Confirm the export includes timeline events. - [x] Confirm the export includes event participants where available. - [x] Confirm the export includes tags where available. - [x] Export a sparse world with little or no related data. - [x] Confirm sparse world export does not crash. - [x] Confirm repeated exports work. - [x] Confirm the export action has a loading or disabled state. - [x] Confirm export errors are handled clearly. - [x] Confirm the export action is keyboard reachable. - [x] Confirm the export layout is usable on desktop. - [x] Confirm the export layout is usable on a narrow viewport. - [x] Confirm no obvious console errors appear. ### Production Verification - [x] Hosted frontend loads successfully. - [x] Login/authenticated flow works. - [x] World detail page loads in production. - [x] Export action appears in production. - [x] World export downloads a .json file in production. - [x] Production export includes world data. - [x] Production export includes related lore data. - [x] Production export includes metadata. - [x] Sparse world export works in production. - [x] No obvious production console errors appear. --- ## Out of Scope - Import flow. - Import validation. - Import preview. - Confirmed import/save behavior. - ID remapping. - Duplicate world detection. - Merge import behavior. - Selective import behavior. - Exporting all worlds at once. - Public sharing work. - Printable world bible export. - Markdown/PDF export. --- ## Risks / Notes - Export should defensively handle missing or empty related arrays. - Export should not expose data from worlds owned by other users. - Export format should be stable enough for Sprint 2 validation work. - Original database IDs may be useful as source references, but they should not be reused during import. - Relationship and participant data depend on existing response shapes. - Tags should be included if they exist as structured data. If tags are currently embedded on entities, the export should preserve them through entity records. - Large worlds may create larger JSON files, but v1.4 can keep the first version simple unless performance issues appear.

foravo_admin

2026-05-19 05:04:48 +00:00