Initial commit
This commit is contained in:
Aodhan Collins
525
docs/planning/PROJECT_PLAN.md
Normal file
525
docs/planning/PROJECT_PLAN.md
Normal file
@@ -0,0 +1,525 @@
|
||||
# 🎭 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
|
||||
Reference in New Issue
Block a user