# governai-techteam/research-atlas architecture

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

- Interactive diagram: https://gitdiagram.com/governai-techteam/research-atlas
- Repository: https://github.com/governai-techteam/research-atlas

## Overview

GovernAI Research Atlas turns a topic query into a board-ready research view: the frontend submits the topic, the backend gathers and ranks papers, repositories, and curated resources, extracts datasets and models, and returns an Atlas for dashboard and graph presentation. The README documents the major integrations and capabilities; sampled source confirms key orchestration and frontend calls. Some backend integrations are represented from documentation and the source index rather than inspected implementation excerpts.

Main entry points: [`services/atlas_service.py`](https://github.com/governai-techteam/research-atlas/blob/dk-final/services/atlas_service.py) (Atlas orchestration), [`src/app/components/AtlasDashboard.tsx`](https://github.com/governai-techteam/research-atlas/blob/dk-final/src/app/components/AtlasDashboard.tsx) (Atlas dashboard), [`src/app/App.tsx`](https://github.com/governai-techteam/research-atlas/blob/dk-final/src/app/App.tsx) (App state flow), [`api_main.py`](https://github.com/governai-techteam/research-atlas/blob/dk-final/api_main.py) (FastAPI endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_app["App state flow<br/>[App.tsx]"]
  node_landing["Topic entry<br/>[LandingPage.tsx]"]
  node_loading["Loading view<br/>[LoadingScreen.tsx]"]
  node_api_client["Atlas API client<br/>[atlasApi.ts]"]
  node_dashboard["Atlas dashboard<br/>[AtlasDashboard.tsx]"]
  node_overview["Executive overview"]
  node_paper_cards["Paper cards<br/>[PaperCard.tsx]"]
  node_repo_cards["Repository cards<br/>[RepoCard.tsx]"]
  node_resource_cards["Resource cards<br/>[ResourceCard.tsx]"]
  node_knowledge_graph["Knowledge graph<br/>[KnowledgeGraph.tsx]"]
end

subgraph group_api["API and orchestration"]
  node_api["FastAPI endpoints<br/>[api_main.py]"]
  node_atlas_service["Atlas orchestration<br/>[atlas_service.py]"]
  node_schema["Atlas data schema<br/>[atlas_schema.py]"]
end

subgraph group_discovery["Discovery and ranking"]
  node_paper_service["Paper retrieval<br/>[paper_service.py]"]
  node_paper_ranking["Paper ranking<br/>[ranking_service.py]"]
  node_scoring["Scoring utilities<br/>[scoring_service.py]"]
  node_repo_service["Repository retrieval<br/>[github_service.py]"]
  node_repo_ranking["Repository ranking"]
end

subgraph group_knowledge["Knowledge enrichment"]
  node_resources["Governance resources"]
  node_extractor["Dataset and model extraction"]
  node_graph_service["Graph construction<br/>[graph_service.py]"]
  node_search_service["Vector search<br/>[search_service.py]"]
  node_vector_store["Vector store<br/>[vector_store.py]"]
  node_embedding["Text embeddings"]
end

subgraph group_sources["External sources"]
  node_openalex["OpenAlex"]
  node_github["GitHub Search"]
  node_chromadb[("ChromaDB")]
  node_sentence_transformers["Sentence Transformers"]
  node_resource_csv["Curated resource data"]
end

node_researcher(("Researcher"))

node_researcher -->|"enters topic"| node_landing
node_landing -->|"submits topic"| node_app
node_app -->|"shows progress"| node_loading
node_app -->|"requests Atlas"| node_api_client
node_api_client -->|"posts topic"| node_api
node_api -->|"dispatches Atlas"| node_atlas_service
node_atlas_service -->|"fetches papers"| node_paper_service
node_paper_service -->|"queries works"| node_openalex
node_atlas_service -->|"ranks papers"| node_paper_ranking
node_paper_ranking -->|"uses scoring"| node_scoring
node_atlas_service -->|"fetches repositories"| node_repo_service
node_repo_service -.->|"searches repositories"| node_github
node_atlas_service -->|"ranks repositories"| node_repo_ranking
node_repo_ranking -->|"embeds text"| node_embedding
node_embedding -->|"generates vectors"| node_sentence_transformers
node_atlas_service -->|"loads resources"| node_resources
node_resources -.->|"reads curated data"| node_resource_csv
node_atlas_service -->|"extracts datasets and models"| node_extractor
node_atlas_service -->|"stores papers"| node_vector_store
node_vector_store -->|"creates embeddings"| node_embedding
node_vector_store -.->|"persists vectors"| node_chromadb
node_search_service -->|"searches vectors"| node_vector_store
node_paper_ranking -->|"uses semantic search"| node_search_service
node_api -->|"dispatches graph"| node_graph_service
node_atlas_service -->|"creates Atlas"| node_schema
node_api -.->|"returns Atlas data"| node_schema
node_app -->|"renders results"| node_dashboard
node_dashboard -->|"renders overview"| node_overview
node_dashboard -->|"renders papers"| node_paper_cards
node_dashboard -->|"renders repositories"| node_repo_cards
node_dashboard -->|"renders resources"| node_resource_cards
node_dashboard -->|"builds graph data"| node_api_client
node_dashboard -->|"renders graph"| node_knowledge_graph

click node_app "https://github.com/governai-techteam/research-atlas/blob/dk-final/src/app/App.tsx"
click node_landing "https://github.com/governai-techteam/research-atlas/blob/dk-final/src/app/components/LandingPage.tsx"
click node_loading "https://github.com/governai-techteam/research-atlas/blob/dk-final/src/app/components/LoadingScreen.tsx"
click node_api_client "https://github.com/governai-techteam/research-atlas/blob/dk-final/src/app/services/atlasApi.ts"
click node_dashboard "https://github.com/governai-techteam/research-atlas/blob/dk-final/src/app/components/AtlasDashboard.tsx"
click node_overview "https://github.com/governai-techteam/research-atlas/blob/dk-final/src/app/components/OverviewSection.tsx"
click node_paper_cards "https://github.com/governai-techteam/research-atlas/blob/dk-final/src/app/components/PaperCard.tsx"
click node_repo_cards "https://github.com/governai-techteam/research-atlas/blob/dk-final/src/app/components/RepoCard.tsx"
click node_resource_cards "https://github.com/governai-techteam/research-atlas/blob/dk-final/src/app/components/ResourceCard.tsx"
click node_knowledge_graph "https://github.com/governai-techteam/research-atlas/blob/dk-final/src/app/components/KnowledgeGraph.tsx"
click node_api "https://github.com/governai-techteam/research-atlas/blob/dk-final/api_main.py"
click node_atlas_service "https://github.com/governai-techteam/research-atlas/blob/dk-final/services/atlas_service.py"
click node_schema "https://github.com/governai-techteam/research-atlas/blob/dk-final/models/atlas_schema.py"
click node_paper_service "https://github.com/governai-techteam/research-atlas/blob/dk-final/services/paper_service.py"
click node_paper_ranking "https://github.com/governai-techteam/research-atlas/blob/dk-final/services/ranking_service.py"
click node_scoring "https://github.com/governai-techteam/research-atlas/blob/dk-final/services/scoring_service.py"
click node_repo_service "https://github.com/governai-techteam/research-atlas/blob/dk-final/services/github_service.py"
click node_repo_ranking "https://github.com/governai-techteam/research-atlas/blob/dk-final/services/repo_ranking_service.py"
click node_resources "https://github.com/governai-techteam/research-atlas/blob/dk-final/services/resource_service.py"
click node_extractor "https://github.com/governai-techteam/research-atlas/blob/dk-final/services/extractor_service.py"
click node_graph_service "https://github.com/governai-techteam/research-atlas/blob/dk-final/services/graph_service.py"
click node_search_service "https://github.com/governai-techteam/research-atlas/blob/dk-final/services/search_service.py"
click node_vector_store "https://github.com/governai-techteam/research-atlas/blob/dk-final/services/vector_store.py"
click node_embedding "https://github.com/governai-techteam/research-atlas/blob/dk-final/services/embedding_service.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_app,node_landing,node_loading,node_api_client,node_dashboard,node_overview,node_paper_cards,node_repo_cards,node_resource_cards,node_knowledge_graph toneBlue
class node_api,node_atlas_service,node_schema toneAmber
class node_paper_service,node_paper_ranking,node_scoring,node_repo_service,node_repo_ranking toneMint
class node_resources,node_extractor,node_graph_service,node_search_service,node_vector_store,node_embedding toneRose
class node_openalex,node_github,node_chromadb,node_sentence_transformers,node_resource_csv,node_researcher toneIndigo
```

## Components

### User experience

- [App state flow](https://github.com/governai-techteam/research-atlas/blob/dk-final/src/app/App.tsx): `src/app/App.tsx`
- [Topic entry](https://github.com/governai-techteam/research-atlas/blob/dk-final/src/app/components/LandingPage.tsx): `src/app/components/LandingPage.tsx`
- [Loading view](https://github.com/governai-techteam/research-atlas/blob/dk-final/src/app/components/LoadingScreen.tsx): `src/app/components/LoadingScreen.tsx`
- [Atlas API client](https://github.com/governai-techteam/research-atlas/blob/dk-final/src/app/services/atlasApi.ts): `src/app/services/atlasApi.ts`
- [Atlas dashboard](https://github.com/governai-techteam/research-atlas/blob/dk-final/src/app/components/AtlasDashboard.tsx): `src/app/components/AtlasDashboard.tsx`
- [Executive overview](https://github.com/governai-techteam/research-atlas/blob/dk-final/src/app/components/OverviewSection.tsx): `src/app/components/OverviewSection.tsx`
- [Paper cards](https://github.com/governai-techteam/research-atlas/blob/dk-final/src/app/components/PaperCard.tsx): `src/app/components/PaperCard.tsx`
- [Repository cards](https://github.com/governai-techteam/research-atlas/blob/dk-final/src/app/components/RepoCard.tsx): `src/app/components/RepoCard.tsx`
- [Resource cards](https://github.com/governai-techteam/research-atlas/blob/dk-final/src/app/components/ResourceCard.tsx): `src/app/components/ResourceCard.tsx`
- [Knowledge graph](https://github.com/governai-techteam/research-atlas/blob/dk-final/src/app/components/KnowledgeGraph.tsx): `src/app/components/KnowledgeGraph.tsx`

### API and orchestration

- [FastAPI endpoints](https://github.com/governai-techteam/research-atlas/blob/dk-final/api_main.py): `api_main.py`
- [Atlas orchestration](https://github.com/governai-techteam/research-atlas/blob/dk-final/services/atlas_service.py): `services/atlas_service.py`
- [Atlas data schema](https://github.com/governai-techteam/research-atlas/blob/dk-final/models/atlas_schema.py): `models/atlas_schema.py`

### Discovery and ranking

- [Paper retrieval](https://github.com/governai-techteam/research-atlas/blob/dk-final/services/paper_service.py): `services/paper_service.py`
- [Paper ranking](https://github.com/governai-techteam/research-atlas/blob/dk-final/services/ranking_service.py): `services/ranking_service.py`
- [Scoring utilities](https://github.com/governai-techteam/research-atlas/blob/dk-final/services/scoring_service.py): `services/scoring_service.py`
- [Repository retrieval](https://github.com/governai-techteam/research-atlas/blob/dk-final/services/github_service.py): `services/github_service.py`
- [Repository ranking](https://github.com/governai-techteam/research-atlas/blob/dk-final/services/repo_ranking_service.py): `services/repo_ranking_service.py`

### Knowledge enrichment

- [Governance resources](https://github.com/governai-techteam/research-atlas/blob/dk-final/services/resource_service.py): `services/resource_service.py`
- [Dataset and model extraction](https://github.com/governai-techteam/research-atlas/blob/dk-final/services/extractor_service.py): `services/extractor_service.py`
- [Graph construction](https://github.com/governai-techteam/research-atlas/blob/dk-final/services/graph_service.py): `services/graph_service.py`
- [Vector search](https://github.com/governai-techteam/research-atlas/blob/dk-final/services/search_service.py): `services/search_service.py`
- [Vector store](https://github.com/governai-techteam/research-atlas/blob/dk-final/services/vector_store.py): `services/vector_store.py`
- [Text embeddings](https://github.com/governai-techteam/research-atlas/blob/dk-final/services/embedding_service.py): `services/embedding_service.py`

### External sources

- **OpenAlex**
- **GitHub Search**
- **ChromaDB**
- **Sentence Transformers**
- **Curated resource data**

### Other components

- **Researcher**

## Connections

- Researcher → Topic entry: enters topic
- Topic entry → App state flow: submits topic (evidence: `src/app/App.tsx`)
- App state flow → Loading view: shows progress (evidence: `src/app/App.tsx`)
- App state flow → Atlas API client: requests Atlas (evidence: `src/app/App.tsx`)
- Atlas API client → FastAPI endpoints: posts topic (evidence: `src/app/services/atlasApi.ts`)
- FastAPI endpoints → Atlas orchestration: dispatches Atlas (evidence: `api_main.py`)
- Atlas orchestration → Paper retrieval: fetches papers (evidence: `services/atlas_service.py`)
- Paper retrieval → OpenAlex: queries works (evidence: `services/paper_service.py`)
- Atlas orchestration → Paper ranking: ranks papers (evidence: `services/atlas_service.py`)
- Paper ranking → Scoring utilities: uses scoring (evidence: `services/ranking_service.py`)
- Atlas orchestration → Repository retrieval: fetches repositories (evidence: `services/atlas_service.py`)
- Repository retrieval → GitHub Search: searches repositories (evidence: `README.md`)
- Atlas orchestration → Repository ranking: ranks repositories (evidence: `services/atlas_service.py`)
- Repository ranking → Text embeddings: embeds text (evidence: `services/repo_ranking_service.py`)
- Text embeddings → Sentence Transformers: generates vectors (evidence: `services/embedding_service.py`)
- Atlas orchestration → Governance resources: loads resources (evidence: `services/atlas_service.py`)
- Governance resources → Curated resource data: reads curated data (evidence: `README.md`)
- Atlas orchestration → Dataset and model extraction: extracts datasets and models (evidence: `services/atlas_service.py`)
- Atlas orchestration → Vector store: stores papers (evidence: `services/atlas_service.py`)
- Vector store → Text embeddings: creates embeddings (evidence: `services/vector_store.py`)
- Vector store → ChromaDB: persists vectors (evidence: `README.md`)
- Vector search → Vector store: searches vectors (evidence: `services/search_service.py`)
- Paper ranking → Vector search: uses semantic search (evidence: `services/ranking_service.py`)
- FastAPI endpoints → Graph construction: dispatches graph (evidence: `api_main.py`)
- Atlas orchestration → Atlas data schema: creates Atlas (evidence: `services/atlas_service.py`)
- FastAPI endpoints → Atlas data schema: returns Atlas data
- App state flow → Atlas dashboard: renders results (evidence: `src/app/App.tsx`)
- Atlas dashboard → Executive overview: renders overview (evidence: `src/app/components/AtlasDashboard.tsx`)
- Atlas dashboard → Paper cards: renders papers (evidence: `src/app/components/AtlasDashboard.tsx`)
- Atlas dashboard → Repository cards: renders repositories (evidence: `src/app/components/AtlasDashboard.tsx`)
- Atlas dashboard → Resource cards: renders resources (evidence: `src/app/components/AtlasDashboard.tsx`)
- Atlas dashboard → Atlas API client: builds graph data (evidence: `src/app/components/AtlasDashboard.tsx`)
- Atlas dashboard → Knowledge graph: renders graph (evidence: `src/app/components/AtlasDashboard.tsx`)
