# ivarurdalen/coinalyze architecture

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

- Interactive diagram: https://gitdiagram.com/ivarurdalen/coinalyze
- Repository: https://github.com/ivarurdalen/coinalyze

## Overview

##### Project Type and Purpose
- This is an open-source Python client library (“coinalyze”) that wraps the coinalyze.net REST API.
- Its goal is to provide Pythonic functions for each API endpoint, enforce rate limits, handle retries, and optionally convert JSON responses into pandas DataFrames.

##### File Structure Analysis
- Top-level: configuration (`.env.template`, `.github`, `pyproject.toml`), examples, scripts, tests.
- `src/coinalyze/`: the library package
- `client.py`: core `CoinalyzeClient`, HTTP logic, rate limiting, retries
- `constants.py`, `enums.py`, `types.py`: API constants, enums (e.g. endpoints, intervals), typing definitions
- `util/`: helpers for request building and pandas conversion
- `examples/`: sample CLI and Jupyter notebook showing typical usage
- `tests/`: pytest suite validating client methods and utilities

##### README Insights
- Uses httpx for HTTP calls, pyrate-limiter for 40 calls/min, httpx-retries for retry behavior
- Provides `response_to_df` convenience for DataFrame output
- Environment variable `COINALYZE_API_KEY` for authentication

a. Main Components
1. User Application (e.g. CLI script, Jupyter notebook, downstream code)
2. coinalyze Library
– `CoinalyzeClient`
– Rate Limiter (pyrate-limiter)
– HTTPX Client + Retry Layer (httpx-retries)
– Utilities (request builders, JSON→DataFrame)
– Constants/Enums/Types
3. External Service: coinalyze.net REST API
4. Optional: pandas for DataFrame conversion
b. Relationships & Data Flows
1. The User App imports `CoinalyzeClient` and configures it with API key
2. Client constructs HTTP requests, passing through Rate Limiter and Retry layers
3. HTTPX executes the request against the coinalyze REST endpoint
4. JSON response returns to Client → parsed/typed → optionally fed to pandas util
5. Final Python objects or DataFrame returned to User App
c. Architectural Patterns
– Wrapper/Facade pattern: `CoinalyzeClient` hides HTTP intricacies
– Decorator or middleware for rate limiting and retry logic on HTTP calls
– Separation of concerns: constants/enums/types vs. core client vs. utils
d. Key Technologies & Libraries
– httpx (HTTP client)
– pyrate-limiter (rate limiting)
– httpx-retries (retry middleware)
– pandas (DataFrame conversion)
– pytest (testing)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Examples
    subgraph "Example Usage" 
        direction TB
        CLI["CLI Script"]:::examples 
        NB["Jupyter Notebook"]:::examples
    end

    %% Config
    ENV[".env.template"]:::config

    %% Library Package
    subgraph "Coinalyze Library" 
        direction TB
        INIT["__init__.py"]:::internal 
        VER["__version__.py"]:::internal
        CLIENT["CoinalyzeClient\n(HTTP, Rate Limiting, Retries)"]:::internal
        CONST["Constants"]:::internal
        ENUM["Enums"]:::internal
        TYPES["Types"]:::internal
        subgraph "Utilities" 
            direction TB
            BASE["Request Builders & Helpers"]:::internal
            PANDAS["JSON→DataFrame"]:::internal
        end
    end

    %% External Service
    API["coinalyze.net\nREST API"]:::external

    %% Third-party libs
    RATE["pyrate-limiter"]:::library
    RETRY["httpx-retries"]:::library
    HTTPX["httpx"]:::library
    PANDAS_LIB["pandas"]:::library

    %% Tests
    subgraph "Test Suite" 
        direction TB
        TC["tests/test_client.py"]:::tests
        TU["tests/test_util.py"]:::tests
        CF["tests/conftest.py"]:::tests
    end

    %% Relationships
    CLI -->|"imports"| CLIENT
    NB -->|"imports"| CLIENT
    ENV -->|"provides API key"| CLIENT

    CLIENT -->|"uses"| RATE
    CLIENT -->|"uses"| RETRY
    CLIENT -->|"uses"| HTTPX
    CLIENT -->|"calls"| API

    CLIENT -->|"parses with"| CONST
    CLIENT -->|"parses with"| ENUM
    CLIENT -->|"parses with"| TYPES

    CLIENT -->|"builds requests"| BASE
    CLIENT -->|"converts JSON"| PANDAS

    PANDAS -->|"calls"| PANDAS_LIB

    API -->|"JSON response"| CLIENT

    TC -->|"tests"| CLIENT
    TU -->|"tests"| BASE & PANDAS

    %% Click Events
    click CLIENT "https://github.com/ivarurdalen/coinalyze/blob/main/src/coinalyze/client.py"
    click RATE "https://github.com/ivarurdalen/coinalyze/blob/main/src/coinalyze/client.py"
    click RETRY "https://github.com/ivarurdalen/coinalyze/blob/main/src/coinalyze/client.py"
    click HTTPX "https://github.com/ivarurdalen/coinalyze/blob/main/src/coinalyze/client.py"
    click CONST "https://github.com/ivarurdalen/coinalyze/blob/main/src/coinalyze/constants.py"
    click ENUM "https://github.com/ivarurdalen/coinalyze/blob/main/src/coinalyze/enums.py"
    click TYPES "https://github.com/ivarurdalen/coinalyze/blob/main/src/coinalyze/types.py"
    click BASE "https://github.com/ivarurdalen/coinalyze/blob/main/src/coinalyze/util/base.py"
    click PANDAS "https://github.com/ivarurdalen/coinalyze/blob/main/src/coinalyze/util/pandas.py"
    click INIT "https://github.com/ivarurdalen/coinalyze/blob/main/src/coinalyze/__init__.py"
    click VER "https://github.com/ivarurdalen/coinalyze/blob/main/src/coinalyze/__version__.py"
    click CLI "https://github.com/ivarurdalen/coinalyze/blob/main/examples/cli.py"
    click NB "https://github.com/ivarurdalen/coinalyze/blob/main/examples/coinalyze_client.ipynb"
    click ENV "https://github.com/ivarurdalen/coinalyze/blob/main/.env.template"
    click TC "https://github.com/ivarurdalen/coinalyze/blob/main/tests/test_client.py"
    click TU "https://github.com/ivarurdalen/coinalyze/blob/main/tests/test_util.py"
    click CF "https://github.com/ivarurdalen/coinalyze/blob/main/tests/conftest.py"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef library fill:#E6FFED,stroke:#28A745,color:#28A745;
    classDef external fill:#FFF5E6,stroke:#E36209,color:#E36209;
    classDef examples fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
    classDef tests fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
    classDef config fill:#F5E6FF,stroke:#6F42C1,color:#6F42C1;
```
