storyteller/docs/planning/PROJECT_PLAN.md

# 🎭 Storyteller RPG - Project Plan

## Vision
Transform the application into a full-featured RPG platform with multiple user roles, AI automation, and comprehensive game management capabilities.

---

## 📋 Phase 1: User Roles & Authentication System

### 1.1 Backend Infrastructure
- [ ] **User Model & Authentication**
  - Implement user registration/login system
  - Add JWT token-based authentication
  - User profile management
  - Session management with user association

- [ ] **Role-Based Access Control (RBAC)**
  - Define role hierarchy: Admin > Gamemaster > Storyteller > Player
  - Create permission decorators for API endpoints
  - Implement role checking middleware
  - Role assignment system

- [ ] **Database Integration**
  - Replace in-memory storage with persistent database (SQLite/PostgreSQL)
  - User table schema
  - Game/Session table schema
  - Character/Player table schema with user association
  - Message history with ownership tracking

**Estimated Time:** 1-2 weeks

**Technical Stack:**
```python
# Backend additions needed:
- SQLAlchemy (ORM)
- JWT (python-jose)
- Password hashing (passlib)
- Database (SQLite for dev, PostgreSQL for prod)
```

---

## 📋 Phase 2: Game Creation & Management System

### 2.1 Game Configuration
- [ ] **Game Creation Interface**
  - Game setup wizard for Gamemaster
  - Configure game settings:
    - Game name & description
    - Scenario/setting details
    - Number of player slots
    - Storyteller assignment (human/AI)
  - LLM model selection per role
  - Game state management (not started, in progress, paused, completed)

- [ ] **Role Assignment System**
  - Player slot management
  - Assign slots to:
    - Human users (invite by username/email)
    - AI players (configure personality & LLM)
  - Storyteller assignment (human or AI)
  - Role transfer/reassignment

- [ ] **Game Lobby**
  - Pre-game waiting room
  - Player slot status display
  - Ready/not ready indicators
  - Game start conditions

**Estimated Time:** 2 weeks

**UI Components:**
```
- GameCreationWizard.js
- RoleAssignmentPanel.js
- GameLobby.js
- PlayerSlotCard.js
```

---

## 📋 Phase 3: User Mode Interfaces

### 3.1 Player Mode
- [ ] **Player Interface**
  - View own character sheet
  - Private messaging with storyteller
  - View scene descriptions
  - Message history (own messages only)
  - Cannot edit storyteller responses
  - Can generate/edit/write own responses

- [ ] **Player Controls**
  - Message composer with AI generation option
  - Edit own messages (before storyteller reads)
  - Character action commands
  - Inventory/stats display (if applicable)

**Permissions:**
```
✅ Read: Own messages, storyteller responses to self, scene narrations
✅ Write: Own character messages
✅ Edit: Own unread messages
❌ Edit: Storyteller responses, other players' messages
```

### 3.2 Storyteller Mode
- [ ] **Storyteller Dashboard**
  - View all player messages
  - Player list with status indicators
  - Response composer per player
  - Scene narration composer
  - AI player response generation/editing

- [ ] **Storyteller Controls**
  - Generate responses with AI assist (per player's LLM)
  - Edit AI-generated responses before sending
  - Manage AI players completely
  - Broadcast scene narrations
  - View conversation history per player

**Permissions:**
```
✅ Read: All player messages, all game state
✅ Write: Responses to players, scene narrations
✅ Edit: Own responses, AI player messages
❌ Edit: Human player messages
✅ Generate: AI responses for any player
```

### 3.3 Gamemaster Mode
- [ ] **Gamemaster Control Panel**
  - Overview of entire game state
  - All player & storyteller message threads
  - Game configuration management
  - Player/role management
  - AI behavior controls

- [ ] **Gamemaster Powers**
  - Send messages to any player
  - Edit AI responses (storyteller or players)
  - Pause/resume game
  - Modify game settings mid-game
  - View all LLM usage/costs
  - Generate content with any LLM

**Permissions:**
```
✅ Read: Everything
✅ Write: Messages to anyone
✅ Edit: AI responses (storyteller & players)
❌ Edit: Human responses (storyteller & players)
✅ Configure: Game settings, roles, LLMs
✅ Control: AI automation, game flow
```

### 3.4 Admin Mode (Development)
- [ ] **Admin Dashboard**
  - System-wide overview
  - All games management
  - User management
  - LLM configuration & monitoring
  - Cost tracking & analytics

- [ ] **Admin Powers**
  - Full edit access to everything
  - View/modify all LLMs in use
  - System configuration
  - Debug tools
  - Performance monitoring

**Permissions:**
```
✅ Full Access: Everything, no restrictions
```

**Estimated Time:** 3-4 weeks

---

## 📋 Phase 4: AI Automation System

### 4.1 AI Player System
- [ ] **AI Player Engine**
  - Automated message generation based on:
    - Character personality/backstory
    - Recent conversation context
    - Scene descriptions
    - Game scenario
  - Configurable response triggers:
    - Time-based (respond every N seconds)
    - Event-based (respond to storyteller)
    - Manual trigger (Gamemaster/Storyteller control)

- [ ] **AI Player Configuration**
  - Personality templates
  - Response style settings
  - Behavior patterns (cautious, bold, curious, etc.)
  - LLM model selection per AI player
  - Temperature/creativity settings

### 4.2 AI Storyteller System
- [ ] **AI Storyteller Engine**
  - Automated storytelling based on:
    - Game scenario/plot
    - Player actions
    - Story progression rules
    - Scene templates
  - Response generation for each player
  - Scene narration generation

- [ ] **AI Storyteller Configuration**
  - Storytelling style (descriptive, action-focused, dialogue-heavy)
  - Plot progression speed
  - Challenge difficulty
  - LLM model selection
  - Context window management

### 4.3 Automation Controls
- [ ] **Manual Override System**
  - Human can take over from AI at any time
  - AI can be paused/resumed
  - Edit AI responses before sending
  - Review mode (AI generates, human approves)

- [ ] **Automation Triggers**
  - Configurable response timing
  - Event-based triggers
  - Turn-based mode support
  - Real-time mode support

**Estimated Time:** 2-3 weeks

**Technical Implementation:**
```python
# Backend components:
- AIPlayerEngine class
- AIStorytellerEngine class  
- AutomationScheduler
- ResponseGenerator with context management
- Trigger system for automated responses
```

---

## 📋 Phase 5: Enhanced Features

### 5.1 Message Management
- [ ] **Message Editing System**
  - Edit history tracking
  - Permissions enforcement
  - Real-time sync of edits
  - Visual indicators for edited messages

- [ ] **Message Generation**
  - AI-assisted writing for all roles
  - Prompt templates library
  - Context-aware suggestions
  - Multi-model comparison

### 5.2 Game State Management
- [ ] **Save/Load System**
  - Export game state
  - Import saved games
  - Game snapshots/checkpoints
  - Rewind to previous state

- [ ] **Turn Management** (Optional)
  - Turn-based gameplay option
  - Turn order configuration
  - Turn timer
  - Turn history

### 5.3 Analytics & Monitoring
- [ ] **Usage Tracking**
  - LLM usage per game
  - Cost tracking per model
  - Response time metrics
  - Player engagement analytics

- [ ] **Game Insights**
  - Conversation flow visualization
  - Player participation metrics
  - Story progression tracking
  - AI vs Human response statistics

**Estimated Time:** 2 weeks

---

## 📋 Phase 6: Polish & Deployment

### 6.1 UI/UX Refinement
- [ ] Responsive design for all modes
- [ ] Mobile-friendly interfaces
- [ ] Accessibility improvements
- [ ] Theme customization

### 6.2 Testing
- [ ] Unit tests for all components
- [ ] Integration tests
- [ ] Role permission tests
- [ ] Load testing

### 6.3 Documentation
- [ ] User guides per role
- [ ] API documentation
- [ ] Deployment guide
- [ ] Developer documentation

### 6.4 Deployment
- [ ] Production environment setup
- [ ] Database migration system
- [ ] CI/CD pipeline
- [ ] Monitoring & logging

**Estimated Time:** 2 weeks

---

## 🗓️ Timeline Summary

| Phase | Description | Duration | Status |
|-------|-------------|----------|--------|
| **Phase 0** | Current MVP | - | ✅ Complete |
| **Phase 1** | User Roles & Auth | 1-2 weeks | 🔄 Planning |
| **Phase 2** | Game Management | 2 weeks | ⏳ Pending |
| **Phase 3** | User Modes | 3-4 weeks | ⏳ Pending |
| **Phase 4** | AI Automation | 2-3 weeks | ⏳ Pending |
| **Phase 5** | Enhanced Features | 2 weeks | ⏳ Pending |
| **Phase 6** | Polish & Deploy | 2 weeks | ⏳ Pending |
| **Total** | | **12-15 weeks** | |

---

## 🏗️ Technical Architecture Changes

### Current Architecture
```
Frontend (React) ←→ Backend (FastAPI) ←→ In-Memory Storage
                     WebSockets
```

### Target Architecture
```
Frontend (React)
    ├── Player Interface
    ├── Storyteller Interface
    ├── Gamemaster Interface
    └── Admin Interface
         ↕
    API Gateway (FastAPI)
    ├── Authentication Layer (JWT)
    ├── Authorization Layer (RBAC)
    └── WebSocket Manager
         ↕
    Business Logic
    ├── Game Engine
    ├── AI Player Engine
    ├── AI Storyteller Engine
    └── Automation Scheduler
         ↕
    Data Layer
    ├── Database (PostgreSQL)
    ├── Redis (Caching/Sessions)
    └── File Storage (Game States)
         ↕
    External Services
    ├── OpenAI API
    ├── OpenRouter API
    └── Analytics Service
```

---

## 📦 New Dependencies Needed

### Backend
```python
# requirements.txt additions
sqlalchemy==2.0.23          # ORM
alembic==1.13.0             # Database migrations
psycopg2-binary==2.9.9      # PostgreSQL driver
python-jose[cryptography]   # JWT (already added, needs activation)
passlib[bcrypt]             # Password hashing (already added, needs activation)
redis==5.0.1                # Caching & session management
celery==5.3.4               # Task queue for AI automation
pydantic-settings==2.1.0    # Settings management
```

### Frontend
```json
// package.json additions
"@tanstack/react-query": "^5.0.0",  // Data fetching
"zustand": "^4.4.0",                 // State management
"react-router-dom": "^6.20.0",       // Routing (if not added)
"react-hook-form": "^7.48.0",        // Form management
"zod": "^3.22.0",                    // Schema validation
"recharts": "^2.10.0",               // Analytics charts
"@dnd-kit/core": "^6.1.0"            // Drag-and-drop for role assignment
```

---

## 🎯 Success Criteria

### Phase 1 Complete When:
- ✅ Users can register/login
- ✅ Role-based access works
- ✅ Database stores all game data persistently

### Phase 2 Complete When:
- ✅ Gamemaster can create games
- ✅ Can assign humans/AI to roles
- ✅ Game lobby works with ready states

### Phase 3 Complete When:
- ✅ All 4 user modes functional
- ✅ Permissions enforced correctly
- ✅ UI matches role capabilities

### Phase 4 Complete When:
- ✅ AI players respond automatically
- ✅ AI storyteller can run full games
- ✅ Human override works seamlessly

### Phase 5 Complete When:
- ✅ Message editing works with permissions
- ✅ Save/load system functional
- ✅ Analytics dashboard complete

### Phase 6 Complete When:
- ✅ App deployed to production
- ✅ All tests passing
- ✅ Documentation complete

---

## 🚀 Getting Started - Phase 1

### Immediate Next Steps:
1. **Database Setup**
   ```bash
   pip install sqlalchemy alembic psycopg2-binary
   alembic init migrations
   ```

2. **Create Database Models**
   - User model with roles
   - Game model
   - Character model with user_id
   - Message model with ownership

3. **Implement Authentication**
   - JWT token generation
   - Login/register endpoints
   - Protected routes

4. **Update Frontend**
   - Login/register pages
   - Auth state management
   - Protected route wrapper

### Priority Tasks for Phase 1:
1. Database schema design
2. User authentication system
3. Role assignment logic
4. Update existing session system to use database

---

## 📝 Notes & Considerations

### Key Design Decisions:
- **Database:** PostgreSQL for production, SQLite for development
- **Auth:** JWT tokens with refresh mechanism
- **Real-time:** Continue using WebSockets, add auth to connections
- **AI Queue:** Celery for handling automated AI responses
- **Caching:** Redis for session data and frequently accessed game state

### Challenges to Address:
- **Race Conditions:** Multiple users editing same game state
- **AI Cost Control:** Budget limits per game/user
- **Scalability:** Support for multiple concurrent games
- **Context Management:** LLM context windows for long games
- **Latency:** AI response generation can be slow

### Future Enhancements (Post-MVP):
- Voice chat integration
- Character sheet system with stats/inventory
- Dice rolling system
- Battle/combat system
- Campaign management (multi-session games)
- Marketplace for game scenarios
- Community features (forums, game discovery)

---

## 🤝 Development Workflow

### Branching Strategy:
```
main (production)
├── develop (integration)
    ├── feature/phase1-auth
    ├── feature/phase2-game-creation
    ├── feature/phase3-player-mode
    └── feature/phase4-ai-automation
```

### Testing Strategy:
- Unit tests for all new backend functions
- Integration tests for API endpoints
- E2E tests for critical user flows
- Load tests for AI automation

### Code Review Process:
- All features require PR review
- Test coverage minimum: 80%
- Documentation required for new features

---

**Last Updated:** 2025-10-11  
**Next Review:** Start of Phase 1