Initial commit

2025-10-11 21:21:36 +01:00
commit eccd456c59
29 changed files with 5375 additions and 0 deletions
--- a/docs/planning/NEXT_STEPS.md
+++ b/docs/planning/NEXT_STEPS.md
@@ -0,0 +1,390 @@
+# 🚀 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