# griffithlab/civicpy architecture

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

- Interactive diagram: https://gitdiagram.com/griffithlab/civicpy
- Repository: https://github.com/griffithlab/civicpy

## Overview

##### Project type and purpose
- From the README and file tree, CIViCpy is an open-source Python client library and CLI analysis toolkit for the Clinical Interpretations of Variants in Cancer (CIViC) knowledgebase.
- It provides a programmable interface (via civicpy.civic) and a command-line tool (civicpy.cli) to query CIViC’s GraphQL API, process and cache results, and export data in common formats.

##### File structure
- Top-level code lives in the “civicpy” package:
- civic.py: core client class (HTTP/GraphQL orchestration)
- graphql_payloads.py: pre-built GraphQL query templates
- exports.py: routines to serialize data to CSV/TSV/JSON
- cli.py: command-line entry points and argument parsing
- utils.py: shared helpers (e.g., caching, rate-limit handling)
- data/: test fixtures and example cache
- tests/: unit tests for each module
- Supporting files: setup.py, Pipfile, Dockerfile, CI workflows (.github/workflows + .travis.yml), docs/ for Sphinx, examples/ notebooks.

##### README for additional insights
- Confirms the role of the library as a “Python client and analysis toolkit.”
- External dependency: CIViC’s public GraphQL endpoint.
- Encourages use in Jupyter (examples).

##### Main components & interactions
a. Internal Components
- CLI Interface (civicpy.cli)
- Core API Client (civicpy.civic)
- GraphQL Payload Builder (civicpy.graphql_payloads)
- Data Models & Caching (civicpy.utils + data/)
- Export Module (civicpy.exports)
b. External Services
- CIViC GraphQL API (public endpoint)
- Local filesystem or cache store (pickle cache)
- User environment (Jupyter notebooks, scripts)
c. CI/CD & Deployment (secondary)
- GitHub Actions / Travis CI pipelines (tests, lint, release)
- Docker container for reproducible environment
- PyPI for package distribution
d. Data Flows & Relationships
1. User invokes CLI or imports library in code/notebook
2. CLI calls Core API Client with user arguments
3. Core client uses GraphQL Payload Builder to assemble queries
4. Queries sent over HTTP to CIViC GraphQL API
5. JSON responses returned → parsed into Python objects
6. Data optionally cached via utils; subsequent calls read cache
7. Export module serializes objects to CSV/TSV/JSON or returns Pandas DataFrames
8. Output delivered to console, files, or notebook

##### Architectural patterns and design principles
- Modular design: separation of concerns (CLI, client logic, payloads, exports)
- Reuse of query templates (GraphQL payloads)
- Caching layer abstracts network latency
- Test coverage enforces reliability

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "civicpy package"
        CLI["CLI Interface"]:::internal
        Client["Core API Client"]:::internal
        Payload["GraphQL Payload Builder"]:::internal
        Utils["Data Models & Caching"]:::internal
        DataCache["Test Cache (data/test_cache.pkl)"]:::internal
        Export["Export Module"]:::internal
    end

    subgraph "Unit Tests Suite"
        Tests["civicpy/tests/"]:::tests
    end

    subgraph "CI/CD & Packaging"
        GH["GitHub Actions (release.yml, tests.yml)"]:::ci
        Travis["Travis CI (.travis.yml)"]:::ci
        Docker["Dockerfile"]:::ci
        Package["Package Config (setup.py, Pipfile, etc)"]:::config
    end

    subgraph "Documentation"
        Docs["docs/"]:::docs
    end

    subgraph "Examples / User Environment"
        Examples["examples/"]:::examples
        User["User Environment (Jupyter, scripts)"]:::external
    end

    subgraph "External Services"
        CIVICAPI["CIViC GraphQL API"]:::external
        FileSystem["Local FS / Cache"]:::external
    end

    User -->|imports or invokes| CLI
    User -->|imports library| Client
    CLI -->|calls| Client
    Client -->|uses| Payload
    Payload -->|"HTTP GraphQL Query"| CIVICAPI
    CIVICAPI -->|"JSON Response"| Client
    Client -->|caches via| Utils
    Utils -->|"pickle"| FileSystem
    Client -->|persists test data| DataCache
    Client -->|forwards data| Export
    Export -->|"CSV/TSV/JSON or DataFrame"| User

    Tests --> CLI
    Tests --> Client
    Tests --> Payload
    Tests --> Utils
    Tests --> Export

    GH --> Tests
    Travis --> Tests
    Package --> GH
    Docker --> GH

    Docs -->|build docs| Package
    Examples -->|demonstrate| Client

    classDef internal fill:#cce5ff,stroke:#004085,color:#004085;
    classDef external fill:#d4edda,stroke:#155724,color:#155724;
    classDef ci fill:#fff3cd,stroke:#856404,color:#856404;
    classDef tests fill:#f5c6cb,stroke:#721c24,color:#721c24;
    classDef docs fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef examples fill:#f0f0f0,stroke:#6a1b9a,color:#6a1b9a;
    classDef config fill:#ffe5b4,stroke:#cc7a00,color:#cc7a00;

    click CLI "https://github.com/griffithlab/civicpy/blob/master/civicpy/cli.py"
    click Client "https://github.com/griffithlab/civicpy/blob/master/civicpy/civic.py"
    click Payload "https://github.com/griffithlab/civicpy/blob/master/civicpy/graphql_payloads.py"
    click Utils "https://github.com/griffithlab/civicpy/blob/master/civicpy/utils.py"
    click DataCache "https://github.com/griffithlab/civicpy/blob/master/civicpy/data/test_cache.pkl"
    click Export "https://github.com/griffithlab/civicpy/blob/master/civicpy/exports.py"
    click Tests "https://github.com/griffithlab/civicpy/tree/master/civicpy/tests/"
    click GH "https://github.com/griffithlab/civicpy/tree/master/.github/workflows/"
    click Travis "https://github.com/griffithlab/civicpy/blob/master/.travis.yml"
    click Docker "https://github.com/griffithlab/civicpy/tree/master/Dockerfile"
    click Package "https://github.com/griffithlab/civicpy/blob/master/setup.py"
    click Docs "https://github.com/griffithlab/civicpy/tree/master/docs/"
    click Examples "https://github.com/griffithlab/civicpy/tree/master/examples/"
```
