# fboerman/jao-py architecture

> Architecture diagram of the GitHub repository fboerman/jao-py, 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/fboerman/jao-py
- Repository: https://github.com/fboerman/jao-py

## Overview

##### Project type and purpose
- This is an open-source Python client library (“jao-py”) for consuming various endpoints offered by JAO (Joint Allocation Office). It provides pandas-based wrappers around REST and SOAP APIs, plus CSV/XML download utilities, all packaged for easy pip installation.

##### File structure
- Top-level:
- .github/workflows: CI pipelines for tests and publishing to Test PyPI
- setup.py, setup.cfg, requirements.txt, manifest.in: packaging and distribution
- test_core_flowbased.py: a smoke/integration test for one of the legacy clients
- Main code under the `jao/` package:
- jao/jao.py, jao/webservice.py: core HTTP client and request orchestration
- jao/parsers.py, jao/util.py, jao/exceptions.py: shared parsing, utilities, and error types
- jao/jao_intraday.py, jao/jao_nordic.py, jao/jao_parrun.py: “PublicationTool” clients for different JAO tools
- Subpackage `jao/CWE/` (deprecated legacy clients):
- ASMX SOAP client, CSV downloader, XML downloader + their parsers and exception types

##### README for additional insights
- Four main modern clients:
a) JaoAPIClient (REST webservice)
b) JaoPublicationToolClient (core day-ahead)
c) JaoPublicationToolPandasIntraDay (intraday versions a/b/c)
d) JaoPublicationToolPandasNordics (nordic day-ahead)
- One “ParRun” client wrapping intraday for parallel run
- Deprecated “CWE” clients using suds-community and lxml/pillow for SOAP and file parsing

##### Detail without over-splitting
- Logical module but group closely related files
- Do not show every single source file; focus on package/subpackage level and key classes

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    subgraph "External Systems"
        direction TB
        REST_API["JAO REST API"]:::external
        PUB_TOOL["JAO Publication Tool Web Interfaces"]:::external
        CWE_ENDPOINTS["Deprecated CWE SOAP & CSV/XML Endpoints"]:::external
    end

    %% Library Modules
    subgraph "jao-py Library"
        direction TB

        subgraph "API Client Layer"
            direction TB
            WebService["JaoAPIClient\n(jao/webservice.py)"]:::client
            CoreHTTP["Core HTTP Client\n(jao/jao.py)"]:::client
        end

        subgraph "PublicationTool Clients"
            direction TB
            DayAhead["Day-Ahead Client\n(jao/jao.py)"]:::client
            Intraday["Intraday Clients\n(jao/jao_intraday.py)"]:::client
            Nordic["Nordic Client\n(jao/jao_nordic.py)"]:::client
            ParRun["Parallel-Run Intraday\n(jao/jao_parrun.py)"]:::client
        end

        subgraph "Parsers & Data Models"
            direction TB
            ModernParsers["Modern Parsers\n(jao/parsers.py)"]:::parser
        end

        subgraph "Utilities & Common"
            direction TB
            Utils["Utilities\n(jao/util.py)"]:::util
            Exceptions["Exceptions\n(jao/exceptions.py)"]:::util
        end

        subgraph "Deprecated CWE Subpackage" 
            direction TB
            CWE_Pkg["jao/CWE/"]:::deprecated
            CWE_Def["CWE Definitions\n(jao/CWE/definitions.py)"]:::deprecated
            CWE_Exc["CWE Exceptions\n(jao/CWE/exceptions.py)"]:::deprecated
            CWE_Core["CWE Core Client\n(jao/CWE/jao.py)"]:::deprecated
            CWE_Parsers["CWE Parsers\n(jao/CWE/parsers.py)"]:::deprecated
        end
    end

    %% Packaging & CI
    subgraph "Packaging & CI"
        direction TB
        Package["setup.py / setup.cfg / manifest.in"]:::packaging
        CI["CI Workflows\n(.github/workflows)"]:::packaging
    end

    %% Tests
    Test["Integration Smoke Test\n(test_core_flowbased.py)"]:::test

    %% Data Flow & Relationships
    REST_API -->|HTTP JSON/XML| WebService
    PUB_TOOL -->|HTTP Endpoints| CoreHTTP
    CWE_ENDPOINTS -->|SOAP/CSV/XML| CWE_Core

    WebService -->|orchestrates| CoreHTTP
    CoreHTTP -->|raw response| ModernParsers
    CWE_Core -->|raw response| CWE_Parsers

    ModernParsers -->|DataFrame| User["Library User"]:::external
    CWE_Parsers -->|DataFrame| User

    WebService -->|raises| Exceptions
    CoreHTTP -->|uses| Utils

    DayAhead -->|uses| CoreHTTP
    Intraday -->|uses| CoreHTTP
    Nordic -->|uses| CoreHTTP
    ParRun -->|wraps Intraday| Intraday

    DayAhead -->|parses| ModernParsers
    Intraday -->|parses| ModernParsers
    Nordic -->|parses| ModernParsers
    ParRun -->|parses| ModernParsers

    Package -->|publishes| User
    CI -->|tests & publishes| Package

    User -->|runs| Test
    Test -->|imports| DayAhead
    Test -->|imports| Intraday

    %% Click events
    click WebService "https://github.com/fboerman/jao-py/blob/master/jao/webservice.py"
    click CoreHTTP "https://github.com/fboerman/jao-py/blob/master/jao/jao.py"
    click DayAhead "https://github.com/fboerman/jao-py/blob/master/jao/jao.py"
    click Intraday "https://github.com/fboerman/jao-py/blob/master/jao/jao_intraday.py"
    click Nordic "https://github.com/fboerman/jao-py/blob/master/jao/jao_nordic.py"
    click ParRun "https://github.com/fboerman/jao-py/blob/master/jao/jao_parrun.py"
    click ModernParsers "https://github.com/fboerman/jao-py/blob/master/jao/parsers.py"
    click Utils "https://github.com/fboerman/jao-py/blob/master/jao/util.py"
    click Exceptions "https://github.com/fboerman/jao-py/blob/master/jao/exceptions.py"
    click CWE_Pkg "https://github.com/fboerman/jao-py/tree/master/jao/CWE/"
    click CWE_Def "https://github.com/fboerman/jao-py/blob/master/jao/CWE/definitions.py"
    click CWE_Exc "https://github.com/fboerman/jao-py/blob/master/jao/CWE/exceptions.py"
    click CWE_Core "https://github.com/fboerman/jao-py/blob/master/jao/CWE/jao.py"
    click CWE_Parsers "https://github.com/fboerman/jao-py/blob/master/jao/CWE/parsers.py"

    click Package "https://github.com/fboerman/jao-py/blob/master/setup.py"
    click CI "https://github.com/fboerman/jao-py/blob/master/.github/workflows/run-tests.yml"
    click CI "https://github.com/fboerman/jao-py/blob/master/.github/workflows/publish-to-test-pypi.yml"
    click Test "https://github.com/fboerman/jao-py/blob/master/test_core_flowbased.py"

    %% Styles
    classDef external fill:#dff0d8,stroke:#3c763d,color:#3c763d
    classDef client fill:#d9edf7,stroke:#31708f,color:#31708f
    classDef parser fill:#fcf8e3,stroke:#8a6d3b,color:#8a6d3b
    classDef util fill:#f5e6fa,stroke:#513375,color:#513375
    classDef deprecated fill:#eeeeee,stroke:#999999,color:#777777,stroke-dasharray: 5 5
    classDef packaging fill:#fff2cc,stroke:#8a6d3b,color:#8a6d3b
    classDef test fill:#f2dede,stroke:#a94442,color:#a94442
```
