{"id":47632472,"url":"https://github.com/kurtxu88/parallel-worlds","last_synced_at":"2026-04-01T23:50:22.646Z","repository":{"id":346174334,"uuid":"1188496666","full_name":"kurtxu88/parallel-worlds","owner":"kurtxu88","description":"Open-source AI storytelling app with Vue, FastAPI, Neo4j, and Postgres.","archived":false,"fork":false,"pushed_at":"2026-03-22T21:17:31.000Z","size":462,"stargazers_count":1,"open_issues_count":13,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-23T07:13:46.548Z","etag":null,"topics":["ai-storytelling","fastapi","interactive-fiction","neo4j","open-source","postgres","vue","worldbuilding"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kurtxu88.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-22T06:43:37.000Z","updated_at":"2026-03-22T21:16:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kurtxu88/parallel-worlds","commit_stats":null,"previous_names":["kurtxu88/parallel-worlds"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/kurtxu88/parallel-worlds","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kurtxu88%2Fparallel-worlds","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kurtxu88%2Fparallel-worlds/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kurtxu88%2Fparallel-worlds/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kurtxu88%2Fparallel-worlds/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kurtxu88","download_url":"https://codeload.github.com/kurtxu88/parallel-worlds/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kurtxu88%2Fparallel-worlds/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31293123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-storytelling","fastapi","interactive-fiction","neo4j","open-source","postgres","vue","worldbuilding"],"created_at":"2026-04-01T23:50:21.969Z","updated_at":"2026-04-01T23:50:22.634Z","avatar_url":"https://github.com/kurtxu88.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Parallel Worlds\n\n[English](./README.md) | [中文说明](./README.zh-CN.md) | [中文贡献指南](./CONTRIBUTING.zh-CN.md) | [中文排障指南](./docs/troubleshooting.zh-CN.md)\n\n[![CI](https://github.com/kurtxu88/parallel-worlds/actions/workflows/ci.yml/badge.svg)](https://github.com/kurtxu88/parallel-worlds/actions/workflows/ci.yml)\n[![Release Drafter](https://github.com/kurtxu88/parallel-worlds/actions/workflows/release-drafter.yml/badge.svg)](https://github.com/kurtxu88/parallel-worlds/actions/workflows/release-drafter.yml)\n[![Release](https://github.com/kurtxu88/parallel-worlds/actions/workflows/release.yml/badge.svg)](https://github.com/kurtxu88/parallel-worlds/actions/workflows/release.yml)\n[![GitHub stars](https://img.shields.io/github/stars/kurtxu88/parallel-worlds?style=social)](https://github.com/kurtxu88/parallel-worlds/stargazers)\n\n![Parallel Worlds social card](./apps/web/public/social-card.svg)\n\nParallel Worlds is an open-source AI storytelling app for building playable worlds from short narrative seeds.\n\n\u003e 中文贡献者也欢迎直接参与。\n\u003e 快速入口：\n\u003e [中文 README](./README.zh-CN.md) |\n\u003e [中文贡献指南](./CONTRIBUTING.zh-CN.md) |\n\u003e [中文排障指南](./docs/troubleshooting.zh-CN.md) |\n\u003e [中文 Bug 模板](https://github.com/kurtxu88/parallel-worlds/issues/new?template=bug_report.zh-CN.yml) |\n\u003e [中文功能建议模板](https://github.com/kurtxu88/parallel-worlds/issues/new?template=feature_request.zh-CN.yml) |\n\u003e [中文世界展示模板](https://github.com/kurtxu88/parallel-worlds/issues/new?template=showcase.zh-CN.yml)\n\nCurrent release line: `v0.1.0`\n\nIt uses Vue, FastAPI, Neo4j OSS, and Postgres to support a tight loop:\n\n- create a world seed\n- generate the world asynchronously in a worker\n- enter the world and play through streamed interactions\n- restore prior sessions from stored event history\n- save language and theme preferences for a guest identity\n\nThis repository does not include the private product history. It is a fresh public codebase with its own structure and git history, designed to keep shipping in public.\n\n## Why This Project Exists\n\nMost AI story demos stop at one-shot generation. Parallel Worlds is trying to keep the world itself alive:\n\n- Postgres stores users, stories, settings, and event history\n- Neo4j stores the world graph used during play\n- the API and worker stay separate so generation and play can evolve independently\n- guest mode keeps the open-source version easy to run locally\n\nIf you care about open-source story engines, graph-backed narrative systems, or small full-stack AI products that are actually hackable, this project is for you.\n\n## Project Status\n\nParallel Worlds is in an active early public phase.\n\n- The current release is a focused v1\n- The roadmap is intentionally small and shippable\n- New improvements should make the project easier to run, easier to demo, and easier to extend\n\nSee [Roadmap](./docs/roadmap.md) for the current direction.\n\n## Stack\n\n- `apps/web`: Vue 3 + Vite\n- `apps/api`: FastAPI API and gameplay endpoint\n- `workers/story-generator`: async world generation worker\n- `db/postgres`: relational schema for stories, events, and settings\n- `db/neo4j`: graph storage notes for generated world data\n- `docker-compose.yml`: local development stack\n\n## Current Scope\n\nIncluded in v1:\n\n- guest session creation\n- personal world list\n- async generation worker\n- streamed play sessions\n- history restore\n- language/theme settings\n- opt-in public share pages for individual worlds\n\nNot included in v1:\n\n- public world marketplace\n- invitations\n- email/password auth\n- hosted deployment defaults\n\n## Quick Start\n\nRequirements:\n\n- Docker\n- an `OPENAI_API_KEY`\n\n1. Copy the environment template.\n\n```bash\ncp .env.example .env\n```\n\n2. Set `OPENAI_API_KEY` in `.env`.\n\n3. Start the local stack.\n\n```bash\ndocker compose up --build\n```\n\n4. Open the app at [http://localhost:5173](http://localhost:5173).\n\n5. Verify the API at [http://localhost:8000/api/health](http://localhost:8000/api/health).\n\nThe `.env.example` values are Docker Compose friendly by default.\n\n## Try This Seed\n\nUse this example to get a fast first run:\n\n```json\n{\n  \"user_input\": \"An archivist on a drowned moon keeps discovering records of wars that have not happened yet.\",\n  \"gender_preference\": \"female\",\n  \"culture_language\": \"en-US\"\n}\n```\n\nYou can also deep-link directly into a starter seed page such as `/create?seed=drowned-moon`.\nIf you enable sharing while creating a world, you can also publish it at `/share/\u003cstory-id\u003e`.\nPublished worlds can also be browsed from the public discovery feed at `/discover`.\n\n## Guest Mode\n\nThe open-source release uses guest mode by default.\n\n- No Supabase\n- No hosted auth\n- No email signup\n- No invitation system\n\nThe frontend requests `POST /api/session/guest` once, stores the returned `guest_user_id` locally, and sends it back through `X-User-Id`.\nPublic world pages are optional and opt-in per story, and shared worlds can be browsed through `/discover`.\n\n## Environment Variables\n\nRequired for world generation:\n\n- `OPENAI_API_KEY`\n- `NEO4J_URI`\n- `NEO4J_USERNAME`\n- `NEO4J_PASSWORD`\n\nRequired for story/event/settings storage:\n\n- `DATABASE_URL`\n\nFrontend:\n\n- `VITE_API_BASE_URL`\n- `VITE_PUBLIC_SITE_URL` for canonical and social preview URLs in production\n\nSee `.env.example` for local defaults.\n\n## Local Development\n\nFrontend only:\n\n```bash\ncd apps/web\nnpm install\nnpm run dev\n```\n\nAPI only:\n\n```bash\ncd apps/api\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\nexport DATABASE_URL=postgresql://parallel_worlds:parallel_worlds@localhost:5432/parallel_worlds\nexport NEO4J_URI=bolt://localhost:7687\nuvicorn main:app --reload\n```\n\nWorker only:\n\n```bash\ncd workers/story-generator\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\nexport DATABASE_URL=postgresql://parallel_worlds:parallel_worlds@localhost:5432/parallel_worlds\nexport NEO4J_URI=bolt://localhost:7687\npython3 worker.py\n```\n\n## Repo Layout\n\n```text\nparallel-worlds/\n  apps/\n    api/\n    web/\n  workers/\n    story-generator/\n  db/\n    postgres/\n    neo4j/\n  docs/\n  examples/\n  deploy/\n    optional/\n```\n\n## Docs\n\n- [Architecture](./docs/architecture.md)\n- [Roadmap](./docs/roadmap.md)\n- [Growth Playbook](./docs/growth-playbook.md)\n- [Demo Script](./docs/demo-script.md)\n- [Launch Checklist](./docs/launch-checklist.md)\n- [Troubleshooting](./docs/troubleshooting.md)\n- [Release Process](./docs/release-process.md)\n- [Chinese README](./README.zh-CN.md)\n- [Contributing](./CONTRIBUTING.md)\n- [Chinese Contributing Guide](./CONTRIBUTING.zh-CN.md)\n- [Security](./SECURITY.md)\n- [Chinese Security Policy](./SECURITY.zh-CN.md)\n\n## Contributing\n\nSmall, focused improvements are the best fit right now.\n\n- onboarding and developer experience\n- API and worker reliability\n- tests around the create -\u003e generate -\u003e play loop\n- UI clarity during story creation and recovery\n\nUse the repo templates to open a [bug report](https://github.com/kurtxu88/parallel-worlds/issues/new?template=bug_report.yml), [feature request](https://github.com/kurtxu88/parallel-worlds/issues/new?template=feature_request.yml), or [world showcase](https://github.com/kurtxu88/parallel-worlds/issues/new?template=showcase.yml).\nYou can also browse [good first issues](https://github.com/kurtxu88/parallel-worlds/labels/good%20first%20issue), [help wanted tasks](https://github.com/kurtxu88/parallel-worlds/labels/help%20wanted), and [showcase posts](https://github.com/kurtxu88/parallel-worlds/labels/showcase).\n\nIf this direction is useful to you, starring the repo helps more people discover it.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkurtxu88%2Fparallel-worlds","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkurtxu88%2Fparallel-worlds","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkurtxu88%2Fparallel-worlds/lists"}