# yudiell/energy-apis architecture

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

- Interactive diagram: https://gitdiagram.com/yudiell/energy-apis
- Repository: https://github.com/yudiell/energy-apis

## Overview

##### Project Type and Purpose
- This is a small Python‐based CLI tool (“eia-api”) that wraps the U.S. Energy Information Administration (EIA) REST API v2.
- Its purpose is to fetch specific data endpoints (e.g. crude-oil-imports, electric-power-operational-data), apply any default parameters, and present results to the user.

##### File‐Structure Analysis
- Top level:
- pyproject.toml – Poetry configuration, dependencies, and defines the CLI entrypoint.
- energy_apis/ – root Python package.
- tests/ – unit or integration tests.
- postman/ – Postman collection for API calls (external testing/integration).
- energy_apis/eia/api/v2/
- __main__.py – CLI engine; entrypoint for `poetry run eia-api`.
- flow.py – orchestrates calls to the HTTP client and handles request parameters.
- No database or frontend. All I/O is HTTP to remote EIA API and console output.

##### Key Components
a. CLI Layer
- Component: “eia-api CLI”
- Technology: Python entrypoint (`__main__.py`), invoked via Poetry.
- Responsibility: Parse `--environment` and `--request` flags; kick off the flow.
b. Core Library Layer
- Component: energy_apis.eia.api.v2.flow
- Responsibility: Build the HTTP request with default parameters (API key, endpoint name), invoke the HTTP Client.
c. HTTP Client / Adapter
- Component: (e.g.) Requests library or built-in HTTP client
- Responsibility: GET/POST to https://api.eia.gov/v2/{endpoint}
d. External Service
- Component: EIA API v2 (REST endpoint)
- External dependency; returns JSON data.
- Component: postman/collections/EIA APIv2.postman_collection.json
- Responsibility: Manual or automated testing of endpoints outside of the CLI.
f. Tests
- Component: tests/*.py
- Responsibility: Unit tests for flow logic and CLI parsing.

##### Relationships and Data Flows
- CLI → Flow module: passes parsed flags →
- Flow module → HTTP Client: issues REST call →
- HTTP Client → External EIA API: fetches JSON →
- External API → HTTP Client → Flow module: returns data →
- Flow module → CLI: prints or stores results → end user
- Tests exercise Flow module and CLI in isolation (mocking HTTP client).
- Postman connects to External API directly for exploratory testing.

##### Architectural Patterns & Design Principles
- Layered Architecture:
- Presentation (CLI)
- Business Logic (flow.py)
- Infrastructure (HTTP client)
- Single Responsibility per module.
- Dependency Injection (injecting environment and request parameters).
- Externalize configuration via Poetry and environment flags.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors and Components
    U["User"]:::externalActor
    Poetry["Poetry\n(pyproject.toml)"]:::tooling
    CLI["eia-api CLI\n(__main__.py)"]:::process
    Flow["Core Library\n(flow.py)"]:::process
    HTTP["HTTP Client/Adapter"]:::process
    EIAAPI["EIA API v2\n(REST Endpoint)"]:::externalService
    Postman["Postman Collection"]:::tooling

    subgraph "Tests"
      direction TB
      Tests["tests/"]:::tests
    end

    %% Data Flows
    U -->|"CLI args"| CLI
    Poetry -->|"entrypoint config"| CLI
    CLI -->|"parsed flags"| Flow
    Flow -->|"builds request & invokes"| HTTP
    HTTP -->|"HTTP GET /v2/{endpoint}"| EIAAPI
    EIAAPI -->|"JSON Response"| HTTP
    HTTP -->|"returns data"| Flow
    Flow -->|"prints results"| CLI
    Tests -.->|"unit tests/mock HTTP client"| Flow
    Postman -->|"manual/automated tests"| EIAAPI

    %% Click Events
    click CLI "https://github.com/yudiell/energy-apis/blob/main/energy_apis/eia/api/v2/__main__.py"
    click Flow "https://github.com/yudiell/energy-apis/blob/main/energy_apis/eia/api/v2/flow.py"
    click HTTP "https://github.com/yudiell/energy-apis/blob/main/energy_apis/eia/api/v2/flow.py"
    click Postman "https://github.com/yudiell/energy-apis/blob/main/postman/collections/EIA APIv2.postman_collection.json"
    click Tests "https://github.com/yudiell/energy-apis/tree/main/tests/"

    %% Styles
    classDef process fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef externalService fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20
    classDef tooling fill:#ECEFF1,stroke:#455A64,color:#455A64
    classDef tests fill:#FFFFFF,stroke:#000000,stroke-dasharray:5 5,color:#000000
    classDef externalActor fill:#FFF9C4,stroke:#F9A825,color:#F9A825
```
