# corsosource/birdsong architecture

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

- Interactive diagram: https://gitdiagram.com/corsosource/birdsong
- Repository: https://github.com/corsosource/birdsong

## Overview

##### Project type and purpose
- Birdsong is an open-source Python client library that wraps the Canary Labs Historian REST API, making it easy to send and receive time-series (“tag”) data.
- It is _not_ a front-end or standalone service; it’s a helper library for other Python code (or Ignition scripts) to interact with the Canary historian.

##### File structure
- Top-level:
- setup.py (packaging script)
- README.md (usage and architecture narrative)
- birdsong/ (the Python package containing all logic)
- test/ (a Jupyter notebook for manual/integration tests)
- birdsong/ modules:
- rest.py – low-level HTTP wrapper (handles GET/POST, SSL options)
- tokens.py – obtains and refreshes Canary session/user tokens
- sender.py – high-level “CanarySender” class for writing data (createNewFile, storeData, fileRollover)
- view.py – high-level “CanaryView” class for querying data (browseNodes, getTagData, getLiveData, etc.)
- values.py – helper data structures (Tvq, Property, Annotation) and their serialization/validation
- __init__.py – public API exports

##### Extract architectural hints from the README
- Uses Python context-managers to open/close tokenized HTTP sessions.
- Follows a layered approach:
a. values.py defines data models
b. rest.py/tokens.py implement communication primitives
c. sender.py/view.py orchestrate domain operations

1) Client Application (could be any Python script, Ignition module, or notebook that does `import birdsong`)
2) birdsong Library
– Values Module (Tvq, Annotation, Property structures)
– REST Module (HTTP calls, SSL handling)
– Token Manager (login, refresh flow)
– Sender (storeData, createNewFile, fileRollover)
– View   (browseNodes/Tags/Status, getTagData, getLiveData, getQualities/Aggregates/Properties)
3) External Canary API (REST endpoints for view & sender services)
4) Canary Historian Server (backend that persists data to its database)
6) Tests (Jupyter notebook referencing birdsong)

- Client App → birdsong API (entry points in __init__.py)
- Sender/View → Token Manager to acquire JWT/session tokens
- Sender/View → REST Module to issue HTTP calls (attach tokens)
- REST Module → Canary API endpoints over HTTPS (POST/GET)
- Canary API → Historian backend → responds with JSON
- REST Module → passes JSON up → Sender/View parse into Python objects (using values.py)
- Tests → Client App / birdsong

c. Architectural patterns & design principles:
- Layered architecture (data models → transport → domain operations)
- Context-manager pattern for automatic resource cleanup
- Generator pattern in view.py for streaming large datasets
- Single Responsibility principle: each module has a focused purpose
- Retry & token-refresh logic encapsulated in tokens.py

d. Key technologies & frameworks:
- Python 3.x
- requests (HTTP client)
- Canary REST API (external service)
- Jupyter (for integration tests in test/)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client and Tests
    ClientApp["Client Application\n(import birdsong)"]:::external
    Tests["Integration Tests\n(Jupyter Notebook)"]:::external

    %% Birdsongs Package
    subgraph "Birdsong Library" 
        direction TB
        PublicAPI["__init__.py\n(Public API)"]:::internal
        Values["values.py\n(Data Models)"]:::internal
        REST["rest.py\n(HTTP Wrapper)"]:::internal
        Tokens["tokens.py\n(Token Manager)"]:::internal
        Sender["sender.py\n(CanarySender)"]:::internal
        View["view.py\n(CanaryView)"]:::internal
    end

    %% Third-party Libraries
    subgraph "Third-Party Dependencies"
        direction TB
        Requests["requests"]:::thirdparty
        Arrow["arrow"]:::thirdparty
        Ciso8601["ciso8601"]:::thirdparty
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        CanaryAPI["Canary REST API"]:::external
        Historian["Canary Historian Server"]:::external
    end

    %% Documentation & Packaging
    subgraph "Project Docs & Setup"
        direction TB
        Setup["setup.py"]:::docs
        Readme["README.md"]:::docs
        License["LICENSE"]:::docs
    end

    %% Relationships
    ClientApp -->|"import birdsong"| PublicAPI
    Tests -->|uses| ClientApp

    PublicAPI -->|exports classes| Sender
    PublicAPI -->|exports classes| View

    Sender -->|uses| Tokens
    View -->|uses| Tokens

    Sender -->|calls| REST
    View -->|calls| REST

    Tokens -->|uses| REST

    REST -->|over HTTPS| CanaryAPI
    CanaryAPI -->|persists data| Historian
    CanaryAPI -->|returns JSON| REST

    REST -->|parses JSON| Values
    Sender -->|serializes Tvq| Values
    View -->|builds objects| Values

    REST -->|import| Requests
    Values -->|import| Arrow
    Values -->|import| Ciso8601

    %% Docs links
    Setup --- Readme
    Readme --- License

    %% Click Events
    click ClientApp "https://github.com/corsosource/birdsong/blob/master/test/Testing birdsong - Python3.ipynb"
    click PublicAPI "https://github.com/corsosource/birdsong/blob/master/birdsong/__init__.py"
    click Values "https://github.com/corsosource/birdsong/blob/master/birdsong/values.py"
    click REST "https://github.com/corsosource/birdsong/blob/master/birdsong/rest.py"
    click Tokens "https://github.com/corsosource/birdsong/blob/master/birdsong/tokens.py"
    click Sender "https://github.com/corsosource/birdsong/blob/master/birdsong/sender.py"
    click View "https://github.com/corsosource/birdsong/blob/master/birdsong/view.py"
    click Setup "https://github.com/corsosource/birdsong/blob/master/setup.py"
    click Readme "https://github.com/corsosource/birdsong/blob/master/README.md"
    click License "https://github.com/corsosource/birdsong/tree/master/LICENSE"

    %% Styles
    classDef internal fill:#E8F1F2,stroke:#2B7A78,stroke-width:2px;
    classDef external fill:#FDEDEC,stroke:#C0392B,stroke-width:2px;
    classDef thirdparty fill:#FEF5E7,stroke:#D4AC0D,stroke-width:2px;
    classDef docs fill:#EBF5FB,stroke:#2874A6,stroke-width:2px;
```
