# vijay-rodge/polarnexus architecture

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

- Interactive diagram: https://gitdiagram.com/vijay-rodge/polarnexus
- Repository: https://github.com/vijay-rodge/polarnexus

## Overview

This is an NCPOR polar-science knowledge, analysis, and outreach portal. Users enter through the web portal or REST API; assistant queries are normalized and classified, routed to retrieval, scientific analysis, or catalog searches, then synthesized and citation-validated. Separate product branches support DSpace harvesting and manuscript extraction, scientific data analysis, catalog exploration, media, and educational outreach. The README documents several capabilities whose page or engine internals are not sampled; those relationships are shown only where documented, with uncertain wiring omitted or dashed.

Main entry points: [`agents/graph.py`](https://github.com/vijay-rodge/polarnexus/blob/main/agents/graph.py) (LangGraph router), [`agents/tools/controlled_tools.py`](https://github.com/vijay-rodge/polarnexus/blob/main/agents/tools/controlled_tools.py) (Controlled data tools), [`streamlit_app/app.py`](https://github.com/vijay-rodge/polarnexus/blob/main/streamlit_app/app.py) (Streamlit portal), [`crawler/dspace_search_harvester.py`](https://github.com/vijay-rodge/polarnexus/blob/main/crawler/dspace_search_harvester.py) (DSpace harvesting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_portal["Streamlit portal<br/>[app.py]"]
  node_assistant_page["AI assistant<br/>[01_assistant.py]"]
  node_catalog_pages["Catalog explorers<br/>[02_stations.py]"]
  node_outreach_page["Outreach guides<br/>[08_outreach.py]"]
  node_api["REST API<br/>[main.py]"]
end

subgraph group_assistant["Query assistant"]
  node_query_graph["LangGraph router<br/>[graph.py]"]
  node_normalizer["Query normalization<br/>[normalize.py]"]
  node_classifier["Intent routing<br/>[classify.py]"]
  node_rag_retrieval["Document retrieval<br/>[retrieve_rag.py]"]
  node_data_analysis["Data analysis route<br/>[analyze_data.py]"]
  node_catalog_search["Catalog search routes<br/>[search_nodes.py]"]
  node_answer["Answer synthesis<br/>[generate_answer.py]"]
  node_citation_check["Citation validation"]
end

subgraph group_science["Science and catalogs"]
  node_controlled_tools["Controlled data tools"]
  node_scientific_engine["Scientific analysis<br/>[analyzer.py]"]
  node_document_analysis["Manuscript analysis"]
  node_ml_classification["Domain classification"]
end

subgraph group_ingestion["Repository ingestion"]
  node_dspace_harvester["DSpace harvesting"]
  node_crawler_engine["Repository crawler<br/>[engine.py]"]
end

subgraph group_persistence["Data and retrieval"]
  node_db[("Polar metadata database<br/>[models.py]")]
  node_vectorstore[("Chroma knowledge store<br/>[chroma_store.py]")]
end

node_user(("Portal user"))
node_external_dspace(("NCPOR DSpace"))

node_user -->|"uses"| node_portal
node_user -->|"queries"| node_api
node_portal -->|"offers"| node_assistant_page
node_assistant_page -.->|"submits query"| node_query_graph
node_api -->|"executes query"| node_query_graph
node_query_graph -->|"normalizes"| node_normalizer
node_query_graph -->|"classifies"| node_classifier
node_query_graph -->|"routes to"| node_rag_retrieval
node_query_graph -->|"routes to"| node_data_analysis
node_query_graph -->|"routes to"| node_catalog_search
node_rag_retrieval -->|"searches documents"| node_controlled_tools
node_data_analysis -->|"requests analysis"| node_controlled_tools
node_catalog_search -->|"searches catalogs"| node_controlled_tools
node_query_graph -->|"dispatches synthesis"| node_answer
node_query_graph -->|"dispatches validation"| node_citation_check
node_controlled_tools -->|"computes statistics"| node_scientific_engine
node_controlled_tools -->|"queries metadata"| node_db
node_controlled_tools -->|"searches chunks"| node_vectorstore
node_answer -->|"uses coordinates"| node_document_analysis
node_dspace_harvester -->|"harvests records"| node_external_dspace
node_crawler_engine -.->|"complements harvest"| node_dspace_harvester
node_crawler_engine -.->|"extracts manuscript data"| node_document_analysis
node_dspace_harvester -.->|"extracts coordinates and figures"| node_document_analysis
node_dspace_harvester -.->|"stores text chunks"| node_vectorstore
node_portal -->|"provides explorers"| node_catalog_pages
node_portal -->|"provides outreach"| node_outreach_page
node_ml_classification -.->|"tracks model metadata"| node_db

click node_portal "https://github.com/vijay-rodge/polarnexus/blob/main/streamlit_app/app.py"
click node_assistant_page "https://github.com/vijay-rodge/polarnexus/blob/main/streamlit_app/pages/01_assistant.py"
click node_catalog_pages "https://github.com/vijay-rodge/polarnexus/blob/main/streamlit_app/pages/02_stations.py"
click node_outreach_page "https://github.com/vijay-rodge/polarnexus/blob/main/streamlit_app/pages/08_outreach.py"
click node_api "https://github.com/vijay-rodge/polarnexus/blob/main/api/main.py"
click node_query_graph "https://github.com/vijay-rodge/polarnexus/blob/main/agents/graph.py"
click node_normalizer "https://github.com/vijay-rodge/polarnexus/blob/main/agents/nodes/normalize.py"
click node_classifier "https://github.com/vijay-rodge/polarnexus/blob/main/agents/nodes/classify.py"
click node_rag_retrieval "https://github.com/vijay-rodge/polarnexus/blob/main/agents/nodes/retrieve_rag.py"
click node_data_analysis "https://github.com/vijay-rodge/polarnexus/blob/main/agents/nodes/analyze_data.py"
click node_catalog_search "https://github.com/vijay-rodge/polarnexus/blob/main/agents/nodes/search_nodes.py"
click node_answer "https://github.com/vijay-rodge/polarnexus/blob/main/agents/nodes/generate_answer.py"
click node_citation_check "https://github.com/vijay-rodge/polarnexus/blob/main/agents/nodes/validate_citations.py"
click node_controlled_tools "https://github.com/vijay-rodge/polarnexus/blob/main/agents/tools/controlled_tools.py"
click node_scientific_engine "https://github.com/vijay-rodge/polarnexus/blob/main/scientific_engine/analyzer.py"
click node_document_analysis "https://github.com/vijay-rodge/polarnexus/blob/main/scientific_engine/document_analyzer.py"
click node_ml_classification "https://github.com/vijay-rodge/polarnexus/blob/main/ml/classification/domain_classifier.py"
click node_dspace_harvester "https://github.com/vijay-rodge/polarnexus/blob/main/crawler/dspace_search_harvester.py"
click node_crawler_engine "https://github.com/vijay-rodge/polarnexus/blob/main/crawler/engine.py"
click node_db "https://github.com/vijay-rodge/polarnexus/blob/main/database/models.py"
click node_vectorstore "https://github.com/vijay-rodge/polarnexus/blob/main/rag/vectorstore/chroma_store.py"

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_portal,node_assistant_page,node_catalog_pages,node_outreach_page,node_api,node_user toneBlue
class node_query_graph,node_normalizer,node_classifier,node_rag_retrieval,node_data_analysis,node_catalog_search,node_answer,node_citation_check toneAmber
class node_controlled_tools,node_scientific_engine,node_document_analysis,node_ml_classification toneMint
class node_dspace_harvester,node_crawler_engine toneRose
class node_db,node_vectorstore,node_external_dspace toneIndigo
```

## Components

### User interfaces

- [Streamlit portal](https://github.com/vijay-rodge/polarnexus/blob/main/streamlit_app/app.py): `streamlit_app/app.py`
- [AI assistant](https://github.com/vijay-rodge/polarnexus/blob/main/streamlit_app/pages/01_assistant.py): `streamlit_app/pages/01_assistant.py`
- [Catalog explorers](https://github.com/vijay-rodge/polarnexus/blob/main/streamlit_app/pages/02_stations.py): `streamlit_app/pages/02_stations.py`
- [Outreach guides](https://github.com/vijay-rodge/polarnexus/blob/main/streamlit_app/pages/08_outreach.py): `streamlit_app/pages/08_outreach.py`
- [REST API](https://github.com/vijay-rodge/polarnexus/blob/main/api/main.py): `api/main.py`

### Query assistant

- [LangGraph router](https://github.com/vijay-rodge/polarnexus/blob/main/agents/graph.py): `agents/graph.py`
- [Query normalization](https://github.com/vijay-rodge/polarnexus/blob/main/agents/nodes/normalize.py): `agents/nodes/normalize.py`
- [Intent routing](https://github.com/vijay-rodge/polarnexus/blob/main/agents/nodes/classify.py): `agents/nodes/classify.py`
- [Document retrieval](https://github.com/vijay-rodge/polarnexus/blob/main/agents/nodes/retrieve_rag.py): `agents/nodes/retrieve_rag.py`
- [Data analysis route](https://github.com/vijay-rodge/polarnexus/blob/main/agents/nodes/analyze_data.py): `agents/nodes/analyze_data.py`
- [Catalog search routes](https://github.com/vijay-rodge/polarnexus/blob/main/agents/nodes/search_nodes.py): `agents/nodes/search_nodes.py`
- [Answer synthesis](https://github.com/vijay-rodge/polarnexus/blob/main/agents/nodes/generate_answer.py): `agents/nodes/generate_answer.py`
- [Citation validation](https://github.com/vijay-rodge/polarnexus/blob/main/agents/nodes/validate_citations.py): `agents/nodes/validate_citations.py`

### Science and catalogs

- [Controlled data tools](https://github.com/vijay-rodge/polarnexus/blob/main/agents/tools/controlled_tools.py): `agents/tools/controlled_tools.py`
- [Scientific analysis](https://github.com/vijay-rodge/polarnexus/blob/main/scientific_engine/analyzer.py): `scientific_engine/analyzer.py`
- [Manuscript analysis](https://github.com/vijay-rodge/polarnexus/blob/main/scientific_engine/document_analyzer.py): `scientific_engine/document_analyzer.py`
- [Domain classification](https://github.com/vijay-rodge/polarnexus/blob/main/ml/classification/domain_classifier.py): `ml/classification/domain_classifier.py`

### Repository ingestion

- [DSpace harvesting](https://github.com/vijay-rodge/polarnexus/blob/main/crawler/dspace_search_harvester.py): `crawler/dspace_search_harvester.py`
- [Repository crawler](https://github.com/vijay-rodge/polarnexus/blob/main/crawler/engine.py): `crawler/engine.py`

### Data and retrieval

- [Polar metadata database](https://github.com/vijay-rodge/polarnexus/blob/main/database/models.py): `database/models.py`
- [Chroma knowledge store](https://github.com/vijay-rodge/polarnexus/blob/main/rag/vectorstore/chroma_store.py): `rag/vectorstore/chroma_store.py`

### Other components

- **Portal user**
- **NCPOR DSpace**

## Connections

- Portal user → Streamlit portal: uses
- Portal user → REST API: queries
- Streamlit portal → AI assistant: offers
- AI assistant → LangGraph router: submits query
- REST API → LangGraph router: executes query (evidence: `api/main.py`)
- LangGraph router → Query normalization: normalizes (evidence: `agents/graph.py`)
- LangGraph router → Intent routing: classifies (evidence: `agents/graph.py`)
- LangGraph router → Document retrieval: routes to (evidence: `agents/graph.py`)
- LangGraph router → Data analysis route: routes to (evidence: `agents/graph.py`)
- LangGraph router → Catalog search routes: routes to (evidence: `agents/graph.py`)
- Document retrieval → Controlled data tools: searches documents (evidence: `agents/nodes/retrieve_rag.py`)
- Data analysis route → Controlled data tools: requests analysis (evidence: `agents/nodes/analyze_data.py`)
- Catalog search routes → Controlled data tools: searches catalogs (evidence: `agents/nodes/search_nodes.py`)
- LangGraph router → Answer synthesis: dispatches synthesis (evidence: `agents/graph.py`)
- LangGraph router → Citation validation: dispatches validation (evidence: `agents/graph.py`)
- Controlled data tools → Scientific analysis: computes statistics (evidence: `agents/tools/controlled_tools.py`)
- Controlled data tools → Polar metadata database: queries metadata (evidence: `agents/tools/controlled_tools.py`)
- Controlled data tools → Chroma knowledge store: searches chunks (evidence: `agents/tools/controlled_tools.py`)
- Answer synthesis → Manuscript analysis: uses coordinates (evidence: `agents/nodes/generate_answer.py`)
- DSpace harvesting → NCPOR DSpace: harvests records
- Repository crawler → DSpace harvesting: complements harvest
- Repository crawler → Manuscript analysis: extracts manuscript data
- DSpace harvesting → Manuscript analysis: extracts coordinates and figures (evidence: `crawler/dspace_search_harvester.py`)
- DSpace harvesting → Chroma knowledge store: stores text chunks (evidence: `crawler/dspace_search_harvester.py`)
- Streamlit portal → Catalog explorers: provides explorers
- Streamlit portal → Outreach guides: provides outreach
- Domain classification → Polar metadata database: tracks model metadata
