Twitterature

Twitterature is now a web-first interactive storytelling product: a live character relationship map with real-time timeline control and sandbox plot branching, powered by HTML/CSS/JS + Python (FastAPI).

Monorepo Structure

• app - FastAPI backend (simulation engine + API + static hosting).
• public - Main website frontend (HTML/CSS/JS live map UI).
• tests - API and end-to-end tests.
• apps/TwitteratureApp - legacy SwiftUI client and original demo assets.
• packages/TwitteratureCore - shared data/model artifacts used by the legacy app.
• docs - architecture and product docs.

Web Features

• Real-time draggable character graph (pan + zoom + free node movement).
• Character search and focus mode for fast graph navigation.
• Live timeline playhead with chapter rail, heatmap, and active scene window.
• Dynamic relationship legend + static map legend for all relationship types.
• Sandbox mode with quick links, inline type/strength editing, suggestion engine, and undo/redo history.
• Sandbox descriptions now offer auto-generated suggestion variants based on selected characters, relationship type, chapter, and scene.
• Selected sandbox branches are rendered directly on the graph and prioritized in timeline/story simulation output.
• Animated UI layer: panel entrance, sandbox edge flow, node pulse, and highlighted sandbox events.
• Story pulse now includes narrative-grade explanations: what changed, why it changed, immediate effect, and projected branch impact.
• Modular narrative simulation core with dynamic world/character/relationship state, weighted rule resolution, and event history.
• Live sandbox dynamics: link strength adapts in real time to node movement and current playhead.
• Sandbox scenario presets (save/load/delete) for reusable branching experiments.
• Auto-layout for instant graph cleanup after free dragging.
• Full map localization (RU/UK): work labels, chapters, scenes, character cards, and relationship descriptions.
• Python simulation endpoint recalculating causal factors and event feed.
• Frankenstein demo dataset preloaded and ready at startup.

Tech Stack

• Python 3.9+, FastAPI, SQLAlchemy.
• Vanilla HTML/CSS/JavaScript frontend (no framework lock-in).
• Playwright + Pytest for end-to-end and API testing.

Web: Setup & Run

cd /Users/vlad/twitterature
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

Open:

• http://127.0.0.1:8000/ (live character map website)

Tests

cd /Users/vlad/twitterature
pytest tests/test_api.py -q
python -m playwright install chromium
pytest tests/e2e/test_happy_path.py -q

Demo Data

Primary live-map demo content is loaded from:

• apps/TwitteratureApp/TwitteratureApp/Resources/Demo/demo_work.json
• apps/TwitteratureApp/TwitteratureApp/Resources/Demo/demo_characters.json
• apps/TwitteratureApp/TwitteratureApp/Resources/Demo/demo_relationships.json

API Endpoints

• GET /api/map/works?locale=ru|uk
• GET /api/map/works/{work_id}?locale=ru|uk
• POST /api/map/simulate
  • now powered by the modular simulation core (app/simulation/*) for live state mutation and rule-driven event resolution
• POST /api/simulation/run (structured narrative simulation cycles with optional narration rendering)
• POST /api/summarize (legacy summarization flow)

Simulation Payload Example

{
  "locale": "en",
  "include_narration": true,
  "config": {"cycles": 4, "max_events_per_cycle": 2, "seed": 11},
  "world": {"tension": 0.45, "scarcity": 0.34, "cohesion": 0.52, "uncertainty": 0.55},
  "characters": [{"id": "victor"}, {"id": "creature"}],
  "relationships": [{"source_id": "victor", "target_id": "creature"}]
}

Notes

• No external paid APIs are required for map mode.
• App Store iOS flow remains available in apps/TwitteratureApp, but web is now the default product surface.