# pantherale0/pyanglianwater architecture

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

- Interactive diagram: https://gitdiagram.com/pantherale0/pyanglianwater
- Repository: https://github.com/pantherale0/pyanglianwater

## Overview

##### Project Type and Purpose
- This is an open-source Python library (package) named `pyanglianwater` designed to interact with Anglian Water’s public APIs and retrieve smart-meter usage data. There is no UI or database of its own—its sole purpose is to encapsulate authentication, request/response logic, and data-model handling for third-party callers.

##### File-Structure Analysis
- Top‐level package folder `pyanglianwater/` contains all core modules:
- auth.py – handles login/authentication flows (e.g. obtaining tokens, managing sessions)
- api.py – defines HTTP client wrappers for each endpoint (readings, dashboard, bills/payments)
- meter.py – data-models and higher-level helpers to fetch and parse meter usage
- const.py, enum.py – constant values and enumerations for API parameters and response codes
- exceptions.py – custom exception classes used throughout the library
- utils.py – shared helper functions (e.g. HTTP helpers, date parsing)
- Configuration, packaging, and dev tools:
- setup.py & pyproject.toml – packaging metadata
- requirements*.txt – dependencies for runtime and documentation
- mkdocs.yml & docs/ – documentation site source
- .github/workflows/ – CI/CD pipelines (build, test, docs, release)
- Tests under `tests/` use static JSON fixtures to verify modules.

##### Key README Insights
- Library is installed via pip
- “Usage” marked TODO—implies consumers call library functions directly in their own code or scripts
- Development driven by `justfile` tasks and GitHub Actions for build/test/docs

## Diagram (Mermaid)

```mermaid
flowchart TB
    ClientApp["Client Application\n(import pyanglianwater)"]:::external

    subgraph "pyanglianwater Package"
        direction TB
        Init["__init__.py"] 
        Version["_version.py"]
        Typed["py.typed"]
        Auth["Auth Manager\n(auth.py)"]
        API["API Client\n(api.py)"]
        Meter["Data Models & Helpers\n(meter.py)"]
        Const["Constants\n(const.py)"]
        Enum["Enumerations\n(enum.py)"]
        Exc["Custom Exceptions\n(exceptions.py)"]
        Utils["Utility Functions\n(utils.py)"]
    end

    subgraph "External Anglian Water APIs"
        direction TB
        ExtAuth["Auth Endpoint"]:::external
        ExtRead["Meter Readings Endpoint"]:::external
        ExtBill["Billing Endpoint"]:::external
    end

    subgraph "CI/CD Pipeline"
        direction TB
        GH["GitHub Actions\n(.github/workflows/)"]
        Just["Task Runner\n(justfile)"]
    end

    subgraph "Documentation"
        direction TB
        MkMd["MkDocs Config\n(mkdocs.yml)"]
        DocsSrc["Docs Source\n(docs/)"]
    end

    subgraph "Testing"
        direction TB
        Tests["Test Suite\n(tests/)"]
        Fixtures["JSON Fixtures\n(tests/*.json)"]
        Example["Example Script\n(test.py)"]
    end

    subgraph "Packaging"
        direction TB
        SetupPy["setup.py"]
        PyProj["pyproject.toml"]
        Req["requirements.txt"]
        ReqDocs["requirements.docs.txt"]
    end

    %% Main flows
    ClientApp --> Auth
    Auth -->|"HTTP POST /login"| ExtAuth
    ExtAuth -->|"token"| Auth
    ClientApp --> API
    API -->|"HTTP GET /readings"| ExtRead
    ExtRead -->|"data"| API
    API -->|"HTTP GET /billing"| ExtBill
    ExtBill -->|"data"| API

    %% Internal module dependencies
    API --> Meter
    API --> Exc
    API --> Const
    API --> Enum
    API --> Utils
    Auth --> Utils
    Auth --> Const
    Auth --> Enum
    Meter --> Const
    Meter --> Enum
    Meter --> Exc
    Meter --> Utils

    %% Dev workflows
    GH --> Tests
    GH --> Docs
    GH --> Packaging
    GH --> Just
    Tests --> Auth
    Tests --> API
    Tests --> Meter
    Tests --> Utils

    %% Click Events
    click Auth "https://github.com/pantherale0/pyanglianwater/blob/main/pyanglianwater/auth.py"
    click API "https://github.com/pantherale0/pyanglianwater/blob/main/pyanglianwater/api.py"
    click Meter "https://github.com/pantherale0/pyanglianwater/blob/main/pyanglianwater/meter.py"
    click Const "https://github.com/pantherale0/pyanglianwater/blob/main/pyanglianwater/const.py"
    click Enum "https://github.com/pantherale0/pyanglianwater/blob/main/pyanglianwater/enum.py"
    click Exc "https://github.com/pantherale0/pyanglianwater/blob/main/pyanglianwater/exceptions.py"
    click Utils "https://github.com/pantherale0/pyanglianwater/blob/main/pyanglianwater/utils.py"
    click Version "https://github.com/pantherale0/pyanglianwater/blob/main/pyanglianwater/_version.py"
    click Typed "https://github.com/pantherale0/pyanglianwater/blob/main/pyanglianwater/py.typed"
    click Init "https://github.com/pantherale0/pyanglianwater/blob/main/pyanglianwater/__init__.py"
    click SetupPy "https://github.com/pantherale0/pyanglianwater/blob/main/setup.py"
    click PyProj "https://github.com/pantherale0/pyanglianwater/blob/main/pyproject.toml"
    click Req "https://github.com/pantherale0/pyanglianwater/blob/main/requirements.txt"
    click ReqDocs "https://github.com/pantherale0/pyanglianwater/blob/main/requirements.docs.txt"
    click MkMd "https://github.com/pantherale0/pyanglianwater/blob/main/mkdocs.yml"
    click DocsSrc "https://github.com/pantherale0/pyanglianwater/tree/main/docs/"
    click GH "https://github.com/pantherale0/pyanglianwater/tree/main/.github/workflows/"
    click Just "https://github.com/pantherale0/pyanglianwater/tree/main/justfile"
    click Tests "https://github.com/pantherale0/pyanglianwater/tree/main/tests/"
    click Fixtures "https://github.com/pantherale0/pyanglianwater/blob/main/tests/*.json"
    click Example "https://github.com/pantherale0/pyanglianwater/blob/main/test.py"

    %% Styles
    classDef internal fill:#D6EFFF,stroke:#0366d6,color:#0366d6;
    classDef external fill:#CFFFD6,stroke:#28a745,color:#28a745;
    classDef dev fill:#FFEEDD,stroke:#d73a49,color:#d73a49;

    class Auth,API,Meter,Const,Enum,Exc,Utils,Init,Version,Typed internal;
    class ClientApp,ExtAuth,ExtRead,ExtBill external;
    class GH,Just,MkMd,DocsSrc,Tests,Fixtures,Example,SetupPy,PyProj,Req,ReqDocs dev
```
