# ibrahimomeer/sourcly architecture

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

- Interactive diagram: https://gitdiagram.com/ibrahimomeer/sourcly
- Repository: https://github.com/ibrahimomeer/sourcly

## Overview

Sourcly is a browser-only scholarly search and research workflow. A user query is interpreted as concepts, sent to selected scholarly sources, then merged, ranked, filtered and displayed with explanations; users can also look up a work, explore counterarguments, save references and export a search protocol. The graph combines sampled implementation evidence with README-documented capabilities; unsampled feature internals are represented by their existing source paths, and unsupported call details are omitted.

Main entry points: [`apps/web/src/App.tsx`](https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/App.tsx) (App shell), [`apps/web/src/useSearch.ts`](https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/useSearch.ts) (Search orchestration), [`apps/web/src/providers.ts`](https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/providers.ts) (Provider dispatch), [`apps/web/src/pipeline.ts`](https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/pipeline.ts) (Merge and ranking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["App shell<br/>[App.tsx]"]
  node_search_ui["Search interface<br/>[SearchBox.tsx]"]
  node_results_ui["Results display<br/>[Results.tsx]"]
  node_settings["Search settings<br/>[SettingsPanel.tsx]"]
end

subgraph group_search["Search and ranking"]
  node_query_prep["Query preparation<br/>[queryText.ts]"]
  node_search_flow["Search orchestration<br/>[useSearch.ts]"]
  node_search_state["Search state<br/>[searchState.ts]"]
  node_provider_dispatch["Provider dispatch<br/>[providers.ts]"]
  node_concept_model["Concept modeling<br/>[concepts.ts]"]
  node_query_render["Source query rendering<br/>[conceptquery.ts]"]
  node_search_engine["Search engine<br/>[search.ts]"]
  node_result_pipeline["Merge and ranking<br/>[pipeline.ts]"]
end

subgraph group_research["Research tools"]
  node_lookup["Work lookup<br/>[useLookup.ts]"]
  node_counterarguments["Counterarguments<br/>[counter.ts]"]
  node_saved["Saved references<br/>[saved.ts]"]
  node_apa["APA citations<br/>[apa.ts]"]
  node_protocol["Protocol export<br/>[protocolRecord.ts]"]
end

subgraph group_integrations["External sources"]
  node_provider_adapters["Source adapters"]
  node_scholarly_apis[("Scholarly databases")]
  node_unpaywall[("Unpaywall")]
end

node_researcher(("Researcher"))

node_researcher -->|"enters query"| node_search_ui
node_search_ui -->|"submits search"| node_app
node_app -->|"prepares query"| node_query_prep
node_query_prep -->|"parses concepts"| node_concept_model
node_concept_model -->|"renders source queries"| node_query_render
node_app -->|"starts search"| node_search_flow
node_search_flow -->|"dispatches sources"| node_provider_dispatch
node_provider_dispatch -->|"queries sources"| node_scholarly_apis
node_provider_adapters -->|"fetches metadata"| node_scholarly_apis
node_provider_dispatch -->|"uses adapters"| node_provider_adapters
node_search_flow -->|"records updates"| node_search_state
node_app -->|"ranks results"| node_result_pipeline
node_result_pipeline -->|"provides ranked results"| node_results_ui
node_result_pipeline -->|"uses search logic"| node_search_engine
node_researcher -->|"requests work"| node_lookup
node_app -->|"routes identifier lookup"| node_lookup
node_researcher -->|"starts counter-search"| node_counterarguments
node_researcher -->|"saves works"| node_saved
node_saved -->|"formats references"| node_apa
node_researcher -->|"exports protocol"| node_protocol
node_researcher -->|"configures search"| node_settings
node_lookup -.->|"checks PDF links"| node_unpaywall

click node_app "https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/App.tsx"
click node_search_ui "https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/SearchBox.tsx"
click node_results_ui "https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/Results.tsx"
click node_query_prep "https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/queryText.ts"
click node_search_flow "https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/useSearch.ts"
click node_search_state "https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/searchState.ts"
click node_provider_dispatch "https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/providers.ts"
click node_concept_model "https://github.com/ibrahimomeer/sourcly/blob/main/packages/core/src/concepts.ts"
click node_query_render "https://github.com/ibrahimomeer/sourcly/blob/main/packages/core/src/conceptquery.ts"
click node_search_engine "https://github.com/ibrahimomeer/sourcly/blob/main/packages/core/src/search.ts"
click node_result_pipeline "https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/pipeline.ts"
click node_provider_adapters "https://github.com/ibrahimomeer/sourcly/tree/main/packages/core/src/providers"
click node_lookup "https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/useLookup.ts"
click node_counterarguments "https://github.com/ibrahimomeer/sourcly/blob/main/packages/core/src/counter.ts"
click node_saved "https://github.com/ibrahimomeer/sourcly/blob/main/packages/core/src/saved.ts"
click node_apa "https://github.com/ibrahimomeer/sourcly/blob/main/packages/core/src/apa.ts"
click node_protocol "https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/protocolRecord.ts"
click node_settings "https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/SettingsPanel.tsx"

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_search_ui,node_results_ui,node_settings toneBlue
class node_query_prep,node_search_flow,node_search_state,node_provider_dispatch,node_concept_model,node_query_render,node_search_engine,node_result_pipeline toneAmber
class node_lookup,node_counterarguments,node_saved,node_apa,node_protocol toneMint
class node_provider_adapters,node_scholarly_apis,node_unpaywall toneRose
class node_researcher toneIndigo
```

## Components

### Web experience

- [App shell](https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Search interface](https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/SearchBox.tsx): `apps/web/src/SearchBox.tsx`
- [Results display](https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/Results.tsx): `apps/web/src/Results.tsx`
- [Search settings](https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/SettingsPanel.tsx): `apps/web/src/SettingsPanel.tsx`

### Search and ranking

- [Query preparation](https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/queryText.ts): `apps/web/src/queryText.ts`
- [Search orchestration](https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/useSearch.ts): `apps/web/src/useSearch.ts`
- [Search state](https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/searchState.ts): `apps/web/src/searchState.ts`
- [Provider dispatch](https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/providers.ts): `apps/web/src/providers.ts`
- [Concept modeling](https://github.com/ibrahimomeer/sourcly/blob/main/packages/core/src/concepts.ts): `packages/core/src/concepts.ts`
- [Source query rendering](https://github.com/ibrahimomeer/sourcly/blob/main/packages/core/src/conceptquery.ts): `packages/core/src/conceptquery.ts`
- [Search engine](https://github.com/ibrahimomeer/sourcly/blob/main/packages/core/src/search.ts): `packages/core/src/search.ts`
- [Merge and ranking](https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/pipeline.ts): `apps/web/src/pipeline.ts`

### Research tools

- [Work lookup](https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/useLookup.ts): `apps/web/src/useLookup.ts`
- [Counterarguments](https://github.com/ibrahimomeer/sourcly/blob/main/packages/core/src/counter.ts): `packages/core/src/counter.ts`
- [Saved references](https://github.com/ibrahimomeer/sourcly/blob/main/packages/core/src/saved.ts): `packages/core/src/saved.ts`
- [APA citations](https://github.com/ibrahimomeer/sourcly/blob/main/packages/core/src/apa.ts): `packages/core/src/apa.ts`
- [Protocol export](https://github.com/ibrahimomeer/sourcly/blob/main/apps/web/src/protocolRecord.ts): `apps/web/src/protocolRecord.ts`

### External sources

- [Source adapters](https://github.com/ibrahimomeer/sourcly/tree/main/packages/core/src/providers): `packages/core/src/providers`
- **Scholarly databases**
- **Unpaywall**

### Other components

- **Researcher**

## Connections

- Researcher → Search interface: enters query
- Search interface → App shell: submits search (evidence: `apps/web/src/App.tsx`)
- App shell → Query preparation: prepares query (evidence: `apps/web/src/App.tsx`)
- Query preparation → Concept modeling: parses concepts (evidence: `apps/web/src/queryText.ts`)
- Concept modeling → Source query rendering: renders source queries (evidence: `packages/core/src/conceptquery.ts`)
- App shell → Search orchestration: starts search (evidence: `apps/web/src/App.tsx`)
- Search orchestration → Provider dispatch: dispatches sources (evidence: `apps/web/src/useSearch.ts`)
- Provider dispatch → Scholarly databases: queries sources
- Source adapters → Scholarly databases: fetches metadata (evidence: `packages/core/src/providers/shared.ts`)
- Provider dispatch → Source adapters: uses adapters
- Search orchestration → Search state: records updates (evidence: `apps/web/src/searchState.ts`)
- App shell → Merge and ranking: ranks results (evidence: `apps/web/src/App.tsx`)
- Merge and ranking → Results display: provides ranked results
- Merge and ranking → Search engine: uses search logic (evidence: `apps/web/src/pipeline.ts`)
- Researcher → Work lookup: requests work
- App shell → Work lookup: routes identifier lookup (evidence: `apps/web/src/App.tsx`)
- Researcher → Counterarguments: starts counter-search
- Researcher → Saved references: saves works
- Saved references → APA citations: formats references (evidence: `packages/core/src/index.ts`)
- Researcher → Protocol export: exports protocol
- Researcher → Search settings: configures search
- Work lookup → Unpaywall: checks PDF links