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:

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

# 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

# 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

// 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

   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