# 📂 Project Files Reference

Quick reference guide to all files in the Storyteller RPG project.

---

## 🔧 Core Application Files

### Backend (Python/FastAPI)

| File | Lines | Purpose |
|------|-------|---------|
| **main.py** | 398 | Complete FastAPI backend with WebSocket support, LLM integration, and all API endpoints |
| **requirements.txt** | 9 | Python dependencies (FastAPI, OpenAI, httpx, etc.) |

### Frontend (React)

| File | Lines | Purpose |
|------|-------|---------|
| **frontend/src/App.js** | 40 | Main router component, manages session/character state |
| **frontend/src/App.css** | 704 | Complete styling for entire application |
| **frontend/src/index.js** | 12 | React entry point |
| **frontend/src/components/SessionSetup.js** | 180 | Session creation and joining interface with model selection |
| **frontend/src/components/CharacterView.js** | 141 | Character's private conversation interface |
| **frontend/src/components/StorytellerView.js** | 243 | Storyteller dashboard with character management |
| **frontend/public/index.html** | 18 | HTML template |
| **frontend/package.json** | 40 | Node.js dependencies and scripts |

---

## 📚 Documentation Files

| File | Purpose | When to Read |
|------|---------|--------------|
| **README.md** | Comprehensive project overview, features, setup instructions | First time setup or sharing with others |
| **QUICKSTART.md** | 5-minute quick start guide | When you want to run the app quickly |
| **SESSION_SUMMARY.md** | Complete development session summary, architecture, decisions | When continuing development or understanding the codebase |
| **NEXT_STEPS.md** | Detailed roadmap of future features and improvements | When planning next development phase |
| **PROJECT_FILES_REFERENCE.md** | This file - quick reference to all files | When navigating the project |
| **LLM_GUIDE.md** | Guide to available LLM models (if exists) | When choosing AI models for characters |

---

## 🔐 Configuration Files

| File | Purpose | Notes |
|------|---------|-------|
| **.env.example** | Template for environment variables | Copy to `.env` and add your API keys |
| **.env** | Your actual API keys | **GITIGNORED** - never commit this |
| **.python-version** | Python version specification | For pyenv users |

---

## 🚀 Scripts

| File | Purpose | Usage |
|------|---------|-------|
| **start.sh** | Auto-start both backend and frontend | `./start.sh` (Unix/Mac/Linux) |
| **start.bat** | Windows version of start script | `start.bat` (Windows) |
| **dev.sh** | Development mode with tmux split terminals | `./dev.sh` (requires tmux) |

---

## 📁 Directory Structure

```
storyteller/
├── 📄 Backend Files
│   ├── main.py                          # ⭐ Main backend application
│   └── requirements.txt                 # Python dependencies
│
├── 🌐 Frontend Files
│   └── frontend/
│       ├── src/
│       │   ├── App.js                   # ⭐ Main React component
│       │   ├── App.css                  # ⭐ All styles
│       │   ├── index.js                 # React entry point
│       │   └── components/
│       │       ├── SessionSetup.js      # ⭐ Session creation/joining
│       │       ├── CharacterView.js     # ⭐ Character interface
│       │       └── StorytellerView.js   # ⭐ Storyteller dashboard
│       ├── public/
│       │   ├── index.html               # HTML template
│       │   ├── manifest.json            # PWA manifest
│       │   └── robots.txt               # SEO robots
│       ├── package.json                 # Node dependencies
│       └── node_modules/                # Installed packages (auto-generated)
│
├── 📚 Documentation
│   ├── README.md                        # ⭐ Main documentation
│   ├── QUICKSTART.md                    # Quick setup guide
│   ├── SESSION_SUMMARY.md               # ⭐ Development session summary
│   ├── NEXT_STEPS.md                    # ⭐ Future roadmap
│   └── PROJECT_FILES_REFERENCE.md       # This file
│
├── 🔐 Configuration
│   ├── .env.example                     # Environment template
│   ├── .env                             # Your API keys (gitignored)
│   └── .python-version                  # Python version
│
└── 🚀 Scripts
    ├── start.sh                         # Unix/Mac/Linux launcher
    ├── start.bat                        # Windows launcher
    └── dev.sh                           # Dev mode with tmux
```

---

## 🎯 Files by Priority

### Must Understand (Core Application)
1. **main.py** - Backend logic, WebSocket handling, LLM integration
2. **SessionSetup.js** - How users create/join sessions
3. **CharacterView.js** - Character's private conversation interface
4. **StorytellerView.js** - Storyteller's dashboard and response interface
5. **App.js** - React routing logic

### Important (Configuration & Styling)
6. **App.css** - All visual styling
7. **.env** - API keys configuration
8. **requirements.txt** - Backend dependencies
9. **package.json** - Frontend dependencies

### Reference (Documentation)
10. **SESSION_SUMMARY.md** - Understanding the architecture
11. **NEXT_STEPS.md** - Planning future work
12. **README.md** - Setup and feature overview
13. **QUICKSTART.md** - Fast setup instructions

---

## 🔍 Where to Find Things

### Adding New Features

**New WebSocket message type:**
- Backend: `main.py` → `character_websocket()` or `storyteller_websocket()`
- Frontend: Relevant component's `useEffect` → `ws.onmessage`

**New REST endpoint:**
- Backend: `main.py` → Add `@app.post()` or `@app.get()` decorator
- Frontend: Component → Add `fetch()` call

**New UI component:**
- Create in: `frontend/src/components/NewComponent.js`
- Import in: `frontend/src/App.js`
- Style in: `frontend/src/App.css`

**New LLM provider:**
- Backend: `main.py` → Update `call_llm()` function
- Frontend: `SessionSetup.js` → Model selector will auto-update from `/models` endpoint

### Understanding How It Works

**Message flow (Character → Storyteller):**
1. `CharacterView.js` → `sendMessage()` → WebSocket
2. `main.py` → `character_websocket()` → Receives message
3. Stored in `character.conversation_history`
4. Forwarded to storyteller via `manager.send_to_client()`
5. `StorytellerView.js` → `ws.onmessage` → Displays in UI

**Message flow (Storyteller → Character):**
1. `StorytellerView.js` → `sendResponse()` → WebSocket
2. `main.py` → `storyteller_websocket()` → Receives response
3. Stored in `character.conversation_history`
4. Sent to specific character via `manager.send_to_client()`
5. `CharacterView.js` → `ws.onmessage` → Displays in UI

**How LLM integration works:**
1. Character chooses model in `SessionSetup.js`
2. Stored in `Character.llm_model` field
3. When generating response: `call_llm(character.llm_model, messages)`
4. Function routes to OpenAI or OpenRouter based on model prefix
5. Returns generated text to be sent to character

### Styling

**Global styles:**
- `App.css` → Lines 1-100 (body, session-setup)

**SessionSetup styles:**
- `App.css` → Lines 18-180 (setup-container, input-group, divider, model-selector)

**CharacterView styles:**
- `App.css` → Lines 181-350 (character-view, character-header, messages)

**StorytellerView styles:**
- `App.css` → Lines 351-704 (storyteller-view, character-list, conversation-panel)

---

## 🛠️ Quick Modifications

### Change default LLM model
**File:** `main.py` line 47
```python
llm_model: str = "gpt-3.5-turbo"  # Change default here
```

### Change ports
**Backend:** `main.py` line 397
```python
uvicorn.run(app, host="0.0.0.0", port=8000)  # Change port here
```

**Frontend:** `package.json` or set `PORT=3001` environment variable

### Change API URLs
**File:** `SessionSetup.js`, `CharacterView.js`, `StorytellerView.js`
```javascript
const API_URL = 'http://localhost:8000';  // Change this
const WS_URL = 'ws://localhost:8000';     // And this
```

### Add new available model
**File:** `main.py` → `get_available_models()` function (lines 323-351)
```python
models["openai"].append({
    "id": "gpt-4o-mini", 
    "name": "GPT-4o Mini", 
    "provider": "OpenAI"
})
```

### Modify color scheme
**File:** `App.css`
- Line 13: `background: linear-gradient(...)` - Main gradient
- Lines 100-150: Button colors (`.btn-primary`)
- Lines 400-450: Message colors (`.message.sent`, `.message.received`)

---

## 📊 File Statistics

| Category | Files | Total Lines |
|----------|-------|-------------|
| Backend | 2 | ~407 |
| Frontend JS | 5 | ~616 |
| Frontend CSS | 1 | 704 |
| Frontend HTML | 1 | 18 |
| Documentation | 5 | ~1,500 |
| Scripts | 3 | ~250 |
| **Total** | **17** | **~3,495** |

---

## 🔄 Git/Version Control

### Files that should be gitignored:
- `.env` (contains API keys)
- `node_modules/` (npm packages)
- `.venv/` or `venv/` (Python virtual environment)
- `__pycache__/` (Python cache)
- `frontend/build/` (React build output)
- `.DS_Store` (Mac system files)

### Files that should be committed:
- All `.js`, `.py`, `.css`, `.html` files
- All `.md` documentation files
- `.env.example` (template without real keys)
- `requirements.txt` and `package.json`
- All script files (`.sh`, `.bat`)

---

## 💡 Tips for Navigating

1. **Start with README.md** for overall understanding
2. **Check SESSION_SUMMARY.md** for architecture details
3. **Read main.py** to understand backend flow
4. **Look at App.js** to see component structure
5. **Each component is self-contained** - easy to modify independently
6. **Styles are organized by component** in App.css
7. **WebSocket messages use JSON** with a `type` field for routing

---

## 🆘 Troubleshooting Guide

### "Can't find file X"
- Check you're in project root: `/home/aodhan/projects/apps/storyteller`
- Frontend files are in `frontend/` subdirectory
- Components are in `frontend/src/components/`

### "Code isn't working"
- Check if both servers are running (backend on 8000, frontend on 3000)
- Check browser console for JavaScript errors
- Check terminal for Python errors
- Verify `.env` file exists with valid API keys

### "Want to understand feature X"
- Search in `SESSION_SUMMARY.md` for architecture
- Search in `main.py` for backend implementation
- Search in relevant component file for frontend
- Check `App.css` for styling

---

*Last Updated: October 11, 2025*
*Total Project Size: ~3,500 lines of code + documentation*