301 lines
10 KiB
Markdown
301 lines
10 KiB
Markdown
# 📂 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*
|