How georgeaaron7/murdermystery works
Project Type and Purpose
• This is a full-stack interactive detective game/web application that leverages a large language model (via Ollama) to drive a chat-based investigation. Users interact through a React front end (“detective_web_page”), which communicates with a Node/Express back end (“webpage/server.js”) and a Python microservice (“v2.py”) that queries an Ollama-hosted LLM. Persistent data (chat history, notes) are stored via a simple database layer configured in “webpage/config/db.js.”
File Structure Analysis
• Top-level:
• v2.py & dummy.py – Python scripts; v2.py is the main LLM orchestration entry point.
• requirements.txt – Python dependencies (including Ollama SDK).
• event/ – Static evidence assets (PDFs, audio, video).
• v2_results_*/ – Output directories for different model runs.
• webpage/ – Full front- and back-end code:
– detective_web_page/ – React (Vite) application under src, public, components.
– server.js – Express server to handle API endpoints, static hosting.
– config/db.js – Database connection module.
– models/ – Mongoose or ORM schemas (ChatHistory.js, Notes.js).
– file-storage.js – Handles evidence file serving or uploads.
– agent_simulator.js, test_client.js – Scripts to simulate or test interactions.
– deploy-scripts (deploy-vast.sh, deploy-frontend.sh).
README Insights
• The app uses Ollama as the LLM backend.
• You must pull a model locally (e.g. deepseek-r1:14b) and serve it (ollama serve).
• Python script v2.py invokes the Ollama API; the Node back end likely proxies or orchestrates calls from the front end to the Python LLM service.
Main System Components
a. Front-end (React/Vite)
• Components: ChatWindow, DetectiveBoard, EvidenceModal, etc.
• Assets: evidence files, suspects images.
b. Back-end API (Node/Express)
• server.js exposing REST/WebSocket endpoints for chat, notes, file retrieval.
• Models: ChatHistory, Notes.
• DB connector: config/db.js (e.g., MongoDB).
• File-storage module for serving static evidence.
c. LLM Microservice (Python v2.py)
• Uses Ollama SDK to send prompts & receive completions.
d. External Service
• Ollama daemon (local, serving the deepseek model).
e. Database
• MongoDB or similar as configured in config/db.js.
Component Interactions
• User → React UI (HTTP/WebSocket) → Express API
• Express API → Database (CRUD on chat, notes)
• Express API → Python LLM Microservice (HTTP/gRPC to v2.py)
• Python Microservice → Ollama Daemon → returns LLM response
• Express API aggregates LLM response + DB state → React UI
Architectural Patterns & Principles
• Separation of concerns:
• Presentation layer (React)
• Application/API layer (Express)
• LLM processing (Python microservice)
• Persistence layer (DB)
• Microservice-like split for LLM calls to isolate heavy model logic.
• Static asset hosting co-located in Express.
• Config-driven (db.js, .env files) for environment flexibility.
Final Advice
• Be thorough: include static file hosting, asset folder, test scripts if relevant.
• API endpoints at a high level (chat, notes, evidence fetch).
• Data flow: user intent → LLM prompt → response → persistence.