# quintus-hgv/morpheus-dashboard architecture

> Architecture diagram of the GitHub repository quintus-hgv/morpheus-dashboard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/quintus-hgv/morpheus-dashboard
- Repository: https://github.com/quintus-hgv/morpheus-dashboard

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User (Browser)"]

    subgraph "Presentation Layer"
        UI1["Streamlit UI (main.py)"]:::ui
        UI2["Setup (setup.py)"]:::ui
        UI3["Views (views.py)"]:::ui
    end

    subgraph "Business Logic & Data Access"
        Loader["Data Access (load_data.py)"]:::data
        Pandas["Pandas Transformations"]:::data
    end

    subgraph "RAG Engine"
        GRE["Orchestrator (graph_rag_engine.py)"]:::ai
        RE["RAG Engine (rag_engine.py)"]:::ai
        DOC["Document Loader (documents.py)"]:::ai
        GR["Graph Builder (build_graph.py)"]:::ai
    end

    subgraph "Data Stores"
        Neo4j[("Neo4j DB")]:::data
        subgraph "Vector Store & Caches"
            VS1[("query_index.faiss")]:::data
            VS2[("query_meta.pkl")]:::data
            VS3[("template_embeddings.index")]:::data
            VS4[("raw_tenant_logs.index")]:::data
            VS5[("summary_logs.index")]:::data
            JS1[("raw_chunks.json")]:::data
            JS2[("summary_chunks.json")]:::data
        end
    end

    subgraph "Templates"
        QT[("query_templates.json")]:::data
        TO[("templates_only.json")]:::data
        NQ[("neo4j_query_table_data.json")]:::data
    end

    External[(Cloud: OpenRouter LLM API)]:::ext
    Env["Environment (.env)"]:::ext

    User -->|"HTTP"| UI1
    UI1 --> UI2
    UI1 --> UI3
    UI1 --> Loader
    Loader -->|"bolt://"| Neo4j
    Neo4j --> Pandas
    Pandas --> UI3
    UI1 --> GRE
    GRE --> RE
    RE --> DOC
    RE --> GR
    DOC --> VS1
    DOC --> VS2
    GR --> VS3
    GR --> VS4
    GR --> VS5
    RE -->|"API Call"| External
    External --> RE
    RE --> UI3
    Env --> Neo4j
    Env --> External

    click UI1 "https://github.com/quintus-hgv/morpheus-dashboard/blob/main/main.py"
    click UI2 "https://github.com/quintus-hgv/morpheus-dashboard/blob/main/setup.py"
    click UI3 "https://github.com/quintus-hgv/morpheus-dashboard/blob/main/views.py"
    click Loader "https://github.com/quintus-hgv/morpheus-dashboard/blob/main/load_data.py"
    click GRE "https://github.com/quintus-hgv/morpheus-dashboard/blob/main/llm/graph_rag_engine.py"
    click RE "https://github.com/quintus-hgv/morpheus-dashboard/blob/main/llm/rag_engine.py"
    click GR "https://github.com/quintus-hgv/morpheus-dashboard/blob/main/llm/build_graph.py"
    click DOC "https://github.com/quintus-hgv/morpheus-dashboard/blob/main/llm/documents.py"
    click VS1 "https://github.com/quintus-hgv/morpheus-dashboard/blob/main/llm/query_index.faiss"
    click VS2 "https://github.com/quintus-hgv/morpheus-dashboard/blob/main/llm/query_meta.pkl"
    click VS3 "https://github.com/quintus-hgv/morpheus-dashboard/blob/main/llm/template_embeddings.index"
    click VS4 "https://github.com/quintus-hgv/morpheus-dashboard/blob/main/llm/raw_tenant_logs.index"
    click VS5 "https://github.com/quintus-hgv/morpheus-dashboard/blob/main/llm/summary_logs.index"
    click JS1 "https://github.com/quintus-hgv/morpheus-dashboard/blob/main/llm/raw_chunks.json"
    click JS2 "https://github.com/quintus-hgv/morpheus-dashboard/blob/main/llm/summary_chunks.json"
    click QT "https://github.com/quintus-hgv/morpheus-dashboard/blob/main/llm/query_templates.json"
    click TO "https://github.com/quintus-hgv/morpheus-dashboard/blob/main/llm/templates_only.json"
    click NQ "https://github.com/quintus-hgv/morpheus-dashboard/blob/main/llm/neo4j_query_table_data.json"

    classDef ui fill:#AED6F1,stroke:#000,stroke-width:1px
    classDef data fill:#ABEBC6,stroke:#000,stroke-width:1px
    classDef ai fill:#F9E79F,stroke:#000,stroke-width:1px
    classDef ext fill:#D7BDE2,stroke:#000,stroke-width:1px
```
