Storyforge

The core architecture follows a clear separation of concerns: the API layer (server/routes/stories.js) handles HTTP requests, delegating to service modules such as storyGenerator.js for outline and chapter creation, ollama.js for LLM interaction, and storage.js for file‑based persistence. Each story is stored as a JSON object, enabling quick reads/writes without a traditional database.

Data ingestion is supported through a RAG (Retrieval‑Augmented Generation) pipeline. Uploaded documents (e.g., PDFs) are processed by the index-document endpoint, which renames and forwards the file to services/rag.js for chunking and indexing, expanding the model's knowledge base. The clear-knowledge endpoint allows administrators to reset this vector store.

Execution flow for story creation begins with a POST /api/stories/generate request containing metadata (title, theme, genre, etc.). The request is validated, then generateOutline constructs a high‑level structure via Ollama. Subsequent chapter generation (POST /api/stories/:id/chapters/:chapterNumber) invokes generateChapter, updates word counts, estimates read time, and persists changes. The frontend uses React Query to cache and synchronize this data, while UI components like the Carousel provide keyboard‑accessible navigation (ArrowLeft/ArrowRight).

Security and guardrails include input validation on required fields, content moderation via services/moderator.js to enforce the explicitness setting, and error handling that returns consistent JSON error objects. Environment variables (PORT, OLLAMA_URL, OLLAMA_MODEL) are loaded from .env, allowing flexible deployment configurations.

Build and deployment topology is straightforward: a Node.js server (npm start or npm run dev) runs on port 3001, and the React client is bundled with Vite (or similar) for static serving. The system relies on the local Ollama service (ollama serve) for model inference, making it self‑contained without external cloud dependencies.