# 🎯 Quick Reference - Storyteller RPG

## 📍 Where We Are Now

### ✅ Current Features (Working)
- Basic storyteller-character private messaging
- Real-time WebSocket communication
- Multiple LLM support (GPT-4, Claude, Llama, Gemini, etc.)
- Each character can use different AI model
- Session creation and joining
- Message history per character
- Scene narrations broadcast to all

### 📁 Current File Structure
```
windsurf-project/
├── main.py                 # Backend API (FastAPI + WebSockets)
├── requirements.txt        # Python dependencies
├── .env                    # API keys configuration
├── start.sh               # Startup script (Linux/Mac)
├── start.bat              # Startup script (Windows)
├── frontend/
│   ├── src/
│   │   ├── App.js
│   │   ├── components/
│   │   │   ├── SessionSetup.js
│   │   │   ├── CharacterView.js
│   │   │   └── StorytellerView.js
│   │   └── App.css
│   ├── public/
│   │   └── index.html
│   └── package.json
├── README.md
├── LLM_GUIDE.md           # Guide to available LLMs
├── PROJECT_PLAN.md        # Full project roadmap
└── MVP_ROADMAP.md         # MVP-specific plan
```

---

## 🎯 MVP Goals Summary

### Core User Modes
1. **Player** (Human/AI) - Play a character with profile
2. **Storyteller** (Human/AI) - Run the game, respond to players
3. **Gamemaster** (Human only) - Create/manage games, control AI
4. **Admin** (Dev only) - Full system access

### Key Features for MVP
1. **Public/Private Messages** - Players can have secret actions
2. **Character Profiles** - Race, class, gender, personality
3. **Import/Export** - Save characters as JSON or PNG with metadata
4. **AI Automation** - AI players and storytellers run automatically
5. **Game Management** - Create games, assign roles, save progress
6. **Permission System** - Each role has specific capabilities

---

## 🎭 Character Profile System (MVP)

### Races
- Human (Versatile)
- Elf (Graceful, perceptive)
- Dwarf (Sturdy, loyal)
- Orc (Strong, fierce)
- Halfling (Nimble, lucky)

### Classes
- Warrior (Combat)
- Wizard (Magic)
- Cleric (Healing)
- Archer (Ranged)
- Rogue (Stealth)

### Personalities
- Friendly (Optimistic)
- Serious (Focused)
- Doubtful (Cautious)
- Measured (Balanced)

### Storyteller Styles
- Narrator (3rd person)
- DM (2nd person)
- Internal Thoughts (1st person)

---

## 📋 Permission Matrix

| Action | Player | Storyteller | GM | Admin |
|--------|--------|-------------|-----|-------|
| View own messages | ✅ | ✅ | ✅ | ✅ |
| View public messages | ✅ | ✅ | ✅ | ✅ |
| View private messages | ❌ | ✅ | ✅ | ✅ |
| Edit own messages | ✅ | ✅ | ✅ | ✅ |
| Edit storyteller | ❌ | ✅ | ❌ | ✅ |
| Edit human players | ❌ | ❌ | ❌ | ✅ |
| Edit AI responses | ❌ | ✅ | ✅ | ✅ |
| Create games | ❌ | ❌ | ✅ | ✅ |
| Control AI | ❌ | ✅ | ✅ | ✅ |

---

## 🗺️ 12-Week Implementation Plan

### Weeks 1-2: Message System
- Public/private/mixed message types
- Enhanced message composer
- Visibility controls

### Weeks 3-4: Character Profiles
- Profile creation wizard
- Race/class/personality templates
- Import/export (JSON & PNG)
- Profile-based LLM prompts

### Weeks 5-7: User Modes
- Player interface
- Storyteller dashboard
- Gamemaster control panel
- Permission enforcement

### Weeks 8-9: AI Automation
- AI player system
- AI storyteller system
- Automation controls
- Override mechanisms

### Weeks 10-11: Game Management
- Game creation wizard
- Save/load system
- Database implementation
- Game checkpoints

### Week 12: Polish & Testing
- UI/UX refinement
- Testing suite
- Documentation
- Performance optimization

---

## 🔧 Technology Stack

### Current
- **Backend:** FastAPI, WebSockets, OpenAI/OpenRouter APIs
- **Frontend:** React, WebSocket client
- **Storage:** In-memory (temporary)

### Needed for MVP
- **Database:** SQLAlchemy + PostgreSQL/SQLite
- **Auth:** JWT tokens (python-jose)
- **Image:** Pillow (PNG metadata)
- **Frontend:** react-hook-form, zod, file-saver

---

## 🚀 How to Run (Current)

```bash
# Quick start (kills old instances, starts both servers)
./start.sh

# Manual start
# Terminal 1 - Backend
python main.py

# Terminal 2 - Frontend
cd frontend
npm start
```

**Access:** http://localhost:3000

---

## 📝 Development Notes

### Message Types (New Feature)
```
PUBLIC: "I shake the merchant's hand"
PRIVATE: "I attempt to pickpocket him"
MIXED: Both public and private actions in one message
```

### Character Profile Structure
```json
{
  "name": "Thorin",
  "gender": "Male",
  "race": "Dwarf",
  "class": "Warrior",
  "personality": "Serious",
  "llm_model": "anthropic/claude-3.5-sonnet",
  "custom_prompts": {
    "background": "A grizzled veteran...",
    "response_style": "Speak gruffly and with honor"
  }
}
```

### LLM Prompt Building
```python
# System prompt = Race + Class + Personality + Custom
"You are a Dwarf Warrior with a Serious personality. 
You are stout and honorable. You excel in combat. 
You are focused and pragmatic. Speak gruffly..."
```

---

## 🎯 Phase 1 Starting Point

**First Task:** Implement Public/Private Message System

**Steps:**
1. Update `Message` model in `main.py`:
   ```python
   class Message(BaseModel):
       visibility: str  # "public", "private", "mixed"
       public_content: Optional[str]
       private_content: Optional[str]
   ```

2. Create message type selector in `CharacterView.js`:
   ```jsx
   <select onChange={handleVisibilityChange}>
     <option value="public">Public Action</option>
     <option value="private">Private Action</option>
     <option value="mixed">Both</option>
   </select>
   ```

3. Update WebSocket message handling:
   - Filter messages based on user role
   - Storyteller sees all
   - Players see only public messages from others

4. Update UI to show message type indicators

**Estimated Time:** 3-5 days

---

## 📚 Documentation Links

- **Full Roadmap:** `PROJECT_PLAN.md` (15 weeks, all phases)
- **MVP Plan:** `MVP_ROADMAP.md` (12 weeks, core features)
- **LLM Guide:** `LLM_GUIDE.md` (Available AI models)
- **README:** `README.md` (Setup and usage)

---

## ❓ Key Questions to Answer During Development

1. **Authentication:** JWT vs Session-based?
2. **Database:** PostgreSQL or MongoDB?
3. **Deployment:** Docker, cloud provider?
4. **AI Costs:** Budget limits per game/user?
5. **Scaling:** How many concurrent games?
6. **Context:** How to handle long game histories with LLM limits?

---

**Next Steps:** Review MVP_ROADMAP.md and begin Phase 1 implementation!

**Last Updated:** 2025-01-11  
**Status:** Planning Complete → Ready for Development