aodhan/storyteller

Fork 0

Files

Aodhan Collins eccd456c59 Initial commit

2025-10-11 21:21:36 +01:00

10 KiB

Raw Permalink Blame History

📂 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)

main.py - Backend logic, WebSocket handling, LLM integration
SessionSetup.js - How users create/join sessions
CharacterView.js - Character's private conversation interface
StorytellerView.js - Storyteller's dashboard and response interface
App.js - React routing logic

Important (Configuration & Styling)

App.css - All visual styling
.env - API keys configuration
requirements.txt - Backend dependencies
package.json - Frontend dependencies

Reference (Documentation)

SESSION_SUMMARY.md - Understanding the architecture
NEXT_STEPS.md - Planning future work
README.md - Setup and feature overview
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):

CharacterView.js → sendMessage() → WebSocket
main.py → character_websocket() → Receives message
Stored in character.conversation_history
Forwarded to storyteller via manager.send_to_client()
StorytellerView.js → ws.onmessage → Displays in UI

Message flow (Storyteller → Character):

StorytellerView.js → sendResponse() → WebSocket
main.py → storyteller_websocket() → Receives response
Stored in character.conversation_history
Sent to specific character via manager.send_to_client()
CharacterView.js → ws.onmessage → Displays in UI

How LLM integration works:

Character chooses model in SessionSetup.js
Stored in Character.llm_model field
When generating response: call_llm(character.llm_model, messages)
Function routes to OpenAI or OpenRouter based on model prefix
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

llm_model: str = "gpt-3.5-turbo"  # Change default here

Change ports

Backend: main.py line 397

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

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)

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

Start with README.md for overall understanding
Check SESSION_SUMMARY.md for architecture details
Read main.py to understand backend flow
Look at App.js to see component structure
Each component is self-contained - easy to modify independently
Styles are organized by component in App.css
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

10 KiB Raw Permalink Blame History