How quintus-hgv/morpheus-dashboard works
Project Type and Purpose
• This is a full-stack analytics/dashboard application (“Morpheus User Insights Dashboard”) built in Python, using Streamlit for the UI, Neo4j as its primary data store, and an LLM/RAG engine for AI-powered insights.
File Structure Analysis
• Top-level files:
– main.py: Streamlit entry point (UI server)
– setup.py: Streamlit page/config setup
– views.py: UI components & Plotly visualizations
– load_data.py: Backend functions to connect to Neo4j, query & preprocess
– llm/ : RAG engine folder with graph builders, embeddings, FAISS index files, templates, and serialization artifacts
– requirements.txt, setup.py, .env templates, Docker devcontainer config
• llm/ submodules implement retrieval-augmented generation: building knowledge graph, chunking docs, FAISS indices, query templates, and orchestrating calls to OpenRouter LLM.
• Data caches and indices (JSON, .index, .pkl) live alongside the llm code, indicating an embedded vector store pattern rather than an external microservice.
README Insights
• Describes 3 main pillars: Data Loading (Neo4j), Dashboard Setup (Streamlit), Visualizations (Plotly + AI insights).
• External dependencies: Neo4j DB, OpenRouter LLM API.
• No distributed microservices—single Python process serving both UI and data/AI logic.
a. Main Components to Show
1. User (Browser) accessing the Streamlit UI
2. Streamlit Application (main.py + setup.py + views.py)
3. Data Access Layer (load_data.py)
4. Neo4j Graph Database
5. LLM/RAG Engine (graph_rag_engine.py, rag_engine.py, documents.py, build_graph.py)
6. Vector Store & Caches (FAISS index files, JSON templates, meta.pkl)
7. External LLM Service (OpenRouter API)
b. Relationships & Data Flows
• Browser → HTTP → Streamlit App
• Streamlit App → load_data → Neo4j (bolt://) → raw user activity
• Neo4j results → Pandas transformations → passed to views.py for charts
• For AI insights: Streamlit App → llm/graph_rag_engine → retrieve from vector store → call OpenRouter API → receive LLM response → render in UI
• Caching: subsequent LLM queries hit local FAISS index or JSON template layer before external API
c. Architectural Patterns
• Monolithic service with layered architecture:
• Presentation Layer (Streamlit UI)
• Business Logic (data filtering, chart generation)
• Data Access Layer (Neo4j connector)
• RAG sub-module (Retrieval + Generation)
• RAG Pattern: local vector DB + graph builder + external LLM
• Cache-first approach for embeddings and query templates
d. Key Technologies
• Python 3.9+, Streamlit, Pandas, Plotly
• Neo4j v4.4+ (bolt driver)
• FAISS (vector indexing)
• OpenRouter LLM API