# georgeaaron7/murdermystery architecture

> Architecture diagram of the GitHub repository georgeaaron7/murdermystery, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/georgeaaron7/murdermystery
- Repository: https://github.com/georgeaaron7/murdermystery

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Front-End (React/Vite)"
        FEApp["React App"]:::frontend
        ChatWindow["ChatWindow"]:::frontend
        DetectiveBoard["DetectiveBoard"]:::frontend
        EvidenceModal["EvidenceModal"]:::frontend
        EvidenceNotification["EvidenceNotification"]:::frontend
        EvidencePanel["EvidencePanel"]:::frontend
        LandingPage["LandingPage"]:::frontend
        NotesPanel["NotesPanel"]:::frontend
        TeamRegistration["TeamRegistration"]:::frontend
        AssetsEvidence["Evidence Assets"]:::frontend
        AssetsSuspects["Suspect Images"]:::frontend
        FEApp --> ChatWindow
        FEApp --> DetectiveBoard
        FEApp --> EvidenceModal
        FEApp --> EvidenceNotification
        FEApp --> EvidencePanel
        FEApp --> LandingPage
        FEApp --> NotesPanel
        FEApp --> TeamRegistration
    end

    subgraph "Back-End (Node/Express)"
        Server["Express API\n(server.js)"]:::backend
        DBConn["DB Connector\n(config/db.js)"]:::backend
        ChatModel["ChatHistory Model\n(models/ChatHistory.js)"]:::backend
        NotesModel["Notes Model\n(models/Notes.js)"]:::backend
        FileStore["File Storage\n(file-storage.js)"]:::backend
        AgentSim["Agent Simulator\n(agent_simulator.js)"]:::backend
        TestClient["Test Client\n(test_client.js)"]:::backend
        VLLMTest["VLLM Test Script\n(test_vllm.sh)"]:::backend
        Server --> DBConn
        DBConn --> ChatModel
        DBConn --> NotesModel
        Server --> FileStore
    end

    subgraph "LLM Microservice (Python)"
        V2["v2.py"]:::microservice
        Dummy["dummy.py"]:::microservice
        Requirements["requirements.txt"]:::microservice
        V2 --> Requirements
        Dummy --> Requirements
    end

    User["User"]:::external
    External["Ollama Daemon"]:::external
    DB["MongoDB"]:::database
    EventAssets["Event Assets\n(event/)"]:::external

    User -->|"HTTP/WebSocket"| FEApp
    FEApp -->|"REST/WebSocket"| Server
    Server -->|"MongoDB Driver"| DB
    Server -->|"HTTP"| V2
    V2 -->|"Ollama SDK"| External
    External -->|"Response"| V2
    V2 -->|"LLM Response"| Server
    Server -->|"JSON"| FEApp
    EventAssets --> FileStore

    click FEApp "https://github.com/georgeaaron7/murdermystery/tree/master/webpage/detective_web_page/"
    click ChatWindow "https://github.com/georgeaaron7/murdermystery/blob/master/webpage/detective_web_page/src/components/ChatWindow.jsx"
    click DetectiveBoard "https://github.com/georgeaaron7/murdermystery/blob/master/webpage/detective_web_page/src/components/DetectiveBoard.jsx"
    click EvidenceModal "https://github.com/georgeaaron7/murdermystery/blob/master/webpage/detective_web_page/src/components/EvidenceModal.jsx"
    click EvidenceNotification "https://github.com/georgeaaron7/murdermystery/blob/master/webpage/detective_web_page/src/components/EvidenceNotification.jsx"
    click EvidencePanel "https://github.com/georgeaaron7/murdermystery/blob/master/webpage/detective_web_page/src/components/EvidencePanel.jsx"
    click LandingPage "https://github.com/georgeaaron7/murdermystery/blob/master/webpage/detective_web_page/src/components/LandingPage.jsx"
    click NotesPanel "https://github.com/georgeaaron7/murdermystery/blob/master/webpage/detective_web_page/src/components/NotesPanel.jsx"
    click TeamRegistration "https://github.com/georgeaaron7/murdermystery/blob/master/webpage/detective_web_page/src/components/TeamRegistration.jsx"
    click AssetsEvidence "https://github.com/georgeaaron7/murdermystery/tree/master/webpage/detective_web_page/src/assets/evidence/"
    click AssetsSuspects "https://github.com/georgeaaron7/murdermystery/tree/master/webpage/detective_web_page/src/assets/suspects/"
    click Server "https://github.com/georgeaaron7/murdermystery/blob/master/webpage/server.js"
    click DBConn "https://github.com/georgeaaron7/murdermystery/blob/master/webpage/config/db.js"
    click ChatModel "https://github.com/georgeaaron7/murdermystery/blob/master/webpage/models/ChatHistory.js"
    click NotesModel "https://github.com/georgeaaron7/murdermystery/blob/master/webpage/models/Notes.js"
    click FileStore "https://github.com/georgeaaron7/murdermystery/blob/master/webpage/file-storage.js"
    click AgentSim "https://github.com/georgeaaron7/murdermystery/blob/master/webpage/agent_simulator.js"
    click TestClient "https://github.com/georgeaaron7/murdermystery/blob/master/webpage/test_client.js"
    click VLLMTest "https://github.com/georgeaaron7/murdermystery/blob/master/webpage/test_vllm.sh"
    click V2 "https://github.com/georgeaaron7/murdermystery/blob/master/v2.py"
    click Dummy "https://github.com/georgeaaron7/murdermystery/blob/master/dummy.py"
    click Requirements "https://github.com/georgeaaron7/murdermystery/blob/master/requirements.txt"
    click EventAssets "https://github.com/georgeaaron7/murdermystery/tree/master/event/"

    classDef frontend fill:#e0ffe0,stroke:#2f6627,stroke-width:1px
    classDef backend fill:#e0f0ff,stroke:#1a4f8b,stroke-width:1px
    classDef microservice fill:#ffe0b3,stroke:#b36b00,stroke-width:1px
    classDef external fill:#f0f0f0,stroke:#666,stroke-width:1px
    classDef database fill:#ffffff,stroke:#000,stroke-width:2px,stroke-dasharray:5 5
```
