# aaroncao06/projectnexus architecture

> Architecture diagram of the GitHub repository aaroncao06/projectnexus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aaroncao06/projectnexus
- Repository: https://github.com/aaroncao06/projectnexus

## Overview

1. **Overall shape**
   ProjectNexus is split into three runtime layers plus an offline preparation layer: an **ingestion/authoring agent**, a **read/query backend**, and a **React frontend**, all centered on a **Neo4j graph**. RAG and summarization are additive services that depend on **Pinecone** and **OpenRouter**.

2. **Write path: the Agent**
   The `agent/` package is the graph-building and indexing pipeline. It ingests email chains from CSV, synthetic data, or sample data, normalizes names through alias generation, extracts people/relationships, and writes the resulting entities into Neo4j. It also has separate flows for generating edge summaries and building Pinecone embeddings for later retrieval.

3. **Graph data model**
   The core graph appears to be intentionally simple: **`Person` nodes** connected by **`COMMUNICATES_WITH` edges**. Edges can carry summary/commentary metadata, which becomes important for the summarization and RAG layers. This makes Neo4j the system of record for relationship structure.

4. **Read path: the Backend**
   The `backend/` package is a FastAPI service that reads from Neo4j and exposes graph-oriented APIs to the UI. It is not the primary writer; it acts as a query and analysis layer over the graph, plus a gateway to RAG and LLM-powered features.

5. **Backend submodules and responsibilities**
   The backend is functionally split into:
   - `db.py` / `config.py`: graph and service configuration
   - `vectorstore.py` / `rag.py`: Pinecone-backed retrieval
   - `llm.py`: OpenRouter integration
   - `clustering.py`: graph clustering/reclustering logic for visualization
   - `insights.py`: anomaly, bridge, and centrality analysis
   - `main.py`: HTTP surface for graph, metadata, summarization, query, and insights endpoints

6. **Frontend boundary**
   The `frontend/` app is a Vite + React + TypeScript client. It consumes the backend over HTTP via `api.ts`, renders the graph in `GraphView.tsx`, and provides a chat/QA surface in `ChatPanel.tsx`. The UI is a pure consumer of backend APIs; it does not talk directly to Neo4j or Pinecone.

7. **Visualization flow**
   The graph UI is driven by backend responses that include nodes, edges, and metadata. The backend can return either the **full graph** or a **person-centered subgraph** with configurable depth, and can optionally recluster nodes to improve layout/legibility before the frontend renders them.

8. **RAG flow**
   RAG is a separate retrieval path: user questions from the frontend go to the backend `/query` endpoint, the backend embeds the query, searches **Pinecone**, and then sends retrieved context to **OpenRouter** for answer generation. This is the main place where unstructured email content is turned into natural-language answers.

9. **Insights flow**
   The backend also produces graph analytics beyond raw traversal: structural anomalies, bridging nodes, and centrality-style insights. These can be returned as computed metrics or generated through LLM-backed commentary, depending on the endpoint used. This sits between pure graph querying and generative assistance.

10. **Offline data preparation**
   `Notebook_Data/` contains Jupyter notebooks that preprocess source email corpora into downstream assets. One notebook chunks large Enron-style email data into parquet files for later embedding/indexing; another works with a structured Epstein email JSON-like dataset. These notebooks feed both the graph-ingestion and RAG pipelines.

11. **External services and operational dependencies**
   Three external systems materially shape the architecture:
   - **Neo4j** for graph persistence
   - **Pinecone** for semantic retrieval
   - **OpenRouter** for summarization, answer generation, and insight narration  
   The app can still do basic graph exploration without the LLM/RAG services, but those features depend on environment configuration.

12. **What to show in an architecture diagram**
   A clear diagram should place **Neo4j** in the center, with the **Agent** as the write-side producer, the **Backend** as the read/analysis API, and the **Frontend** as the client. Off to the side, show **Pinecone + OpenRouter** behind backend RAG/LLM calls, and show **Notebook preprocessing** as an offline source feeding the agent/indexing pipeline.

Main entry points: [`backend/main.py`](https://github.com/aaroncao06/projectnexus/blob/main/backend/main.py) (API), [`agent/main.py`](https://github.com/aaroncao06/projectnexus/blob/main/agent/main.py) (Agent), [`backend/rag.py`](https://github.com/aaroncao06/projectnexus/blob/main/backend/rag.py) (RAG), [`agent/graph.py`](https://github.com/aaroncao06/projectnexus/blob/main/agent/graph.py) (Graph build)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_offline["Offline prep"]
  node_notebooks["Notebooks<br/>preprocess"]
  node_email_inputs["Email data<br/>source corpus"]
end

subgraph group_agent["Write path"]
  node_agent_main["Agent<br/>ingestion pipeline<br/>[main.py]"]
  node_aliasing["Aliases<br/>normalization"]
  node_graph_building[("Graph build<br/>neo4j writer<br/>[graph.py]")]
  node_relationship_indexing["Edge index<br/>relationship indexing"]
  node_embedding_indexing["Embeddings<br/>vector indexing<br/>[embeddings.py]"]
  node_pinecone_client["Pinecone client<br/>vector client<br/>[pinecone_client.py]"]
end

subgraph group_backend["Read path"]
  node_backend_main["API<br/>[main.py]"]
  node_db_layer[("DB layer<br/>graph access<br/>[db.py]")]
  node_clustering["Clustering<br/>layout analysis<br/>[clustering.py]"]
  node_insights["Insights<br/>graph analytics<br/>[insights.py]"]
  node_rag_layer["RAG<br/>retrieval pipeline<br/>[rag.py]"]
  node_vectorstore["Vector store<br/>retrieval access<br/>[vectorstore.py]"]
  node_llm_layer["LLM<br/>generation gateway<br/>[llm.py]"]
end

subgraph group_frontend["UI"]
  node_graph_ui["Graph view<br/>visualization<br/>[GraphView.tsx]"]
  node_chat_ui["Chat panel<br/>qa interface<br/>[ChatPanel.tsx]"]
  node_api_client["API client<br/>http client<br/>[api.ts]"]
end

subgraph group_services["External services"]
  node_neo4j[("Neo4j<br/>graph database")]
  node_pinecone[("Pinecone<br/>vector database")]
  node_openrouter(("OpenRouter<br/>llm service"))
end

node_notebooks -->|"prepare"| node_email_inputs
node_email_inputs -->|"feed"| node_agent_main
node_agent_main -->|"normalize"| node_aliasing
node_aliasing -->|"resolve"| node_graph_building
node_agent_main -->|"extract"| node_relationship_indexing
node_relationship_indexing -->|"write"| node_graph_building
node_agent_main -->|"index"| node_embedding_indexing
node_embedding_indexing -->|"store"| node_pinecone_client
node_graph_building -->|"persist"| node_neo4j
node_pinecone_client -->|"upsert"| node_pinecone
node_api_client -->|"request"| node_backend_main
node_backend_main -->|"read graph"| node_db_layer
node_db_layer -->|"query"| node_neo4j
node_backend_main -->|"recluster"| node_clustering
node_backend_main -->|"analyze"| node_insights
node_backend_main -->|"answer"| node_rag_layer
node_rag_layer -->|"retrieve"| node_vectorstore
node_vectorstore -->|"search"| node_pinecone
node_rag_layer -->|"generate"| node_llm_layer
node_llm_layer -->|"invoke"| node_openrouter
node_backend_main -->|"serve graph"| node_graph_ui
node_backend_main -->|"serve qa"| node_chat_ui

click node_notebooks "https://github.com/aaroncao06/projectnexus/tree/main/Notebook_Data"
click node_email_inputs "https://github.com/aaroncao06/projectnexus/blob/main/Notebook_Data/epstein_emails_insights_all.txt"
click node_agent_main "https://github.com/aaroncao06/projectnexus/blob/main/agent/main.py"
click node_aliasing "https://github.com/aaroncao06/projectnexus/blob/main/agent/generate_aliases.py"
click node_graph_building "https://github.com/aaroncao06/projectnexus/blob/main/agent/graph.py"
click node_relationship_indexing "https://github.com/aaroncao06/projectnexus/blob/main/agent/index_relationships.py"
click node_embedding_indexing "https://github.com/aaroncao06/projectnexus/blob/main/agent/embeddings.py"
click node_pinecone_client "https://github.com/aaroncao06/projectnexus/blob/main/agent/pinecone_client.py"
click node_backend_main "https://github.com/aaroncao06/projectnexus/blob/main/backend/main.py"
click node_db_layer "https://github.com/aaroncao06/projectnexus/blob/main/backend/db.py"
click node_clustering "https://github.com/aaroncao06/projectnexus/blob/main/backend/clustering.py"
click node_insights "https://github.com/aaroncao06/projectnexus/blob/main/backend/insights.py"
click node_rag_layer "https://github.com/aaroncao06/projectnexus/blob/main/backend/rag.py"
click node_vectorstore "https://github.com/aaroncao06/projectnexus/blob/main/backend/vectorstore.py"
click node_llm_layer "https://github.com/aaroncao06/projectnexus/blob/main/backend/llm.py"
click node_graph_ui "https://github.com/aaroncao06/projectnexus/blob/main/frontend/src/GraphView.tsx"
click node_chat_ui "https://github.com/aaroncao06/projectnexus/blob/main/frontend/src/ChatPanel.tsx"
click node_api_client "https://github.com/aaroncao06/projectnexus/blob/main/frontend/src/api.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_notebooks,node_email_inputs toneBlue
class node_agent_main,node_aliasing,node_graph_building,node_relationship_indexing,node_embedding_indexing,node_pinecone_client toneAmber
class node_backend_main,node_db_layer,node_clustering,node_insights,node_rag_layer,node_vectorstore,node_llm_layer toneMint
class node_graph_ui,node_chat_ui,node_api_client toneRose
class node_neo4j,node_pinecone,node_openrouter toneIndigo
```

## Components

### Offline prep

Notebooks and source data preparation

- [Notebooks](https://github.com/aaroncao06/projectnexus/tree/main/Notebook_Data): preprocess · Jupyter workflows that chunk and prepare source email corpora · `Notebook_Data`
- [Email data](https://github.com/aaroncao06/projectnexus/blob/main/Notebook_Data/epstein_emails_insights_all.txt): source corpus · Raw or structured email datasets used to build graph and retrieval assets · `Notebook_Data/epstein_emails_insights_all.txt`

### Write path

Ingestion, normalization, and indexing pipeline

- [Agent](https://github.com/aaroncao06/projectnexus/blob/main/agent/main.py): ingestion pipeline · Entry point for graph-building and indexing workflows · `agent/main.py`
- [Aliases](https://github.com/aaroncao06/projectnexus/blob/main/agent/generate_aliases.py): normalization · Name normalization and alias generation for entity resolution · `agent/generate_aliases.py`
- [Graph build](https://github.com/aaroncao06/projectnexus/blob/main/agent/graph.py): neo4j writer · Creates people and communication relationships in the graph store · `agent/graph.py`
- [Edge index](https://github.com/aaroncao06/projectnexus/blob/main/agent/index_relationships.py): relationship indexing · Extracts relationship chains and writes communication edges · `agent/index_relationships.py`
- [Embeddings](https://github.com/aaroncao06/projectnexus/blob/main/agent/embeddings.py): vector indexing · Builds embeddings for later semantic retrieval · `agent/embeddings.py`
- [Pinecone client](https://github.com/aaroncao06/projectnexus/blob/main/agent/pinecone_client.py): vector client · Agent-side connector for semantic index writes · `agent/pinecone_client.py`

### Read path

FastAPI query, analysis, and RAG service

- [API](https://github.com/aaroncao06/projectnexus/blob/main/backend/main.py): FastAPI service · HTTP surface for graph, query, summarization, and insights · `backend/main.py`
- [DB layer](https://github.com/aaroncao06/projectnexus/blob/main/backend/db.py): graph access · Neo4j connectivity and graph read helpers · `backend/db.py`
- [Clustering](https://github.com/aaroncao06/projectnexus/blob/main/backend/clustering.py): layout analysis · Reclusters graph data for visualization and legibility · `backend/clustering.py`
- [Insights](https://github.com/aaroncao06/projectnexus/blob/main/backend/insights.py): graph analytics · Centrality, bridge, and anomaly-style analysis · `backend/insights.py`
- [RAG](https://github.com/aaroncao06/projectnexus/blob/main/backend/rag.py): retrieval pipeline · Embeds questions and retrieves context for answers · `backend/rag.py`
- [Vector store](https://github.com/aaroncao06/projectnexus/blob/main/backend/vectorstore.py): retrieval access · Pinecone-backed search helpers used by the backend · `backend/vectorstore.py`
- [LLM](https://github.com/aaroncao06/projectnexus/blob/main/backend/llm.py): generation gateway · OpenRouter integration for answers and commentary · `backend/llm.py`

### UI

React client for graph exploration and chat

- [Graph view](https://github.com/aaroncao06/projectnexus/blob/main/frontend/src/GraphView.tsx): visualization · Renders nodes, edges, and metadata returned by the backend · `frontend/src/GraphView.tsx`
- [Chat panel](https://github.com/aaroncao06/projectnexus/blob/main/frontend/src/ChatPanel.tsx): qa interface · User-facing question and answer surface · `frontend/src/ChatPanel.tsx`
- [API client](https://github.com/aaroncao06/projectnexus/blob/main/frontend/src/api.ts): http client · Frontend adapter for backend requests · `frontend/src/api.ts`

### External services

Persistence, retrieval, and LLM dependencies

- **Neo4j**: graph database · System of record for people and communication relationships
- **Pinecone**: vector database · Semantic retrieval store for RAG
- **OpenRouter**: llm service · Generates answers, summaries, and insight narration

## Connections

- Notebooks → Email data: prepare · Offline notebooks transform source email corpora into downstream assets
- Email data → Agent: feed · Prepared corpora are consumed by the agent pipeline
- Agent → Aliases: normalize · Agent resolves names and aliases before graph construction
- Aliases → Graph build: resolve · Normalized identities are written as graph entities and relationships
- Agent → Edge index: extract · Agent derives communication chains and relationship edges
- Edge index → Graph build: write · Indexed relationships are persisted into the graph store
- Agent → Embeddings: index · Agent prepares semantic embeddings for retrieval
- Embeddings → Pinecone client: store · Embeddings are sent to the vector index client
- Graph build → Neo4j: persist · People and communication edges are stored in Neo4j
- Pinecone client → Pinecone: upsert · Semantic vectors are written to Pinecone
- API client → API: request · Frontend calls backend HTTP endpoints
- API → DB layer: read graph · Backend reads graph data through its DB layer
- DB layer → Neo4j: query · Neo4j powers graph traversal and subgraph responses
- API → Clustering: recluster · Backend can reshape graph data for visual clarity
- API → Insights: analyze · Backend computes graph-centric insights and anomalies
- API → RAG: answer · Backend routes user questions through the RAG flow
- RAG → Vector store: retrieve · Questions are embedded and matched against the vector store
- Vector store → Pinecone: search · Pinecone provides semantic retrieval context
- RAG → LLM: generate · Retrieved context is turned into a natural-language answer
- LLM → OpenRouter: invoke · OpenRouter generates summaries, answers, and commentary
- API → Graph view: serve graph · Graph responses power the visualization layer
- API → Chat panel: serve qa · Chat responses power the conversational UI
