storyteller/docs/planning/NEXT_STEPS.md

# 🚀 Next Steps for Storyteller RPG

## Immediate Improvements (Quick Wins)

### 1. AI-Assisted Storyteller Responses
**Priority: High | Effort: Low**
- [x] 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:**
```javascript
// 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)**
```bash
pip install sqlalchemy aiosqlite
```

**Option B: PostgreSQL (Production-ready)**
```bash
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:

```javascript
// 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:

```python
# 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:

```python
# 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):

```python
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**
```python
# 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:

```python
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:

```python
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:

```bash
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:

```python
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:

```bash
# 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