storyteller/docs/planning/NEXT_STEPS.md

🚀 Next Steps for Storyteller RPG

Immediate Improvements (Quick Wins)

1. AI-Assisted Storyteller Responses

Priority: High | Effort: Low

• Backend endpoint exists (/sessions/{session_id}/generate_suggestion)
• Add "✨ AI Suggest" button to StorytellerView response textarea
• Show suggested response that storyteller can edit before sending
• Allow storyteller to regenerate if they don't like the suggestion

Implementation:

// In StorytellerView.js - Add button next to "Send Private Response"
const getSuggestion = async () => {
  const response = await fetch(
    `${API_URL}/sessions/${sessionId}/generate_suggestion?character_id=${selectedCharacter}`,
    { method: 'POST' }
  );
  const data = await response.json();
  setResponseText(data.suggestion);
};

2. Session Persistence

Priority: High | Effort: Medium

Currently, sessions exist only in memory. Add database storage:

Option A: SQLite (Simplest)

pip install sqlalchemy aiosqlite

Option B: PostgreSQL (Production-ready)

pip install sqlalchemy asyncpg psycopg2-binary

Files to modify:

• Create database.py for SQLAlchemy models
• Update main.py to use database instead of sessions: Dict
• Add session persistence on server restart

3. Better UI/UX Enhancements

Priority: Medium | Effort: Low

• Add typing indicators ("Storyteller is typing...")
• Add sound notifications for new messages
• Add markdown support in messages (bold, italic, etc.)
• Add character avatars (emoji selector or image upload)
• Add "Export conversation" button (save as JSON/text)
• Show timestamp for when character joined
• Add "Last active" indicator for characters

4. Dice Rolling System

Priority: Medium | Effort: Medium

Add RPG dice mechanics:

// New component: DiceRoller.js
const rollDice = (notation) => {
  // Parse notation like "2d6+3", "1d20", etc.
  // Return result and show animation
};

Features:

• Character can request roll from storyteller
• Storyteller sees roll request and can approve
• Results visible to storyteller only (or optionally to character)
• Support for various dice (d4, d6, d8, d10, d12, d20, d100)

Medium-Term Features

5. Character Sheets & Stats

Priority: Medium | Effort: High

Add RPG character management:

# In main.py - extend Character model
class CharacterStats(BaseModel):
    health: int = 100
    max_health: int = 100
    attributes: Dict[str, int] = {}  # Strength, Dex, etc.
    inventory: List[str] = []
    skills: List[str] = []

UI:

• Character view shows their stats in a sidebar
• Storyteller can edit character stats
• Add stat modification history/log

6. Image Generation Integration

Priority: Medium | Effort: Medium

Integrate DALL-E or Stable Diffusion:

# New endpoint in main.py
@app.post("/sessions/{session_id}/generate_image")
async def generate_scene_image(scene_description: str):
    # Use OpenAI DALL-E or Replicate Stable Diffusion
    # Return image URL
    pass

Use cases:

• Generate scene illustrations
• Create character portraits
• Visualize items or locations

7. Multiple Storytellers / Co-GMs

Priority: Low | Effort: Medium

Allow multiple storytellers in one session:

• One primary storyteller
• Assistant storytellers can respond to characters
• Storytellers can see each other's responses
• Add permission system

8. Group Conversations

Priority: Medium | Effort: Medium

Allow characters to talk to each other (not just storyteller):

class ConversationChannel(BaseModel):
    id: str
    name: str  # "Party Chat", "Private: Alice & Bob"
    participants: List[str]  # character_ids
    messages: List[Message] = []

Features:

• Storyteller creates channels
• Characters can be added/removed from channels
• Storyteller can see all channels (but optionally hide from other characters)

Advanced Features

9. Voice Integration

Priority: Low | Effort: High

Add voice chat or text-to-speech:

Option A: Text-to-Speech

# Use OpenAI TTS or ElevenLabs
@app.post("/tts")
async def text_to_speech(text: str, voice: str):
    # Generate audio from text
    pass

Option B: Real-time Voice

• Integrate WebRTC for voice channels
• Voice-to-text for automatic transcription
• Character AI can speak responses

10. Campaign Management

Priority: Medium | Effort: High

Add multi-session campaign support:

class Campaign(BaseModel):
    id: str
    name: str
    sessions: List[str]  # session_ids
    characters: Dict[str, Character]  # Persistent across sessions
    world_state: Dict[str, Any]  # Locations, NPCs, quests

11. AI NPCs

Priority: Medium | Effort: Medium

Storyteller can create AI-controlled NPCs:

class NPC(BaseModel):
    id: str
    name: str
    description: str
    ai_controlled: bool = True
    llm_model: str = "gpt-3.5-turbo"

Features:

• NPCs have their own LLM sessions
• NPCs can respond to character messages
• Storyteller can override/edit NPC responses
• NPCs remember previous interactions

12. Combat System

Priority: Low | Effort: High

Add turn-based combat:

• Initiative tracking
• Action queue
• Status effects
• Health/damage tracking
• Combat log visible to all participants

Infrastructure Improvements

13. Authentication & User Accounts

Priority: High | Effort: High

Add user system:

pip install python-jose[cryptography] passlib[bcrypt]

Features:

• User registration/login
• OAuth support (Google, Discord)
• User owns their characters
• User can be storyteller for multiple campaigns
• Session access control

14. Database Migration

Priority: High | Effort: Medium

Current: In-memory storage Target: PostgreSQL or MongoDB

Why:

• Persist sessions across restarts
• Scale to multiple servers
• Backup and recovery
• Query optimization

15. API Rate Limiting

Priority: Medium | Effort: Low

Prevent abuse:

from slowapi import Limiter
from slowapi.util import get_remote_address

limiter = Limiter(key_func=get_remote_address)
app.state.limiter = limiter

@app.post("/sessions/")
@limiter.limit("10/minute")
async def create_session(...):
    pass

16. WebSocket Reconnection

Priority: Medium | Effort: Medium

Handle disconnections gracefully:

• Auto-reconnect on connection loss
• Queue messages while disconnected
• Sync state on reconnection
• Show connection status prominently

17. Mobile App

Priority: Low | Effort: Very High

Build native mobile apps:

Option A: React Native

• Reuse React components
• iOS + Android from one codebase

Option B: Progressive Web App (PWA)

• Add service worker
• Offline support
• Add to home screen
• Push notifications

18. Testing Suite

Priority: High | Effort: Medium

Add comprehensive tests:

# Backend tests
pip install pytest pytest-asyncio httpx

# Frontend tests (already have Jest)
cd frontend
npm test

Coverage:

• Unit tests for message routing
• Integration tests for WebSocket connections
• End-to-end tests for full user flows
• Load testing for concurrent sessions

Polish & Quality of Life

19. Better Error Handling

• Show user-friendly error messages
• Add retry logic for failed API calls
• Graceful degradation when LLM API is down
• Better validation on all inputs

20. Accessibility

• Add keyboard navigation
• Screen reader support
• High contrast mode
• Font size controls
• Color blind friendly themes

21. Internationalization (i18n)

• Support multiple languages
• Translate UI elements
• LLM can respond in user's language

22. Analytics & Monitoring

• Track session duration
• Monitor WebSocket health
• LLM API usage and costs
• User engagement metrics

Documentation

23. API Documentation

• Add Swagger/OpenAPI docs (FastAPI auto-generates this)
• Document WebSocket message formats
• Add code examples for all endpoints

24. Tutorial System

• In-app tutorial for new users
• Video guides
• Example campaign/scenario
• Best practices guide for storytellers

Prioritized Roadmap

Phase 1: Core Stability (1-2 weeks)

1. ✅ AI-assisted storyteller responses (UI hookup)
2. ✅ Database persistence (SQLite or PostgreSQL)
3. ✅ Better error handling
4. ✅ WebSocket reconnection

Phase 2: Enhanced Gameplay (2-3 weeks)

5. ✅ Dice rolling system
6. ✅ Character sheets & stats
7. ✅ Typing indicators
8. ✅ Export conversations

Phase 3: Rich Features (3-4 weeks)

9. ✅ Image generation
10. ✅ Group conversations
11. ✅ AI NPCs
12. ✅ Authentication system

Phase 4: Scale & Polish (2-3 weeks)

13. ✅ Production database
14. ✅ Testing suite
15. ✅ Mobile PWA
16. ✅ Campaign management

Quick Wins to Start With

If you're continuing development, I recommend starting with:

1. Add AI Suggest button (30 mins) - The backend already supports it!
2. Add typing indicators (1 hour) - Great UX improvement
3. Session persistence (3-4 hours) - Prevents data loss
4. Dice roller (2-3 hours) - Core RPG feature
5. Export conversations (1 hour) - Users will love this

Notes for Future Development

• All WebSocket messages use JSON format with a type field
• Character conversations are stored in Character.conversation_history
• Each character has their own LLM model configurable at creation
• Frontend uses native WebSocket (not socket.io despite the package.json)
• Backend runs on port 8000, frontend on port 3000
• CORS is wide open for development - restrict in production!

Getting Help

• FastAPI docs: https://fastapi.tiangolo.com/
• React docs: https://react.dev/
• OpenAI API: https://platform.openai.com/docs
• OpenRouter: https://openrouter.ai/docs
• WebSocket guide: https://developer.mozilla.org/en-US/docs/Web/API/WebSocket