# ulviyabasova/litreviewkit architecture

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

- Interactive diagram: https://gitdiagram.com/ulviyabasova/litreviewkit
- Repository: https://github.com/ulviyabasova/litreviewkit

## Overview

LitReviewKit is a Streamlit workspace for literature discovery and review. Users search scholarly APIs or import Scopus/Web of Science exports; records are normalized, screened against terms, and deduplicated before review. They can manually screen records, inspect project metrics, and export review artifacts. Projects persist in SQLite, while session data is lost on restart. Optional chat uses matching abstracts and an OpenAI key. The repository is a single source file, so component paths share that file; some internal wiring is documented in the README but not visible in the sampled excerpts.

Main entry points: [`litreviewkit_app.py`](https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py) (Live search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Discovery and import"]
  node_search["Live search"]
  node_import["Export import"]
  node_normalize["Normalize records"]
  node_termfilter["Term screening"]
  node_dedupe["Duplicate merge"]
end

subgraph group_review["Review workflow"]
  node_outcomes["Query outcomes"]
  node_manual["Manual screening"]
end

subgraph group_workspace["Project workspace"]
  node_app["Streamlit app"]
  node_dashboard["Review dashboard"]
  node_exports["Review exports"]
  node_projects["Project management"]
  node_projectdb[("Project database")]
  node_chat["Literature chat"]
end

subgraph group_integrations["External services"]
  node_crossref["Crossref"]
  node_openalex["OpenAlex"]
  node_semantic["Semantic Scholar"]
  node_openai["OpenAI API"]
end

node_researcher(("Researcher"))
node_exportfiles["Scopus / WoS files"]
node_exportformats["Excel / CSV / protocol JSON"]

node_researcher -->|"uses"| node_app
node_app -->|"starts search"| node_search
node_search -->|"queries"| node_crossref
node_search -->|"queries"| node_openalex
node_search -->|"queries"| node_semantic
node_researcher -->|"selects exports"| node_import
node_exportfiles -->|"loads records"| node_import
node_search -->|"returns records"| node_normalize
node_import -->|"returns records"| node_normalize
node_normalize -->|"screens terms"| node_termfilter
node_termfilter -->|"passes matches"| node_dedupe
node_dedupe -->|"records outcomes"| node_outcomes
node_outcomes -->|"presents records"| node_manual
node_manual -->|"updates review"| node_dashboard
node_manual -->|"provides review data"| node_exports
node_exports -->|"writes"| node_exportformats
node_researcher -->|"manages project"| node_projects
node_projects -->|"saves / loads"| node_projectdb
node_researcher -->|"asks question"| node_chat
node_chat -.->|"sends question and abstracts"| node_openai

click node_app "https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py"
click node_search "https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py"
click node_import "https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py"
click node_normalize "https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py"
click node_termfilter "https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py"
click node_dedupe "https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py"
click node_outcomes "https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py"
click node_manual "https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py"
click node_dashboard "https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py"
click node_exports "https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py"
click node_projects "https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py"
click node_projectdb "https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py"
click node_chat "https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.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_search,node_import,node_normalize,node_termfilter,node_dedupe toneBlue
class node_outcomes,node_manual toneAmber
class node_app,node_dashboard,node_exports,node_projects,node_projectdb,node_chat toneMint
class node_crossref,node_openalex,node_semantic,node_openai toneRose
class node_researcher,node_exportfiles,node_exportformats toneIndigo
```

## Components

### Discovery and import

- [Live search](https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py): `litreviewkit_app.py`
- [Export import](https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py): `litreviewkit_app.py`
- [Normalize records](https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py): `litreviewkit_app.py`
- [Term screening](https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py): `litreviewkit_app.py`
- [Duplicate merge](https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py): `litreviewkit_app.py`

### Review workflow

- [Query outcomes](https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py): `litreviewkit_app.py`
- [Manual screening](https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py): `litreviewkit_app.py`

### Project workspace

- [Streamlit app](https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py): `litreviewkit_app.py`
- [Review dashboard](https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py): `litreviewkit_app.py`
- [Review exports](https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py): `litreviewkit_app.py`
- [Project management](https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py): `litreviewkit_app.py`
- [Project database](https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py): `litreviewkit_app.py`
- [Literature chat](https://github.com/ulviyabasova/litreviewkit/blob/main/litreviewkit_app.py): `litreviewkit_app.py`

### External services

- **Crossref**
- **OpenAlex**
- **Semantic Scholar**
- **OpenAI API**

### Other components

- **Researcher**
- **Scopus / WoS files**
- **Excel / CSV / protocol JSON**

## Connections

- Researcher → Streamlit app: uses
- Streamlit app → Live search: starts search
- Live search → Crossref: queries
- Live search → OpenAlex: queries
- Live search → Semantic Scholar: queries
- Researcher → Export import: selects exports
- Scopus / WoS files → Export import: loads records
- Live search → Normalize records: returns records
- Export import → Normalize records: returns records
- Normalize records → Term screening: screens terms
- Term screening → Duplicate merge: passes matches
- Duplicate merge → Query outcomes: records outcomes
- Query outcomes → Manual screening: presents records
- Manual screening → Review dashboard: updates review
- Manual screening → Review exports: provides review data
- Review exports → Excel / CSV / protocol JSON: writes
- Researcher → Project management: manages project
- Project management → Project database: saves / loads
- Researcher → Literature chat: asks question
- Literature chat → OpenAI API: sends question and abstracts