Roleplay Bot

Core Architecture The application follows a classic three‑tier architecture: a presentation layer built with React 18, TypeScript, and TailwindCSS; a service layer implemented in Express that handles routing, authentication (JWT), and AI request forwarding; and a data layer using MongoDB with Mongoose models. The entry point server/server.js wires middleware (cors, express.json, request logger) and mounts the /api/auth and /api routers, exposing endpoints documented in the repository.

Data Flow & Persistence User registration and login flow through auth.routes.js, invoking auth.controller methods that validate input (via Joi schemas as noted in the project details) and persist user records. Authenticated requests carry a Bearer token processed by auth.middleware, which guards protected routes like /api/auth/me, /api/auth/sessions, and /api/chat. Chat sessions are stored as documents containing configuration objects (gender, role, scene, level) and message arrays, enabling later retrieval and replay.

AI Integration The /api/chat endpoint forwards the user’s message payload to an Ollama model (dolphin‑mistral by default) over HTTP. Health checks (/api/health) verify both server uptime and Ollama connectivity, providing quick diagnostics for developers. Error handling middleware captures uncaught exceptions and returns sanitized JSON error objects, while the root endpoint enumerates available routes for discoverability.

Security & DevOps Guardrails Security is enforced through JWT authentication, rate‑limiting placeholders, and Helmet headers (as recommended in the project notes). Environment variables (.env) store secrets like JWT_SECRET, OLLAMA_URL, and DB credentials, keeping them out of source control. The setup documentation outlines MongoDB Atlas IP whitelisting and port conflict resolution, ensuring smooth local development and production readiness.

Build & Deployment Frontend assets are built with Vite (npm run build) and can be deployed to static hosts (Vercel, Netlify). The backend can be containerized or run directly via npm run dev. For desktop distribution, Electron wraps the web stack, leveraging IPC for native features while reusing the same codebase.