# magikcarp/snakecite architecture

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

- Interactive diagram: https://gitdiagram.com/magikcarp/snakecite
- Repository: https://github.com/magikcarp/snakecite

## Overview

##### Project type and purpose
- snakecite is a lightweight, command-line Python tool that automates retrieval and generation of citation information (BibTeX/JSON) for the packages used in a Snakemake workflow or plain requirements files.
- It is not a web service or microservice suite, but a single‐process CLI application that orchestrates a pipeline of sub‐components: input parsing, metadata retrieval (PyPI, Bioconda, Anaconda, GitHub), formatting, and output.

##### File structure
- Top-level files:
- pyproject.toml – build configuration & entry point
- README.md – documentation
- tests/ – unit tests
- src/snakecite/
- __main__.py – CLI entrypoint and argument parsing
- cite.py – core logic: parsing inputs, querying APIs, formatting citations
- tests/test_cite.py – verifies citation retrieval and formatting

##### README for additional insights
- Supports three input modes: DOI URL, requirements.txt, environment.yaml (or directories of Snakemake YAML files).
- Queries external registries: PyPI, Bioconda, Anaconda; falls back to GitHub API for author metadata.
- Produces BibTeX or JSON; writes to STDOUT or file.
- All-batteries-included: uses only Python standard library.

##### Main components and their interactions
a. Components
1. CLI Interface (in __main__.py)
2. Input Parser (requirements.txt, environment.yaml, Snakemake workflows)
3. Citation Retriever
– PyPI API Client
– Bioconda/Anaconda Registry Client
– GitHub API Client (with optional token)
4. Citation Generator (formats metadata into BibTeX/JSON)
5. Output Writer (stdout or file)
6. Logging / Error Handler
7. Tests (isolated against cite.py functions)
b. Relationships & data flow
- User invokes “snakecite” → CLI Interface
- CLI parses arguments → hands off to Input Parser → emits list of package identifiers
- For each package:
– Citation Retriever queries external services in sequence (PyPI → Bioconda → Anaconda → GitHub fallback)
– Returns normalized metadata (authors, title, DOI, URL)
- Citation Generator formats metadata → structured BibTeX or JSON object
- Output Writer streams formatted citations to STDOUT or writes to designated file
- Logging component captures errors/warnings (e.g., rate limiting), surfaces to user
c. Architectural patterns & design principles
– Pipeline / chain of responsibility: each stage has single responsibility
– Dependency inversion: core logic in cite.py is decoupled from data sources via client abstractions
– Pure-function style in retrieval and formatting modules → high test coverage
d. Key technologies and libraries
– Python standard library (argparse, json, urllib.request, xml)
– pytest for testing
– GitHub REST API (via urllib)
– PyPI JSON endpoints
– YAML parsing (via standard library’s minimal safe parser if needed)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Layer 1: CLI / Argument Parsing"
        CLI["CLI Interface\n(__main__.py)"]:::internal
    end

    subgraph "Layer 2: Input Handlers"
        Parser["Input Parser\n(cite.py)"]:::internal
    end

    subgraph "Layer 3: Citation Retrieval Services"
        Pypi["PyPI API Client"]:::external
        Bioconda["Bioconda Client"]:::external
        Anaconda["Anaconda Client"]:::external
        GitHub["GitHub API Client"]:::external
    end

    subgraph "Layer 4: Formatting & Output"
        Generator["Citation Generator\n(cite.py)"]:::internal
        Writer["Output Writer\n(cite.py & __main__.py)"]:::internal
    end

    Logging["Logging / Error Handler\n(cite.py)"]:::util
    Tests["Tests\n(test_cite.py)"]:::util

    CLI -->|"invokes"| Parser
    Parser -->|"list of packages"| Pypi
    Pypi -->|"metadata JSON"| Generator
    Pypi -.-> Bioconda
    Bioconda -.-> Anaconda
    Anaconda -.-> GitHub
    Generator -->|"formatted citations"| Writer
    CLI -.->|"errors/warnings"| Logging
    Parser -.-> Logging
    Generator -.-> Logging
    Writer -.-> Logging
    Tests -->|"imports functions"| Parser

    click CLI "https://github.com/magikcarp/snakecite/blob/main/src/snakecite/__main__.py"
    click Parser "https://github.com/magikcarp/snakecite/blob/main/src/snakecite/cite.py"
    click Pypi "https://github.com/magikcarp/snakecite/blob/main/src/snakecite/cite.py"
    click Bioconda "https://github.com/magikcarp/snakecite/blob/main/src/snakecite/cite.py"
    click Anaconda "https://github.com/magikcarp/snakecite/blob/main/src/snakecite/cite.py"
    click GitHub "https://github.com/magikcarp/snakecite/blob/main/src/snakecite/cite.py"
    click Generator "https://github.com/magikcarp/snakecite/blob/main/src/snakecite/cite.py"
    click Writer "https://github.com/magikcarp/snakecite/blob/main/src/snakecite/__main__.py"
    click Logging "https://github.com/magikcarp/snakecite/blob/main/src/snakecite/cite.py"
    click Tests "https://github.com/magikcarp/snakecite/blob/main/tests/test_cite.py"

    classDef internal fill:#cce5ff,stroke:#004085,color:#004085
    classDef external fill:#d4edda,stroke:#155724,color:#155724
    classDef util fill:#e2e3e5,stroke:#d6d8db,color:#6c757d
    class CLI,Parser,Generator,Writer internal
    class Pypi,Bioconda,Anaconda,GitHub external
    class Logging,Tests util
```
