# anoopkcn/obsidian-reference-map architecture

> Architecture diagram of the GitHub repository anoopkcn/obsidian-reference-map, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anoopkcn/obsidian-reference-map
- Repository: https://github.com/anoopkcn/obsidian-reference-map

## Overview

This project is an Obsidian plugin called “Reference Map” that enhances reference and citation management within the Obsidian note-taking ecosystem. Its primary purpose is to provide a sidebar view for managing references, quickly searching for papers online, and visualizing literature connections through a graph view. The project architecture is centered around enhancing the Obsidian application with additional UI panels and functionalities, while integrating with external APIs (Semantic Scholar, Zotero, arXiv, etc.) to fetch and display bibliographic metadata.

##### Main Components Identification
- Plugin Core / Entry Point: The main module (src/main.ts) initializes the plugin and wires up commands, settings, and event listeners.
- UI Components:
– Sidebar Views: Components for the Reference Map Sidebar (IndexPaperCard, PaperList, PaperHeading, PaperButtons, etc.)
– Graph View: Components for displaying the literature graph (GraphView, ReferenceMapGraph)
– Search Modals: Components for search functionality (SearchModal, SuggestModal)
– Settings Panel: Components to configure plugin behavior (ButtonSettings, SettingItem, ZoteroPullSettings, etc.)
- API Interfaces:
– External API Communication: Modules providing functions to interact with external services (src/apis/s2agAPI.ts and associated types)
– Data Fetching & Update Checking: Modules for updateChecker.ts and viewManager.ts
- Data and Localization:
– Data Files: Static reference data and update check logic found in src/data.
– Localization: A set of language files stored in src/lang/locale, along with helper utilities.
- Utility Modules: Various helper functions (in src/utils) to process CSL formats, parse metadata, handle postprocessing, and interact with Zotero.
- Configuration & Build: Configuration files (esbuild.config.mjs, tsconfig.json, etc.) and deployment scripts (GitHub workflows, version bump scripts) that facilitate building and releasing the plugin.

##### Relationships and Interactions
- The Plugin Core interacts directly with Obsidian's plugin API to register commands (search, create, open graph, etc.) and set up the sidebar.
- UI Components communicate internally via shared context (see src/context.tsx) and update the display dynamically as data changes.
- The API modules are loosely coupled with UI components; they fetch data from external sources and then pass on results to the UI layer.
- Utility modules are used across the code base to manage data transformations, parsing, and other processing tasks.
- The localization module ensures that UI components use the correct language strings based on user settings.

##### Architectural Patterns and Design Principles
- Component-Based Architecture: The user interface is built using discrete, reusable components (React-style .tsx files) that collectively create the various views (sidebar, modal, graph).
- Separation of Concerns: The system clearly separates data retrieval (APIs), data processing (utils and data modules), and presentation (components).
- Configuration Driven Behavior: Settings and user customizations are handled in separate modules and exposed in an Obsidian settings tab.
- Integration with External Services: The plugin follows a loosely coupled integration with external references and metadata providers, using defined abstractions in the API layer.

##### Detailed Representation
– UI Layer (Sidebar, Graph, Search, Settings)
– Data and API Modules
– Utilities and Localization
- Visually embed external dependencies (Semantic Scholar, Zotero, arXiv, etc.) and show how API calls are made from the Data Layer.
- Configuration files and build scripts on the periphery to represent how the system is maintained and deployed.

- Every component (as listed above) is clearly labeled and placed within its logical grouping.
- Incorporate notes or annotations if needed to explain relationships (e.g., “Plugin listens for file events to update dynamically based on document frontmatter keywords”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Core Layer
    subgraph "Application Core Layer"
        PluginCore("Plugin Core"):::core
    end

    %% UI Layer
    subgraph "UI Layer"
        subgraph "Sidebar Views"
            SidebarPanel("Sidebar Panel"):::ui
            ReferenceList("Reference List"):::ui
            IndexPaperCard("Index Paper Card"):::ui
            PaperHeading("Paper Heading"):::ui
            PaperButtons("Paper Buttons"):::ui
            PaperCard("Paper Card"):::ui
            PaperList("Paper List"):::ui
        end
        subgraph "Graph View"
            GraphView("Graph View"):::ui
            ReferenceMapGraph("Reference Map Graph"):::ui
        end
        subgraph "Search Modals"
            SearchModal("Search Modal"):::ui
            SuggestModal("Suggest Modal"):::ui
        end
        subgraph "Settings Panel"
            Settings("Settings"):::ui
            SettingItem("Setting Item"):::ui
            ZoteroPullSettings("Zotero Pull Settings"):::ui
            ButtonSettings("Button Settings"):::ui
            ListSuggest("List Suggest"):::ui
            Suggest("Suggest"):::ui
        end
    end

    %% Data & Service Layer
    subgraph "Data & Service Layer"
        subgraph "API Interfaces"
            S2agAPI("Semantic Scholar API"):::api
            S2agTypes("S2ag Types"):::api
            BibTypes("Bibliographic Types"):::api
        end
        subgraph "Data Management"
            Data("Data Management"):::api
            UpdateChecker("Update Checker"):::api
            ViewManager("View Manager"):::api
        end
    end

    %% Utility & Support Layer
    subgraph "Utility & Support Layer"
        LocalizationHelper("Localization Helper"):::util
        LocaleFiles("Locale Files"):::util
        Utilities("Utility Modules"):::util
        Context("Context Management"):::util
    end

    %% External Systems
    SemanticScholar("Semantic Scholar"):::external
    Zotero("Zotero"):::external
    arXiv("arXiv"):::external

    %% Relationships and Interactions
    PluginCore -->|"init_sidebar"| SidebarPanel
    PluginCore -->|"init_graph"| GraphView
    PluginCore -->|"init_search"| SearchModal
    PluginCore -->|"init_settings"| Settings
    PluginCore -->|"fetch_metadata"| S2agAPI
    PluginCore -->|"update_data"| Data
    PluginCore -->|"setup_context"| Context

    SidebarPanel -->|"display_data"| Data
    SearchModal -->|"trigger_search"| S2agAPI
    GraphView -->|"update_graph"| ViewManager

    S2agAPI -->|"calls_SemanticScholar"| SemanticScholar
    S2agAPI -->|"calls_arXiv"| arXiv
    ZoteroPullSettings -->|"calls_Zotero"| Zotero

    Data -->|"check_update"| UpdateChecker
    Data -->|"manage_views"| ViewManager

    Settings -->|"localized_by"| LocalizationHelper

    Context -->|"propagates_to"| SidebarPanel
    Context -->|"propagates_to"| GraphView
    Context -->|"propagates_to"| SearchModal
    Context -->|"propagates_to"| Settings

    %% Click Events
    click PluginCore "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/main.ts"
    click SidebarPanel "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/sidebar/SidebarView.tsx"
    click ReferenceList "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/sidebar/ReferenceMapList.tsx"
    click IndexPaperCard "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/components/IndexPaperCard.tsx"
    click PaperHeading "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/components/PaperHeading.tsx"
    click PaperButtons "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/components/PaperButtons.tsx"
    click PaperCard "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/components/PaperCard.tsx"
    click PaperList "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/components/PaperList.tsx"
    click GraphView "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/graph/GraphView.tsx"
    click ReferenceMapGraph "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/graph/ReferenceMapGraph.tsx"
    click SearchModal "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/search/SearchModal.tsx"
    click SuggestModal "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/search/SuggestModal.tsx"
    click Settings "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/settings/settings.tsx"
    click SettingItem "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/settings/SettingItem.tsx"
    click ZoteroPullSettings "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/settings/ZoteroPullSettings.tsx"
    click ButtonSettings "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/settings/ButtonSettings.tsx"
    click ListSuggest "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/settings/list-suggest.ts"
    click Suggest "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/settings/suggest.ts"
    click S2agAPI "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/apis/s2agAPI.ts"
    click S2agTypes "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/apis/s2agTypes.ts"
    click BibTypes "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/apis/bibTypes.ts"
    click Data "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/data/data.ts"
    click UpdateChecker "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/data/updateChecker.ts"
    click ViewManager "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/data/viewManager.ts"
    click LocalizationHelper "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/lang/helpers.ts"
    click LocaleFiles "https://github.com/anoopkcn/obsidian-reference-map/tree/master/src/lang/locale"
    click Utilities "https://github.com/anoopkcn/obsidian-reference-map/tree/master/src/utils"
    click Context "https://github.com/anoopkcn/obsidian-reference-map/blob/master/src/context.tsx"

    %% Styling
    classDef core fill:#FFC300,stroke:#333,stroke-width:2px;
    classDef ui fill:#33CCFF,stroke:#333,stroke-width:2px;
    classDef api fill:#99FF99,stroke:#333,stroke-width:2px;
    classDef util fill:#FF99CC,stroke:#333,stroke-width:2px;
    classDef external fill:#C0C0C0,stroke:#333,stroke-width:2px;
```
