# suqingdong/pypubmed architecture

> Architecture diagram of the GitHub repository suqingdong/pypubmed, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/suqingdong/pypubmed
- Repository: https://github.com/suqingdong/pypubmed

## Overview

##### Project type and purpose
- This is an open-source, Python-based command-line toolkit (“pypubmed”) that lets users search NCBI PubMed/PMC, parse XML results, build advanced queries, and generate citation lists or export results (e.g., XLSX).

##### File structure
- Top-level files:
- setup.py, requirements.txt, build.sh – packaging, dependency and build scripts
- README.md, docs/ – user documentation, Sphinx-generated API docs
- pypubmed/ (main package) with subpackages:
- bin/ – CLI entry points: cli.py plus subcommands (_search.py, _citations.py)
- core/ – domain logic: article model, citations logic, eutils (Entrez calls), export routines
- util/ – XML parsers for PubMed and PMC formats
- version/ – release metadata
- src/ appears empty or placeholder

##### README for additional insights
- Describes commands: search, advance-search, citations
- Shows that HTTP calls to NCBI E-utilities occur, results get parsed and exported
- Mentions future TODOs (HTML/PDF output, GUI), suggesting extension points

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    User(("User")):::external

    %% CLI Layer
    subgraph "CLI Layer"
        CLI_cli["cli.py"]:::internal
        CLI_search["_search.py"]:::internal
        CLI_citations["_citations.py"]:::internal
    end

    %% Core Logic
    subgraph "Core Logic"
        subgraph "Domain Models & Orchestration"
            Domain_article["article.py"]:::internal
            Domain_citations["citations.py"]:::internal
        end
        subgraph "External API Client"
            API_client["eutils.py"]:::internal
        end
        subgraph "Export Engine"
            Export_engine["export.py"]:::internal
        end
    end

    %% Utility Parsers
    subgraph "Utility Parsers"
        Parser_pubmed["pubmed_xml_parser.py"]:::internal
        Parser_pmc["pmc_xml_parser.py"]:::internal
    end

    %% External Service
    NCBI[(NCBI Entrez API)]:::external

    %% I/O Outputs
    subgraph "Local Output"
        Filesystem[(Filesystem)]:::io
        Console[(Console STDOUT)]:::io
    end

    %% Documentation & Packaging & Version
    README["README.md"]:::internal
    Docs["docs/"]:::internal
    Setup["setup.py"]:::internal
    Req["requirements.txt"]:::internal
    Build["build.sh"]:::internal
    Version["version.json"]:::internal

    %% Connections
    User --> CLI_cli
    CLI_cli --> CLI_search
    CLI_cli --> CLI_citations

    CLI_search --> Domain_article
    CLI_citations --> Domain_citations

    Domain_article --> API_client
    Domain_citations --> API_client

    API_client -->|HTTP Request| NCBI
    NCBI -->|XML Response| API_client

    API_client --> Domain_article
    API_client --> Domain_citations

    Domain_article --> Parser_pubmed
    Domain_citations --> Parser_pmc
    Parser_pubmed --> Domain_article
    Parser_pmc --> Domain_citations

    Domain_article --> Export_engine
    Domain_citations --> Export_engine

    Export_engine --> Filesystem
    Export_engine --> Console

    %% Side components
    Setup --- CLI_cli
    Req --- CLI_cli
    Build --- CLI_cli
    README --- CLI_cli
    Docs --- CLI_cli
    Version --- CLI_cli

    %% Click Events
    click CLI_cli "https://github.com/suqingdong/pypubmed/blob/master/pypubmed/bin/cli.py"
    click CLI_search "https://github.com/suqingdong/pypubmed/blob/master/pypubmed/bin/_search.py"
    click CLI_citations "https://github.com/suqingdong/pypubmed/blob/master/pypubmed/bin/_citations.py"
    click Domain_article "https://github.com/suqingdong/pypubmed/blob/master/pypubmed/core/article.py"
    click Domain_citations "https://github.com/suqingdong/pypubmed/blob/master/pypubmed/core/citations.py"
    click API_client "https://github.com/suqingdong/pypubmed/blob/master/pypubmed/core/eutils.py"
    click Export_engine "https://github.com/suqingdong/pypubmed/blob/master/pypubmed/core/export.py"
    click Parser_pubmed "https://github.com/suqingdong/pypubmed/blob/master/pypubmed/util/pubmed_xml_parser.py"
    click Parser_pmc "https://github.com/suqingdong/pypubmed/blob/master/pypubmed/util/pmc_xml_parser.py"
    click README "https://github.com/suqingdong/pypubmed/blob/master/README.md"
    click Docs "https://github.com/suqingdong/pypubmed/tree/master/docs/"
    click Setup "https://github.com/suqingdong/pypubmed/blob/master/setup.py"
    click Req "https://github.com/suqingdong/pypubmed/blob/master/requirements.txt"
    click Build "https://github.com/suqingdong/pypubmed/blob/master/build.sh"
    click Version "https://github.com/suqingdong/pypubmed/blob/master/pypubmed/version/version.json"

    %% Styles
    classDef internal fill:#AEDFF7,stroke:#1B4F72,color:#0B5345
    classDef external fill:#A9DFBF,stroke:#145A32,color:#145A32
    classDef io fill:#F9E79F,stroke:#B9770E,color:#6E2C00
```
