# javidjms/influxable architecture

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

- Interactive diagram: https://gitdiagram.com/javidjms/influxable
- Repository: https://github.com/javidjms/influxable

## Overview

##### Project type and purpose
- This is an open-source Python library (ORM/ODM/client) for interacting with InfluxDB.
- It provides a DSL for building InfluxQL queries, a Measurement class to model time-series points, serializers for formatting results, and CLI commands for code generation and data population.

##### File-structure analysis
- Top-level modules:
- influxable/app.py – main singleton entrypoint (Influxable)
- influxable/api.py – thin wrapper for HTTP calls (InfluxDBApi)
- influxable/connection.py – builds Connection objects
- influxable/db – Query, admin functionality, function sub-packages (aggregations, selectors, transformations)
- influxable/measurement.py – Measurement and SimpleMeasurement base classes
- influxable/attributes.py – FieldAttribute types (Generic, Integer, Float, Tag, Timestamp, DateTime)
- influxable/serializers.py – various output formats
- influxable/command_line.py & influxable/commands – CLI entrypoint and commands (autogenerate, populate)
- influxable/request.py & influxable/response.py – HTTP request construction and response handling
- influxable/helpers – utility decorators and helpers
- Config and deployment:
- Dockerfile & docker-compose.yml for containerized testing
- .env files for environment variables

##### Key insights from README
- Defines core classes and methods: Influxable, InfluxDBApi, Connection, Measurement, Query, InfluxDBAdmin.
- Describes features: auto-generation of measurement classes, query builder DSL, serializers, admin operations.

##### Main components
A. Client layer
- User code or CLI (influxable CLI commands)
- Application imports (from influxable import Influxable, Measurement, Query)
B. Library core
1. Influxable (singleton)
- Manages configuration, environment variables, holds a Connection instance.
2. Connection
- Encapsulates HTTP client settings (base_url, auth)
- Delegates to InfluxDBApi
3. InfluxDBApi
- Builds HTTP requests (influxable/request.py)
- Sends requests, receives JSON
4. Request/Response
- Request: constructs URL, headers, query parameters
- Response: wraps raw JSON and provides accessors
5. Query Builder (influxable/db/query.py)
- Fluent DSL for SELECT, WHERE, GROUP BY, etc.
- Uses function modules (aggregations, selectors, transformations)
6. Measurement Model
- Subclasses of Measurement define attributes (fields)
- Bulk save → write_points → line protocol → HTTP
7. Serializers
- Convert raw JSON or Query result to Python objects, pandas DataFrame, plain JSON, etc.
8. CLI Commands
- autogenerate: uses jinja2 templates (influxable/templates) to output Measurement class files
- populate: generates random points and bulk-saves them
C. External systems
- InfluxDB server (1.x or OSS 2.0)
- Environment variables or config file for credentials
- Optional user’s Python application embedding this library

##### Component interactions and data flows
1. Client code or CLI → calls Influxable.get_instance() or CLI entry
2. Influxable → creates/uses Connection
3. Connection → uses InfluxDBApi to construct HTTP requests
4. Query or Measurement.bulk_save → triggers InfluxDBApi.execute_query() or write_points()
5. HTTP request → InfluxDB server → HTTP response JSON
6. Response → wrapped by InfluxDBResponse → passed to serializer → returned to client
7. CLI autogenerate → reads existing schema from InfluxDB or template → writes Python measurement file

##### Architectural patterns and principles
- Singleton (Influxable)
- Factory method (Connection.create())
- Fluent interface / DSL (Query)
- Template Method (serializers share interface)
- Strategy (pluggable serializers, field attribute classes)
- Separation of concerns:
- HTTP layer vs. domain vs. CLI vs. templating

##### Technologies, frameworks, libraries
- Python 3.7+
- requests (HTTP client, via InfluxDBApi)
- jinja2 (templating for autogenerate)
- pytest (testing)
- Docker for containerized testing
- InfluxDB (v1.x and OSS 2.0)

##### Essential elements to capture
- Influxable singleton → Connection → InfluxDBApi
- Query builder and Measurement flow separately
- Serializers branching out of Response
- CLI commands reading from templates or generating data
- The external InfluxDB service as the persistence layer
- Extension packages (/attributes, /serializers, /db/function)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        ClientApp["User Application"]:::external
        CLIEntry["CLI Entrypoint"]:::cli
    end

    %% Core Library
    subgraph "Core Library"
        Influxable["Influxable"]:::core
        Connection["Connection"]:::core
        InfluxDBApi["InfluxDBApi"]:::core
        Request["Request"]:::util
        Response["Response"]:::util
        Query["Query Builder DSL"]:::core
        Admin["Admin Functionality"]:::core
        Criteria["Query Criteria Utilities"]:::core
        Aggregations["Aggregation Functions"]:::functions
        Selectors["Selector Functions"]:::functions
        Transformations["Transformation Functions"]:::functions
        Measurement["Measurement Base Classes"]:::core
        Attributes["FieldAttribute Types"]:::core
        Serializers["Serializers"]:::core
        Settings["Configuration Loader"]:::util
    end

    %% CLI Commands
    subgraph "CLI Subsystem"
        AutoGen["autogenerate Command"]:::cli
        Populate["populate Command"]:::cli
        Templates["Jinja2 Templates"]:::util
    end

    %% External Systems
    subgraph "External Systems"
        InfluxDB["InfluxDB Server"]:::external
        EnvConfig["Environment Variables"]:::util
    end

    %% Data Flows and Relationships
    ClientApp -->|"imports"| Influxable
    CLIEntry -->|"invokes"| Influxable
    Influxable -->|"uses create()"| Connection
    Connection -->|"delegates to"| InfluxDBApi
    Connection -->|"loads settings"| Settings
    InfluxDBApi -->|"builds requests"| Request
    InfluxDBApi -->|"sends HTTP"| InfluxDB
    InfluxDBApi -->|"receives JSON"| Response
    Response -->|"passes data to"| Serializers
    Query -->|"uses criteria"| Criteria
    Query -->|"uses functions"| Aggregations
    Query -->|"uses functions"| Selectors
    Query -->|"uses functions"| Transformations
    Query -->|"executes via"| InfluxDBApi
    Measurement -->|"bulk_save → line protocol"| InfluxDBApi
    Measurement -->|"defines fields with"| Attributes
    Admin -->|"admin ops via"| InfluxDBApi
    AutoGen -->|"reads schema/templates"| Templates
    AutoGen -->|"writes classes"| Measurement
    Populate -->|"generates data"| Measurement
    Populate -->|"bulk_save"| Measurement
    EnvConfig -.->|"injected into"| Connection

    %% Click Events
    click Influxable "https://github.com/javidjms/influxable/blob/develop/influxable/app.py"
    click InfluxDBApi "https://github.com/javidjms/influxable/blob/develop/influxable/api.py"
    click Connection "https://github.com/javidjms/influxable/blob/develop/influxable/connection.py"
    click Request "https://github.com/javidjms/influxable/blob/develop/influxable/request.py"
    click Response "https://github.com/javidjms/influxable/blob/develop/influxable/response.py"
    click Query "https://github.com/javidjms/influxable/blob/develop/influxable/db/query.py"
    click Admin "https://github.com/javidjms/influxable/blob/develop/influxable/db/admin.py"
    click Criteria "https://github.com/javidjms/influxable/blob/develop/influxable/db/criteria.py"
    click Aggregations "https://github.com/javidjms/influxable/blob/develop/influxable/db/function/aggregations.py"
    click Selectors "https://github.com/javidjms/influxable/blob/develop/influxable/db/function/selectors.py"
    click Transformations "https://github.com/javidjms/influxable/blob/develop/influxable/db/function/transformations.py"
    click Measurement "https://github.com/javidjms/influxable/blob/develop/influxable/measurement.py"
    click Attributes "https://github.com/javidjms/influxable/blob/develop/influxable/attributes.py"
    click Serializers "https://github.com/javidjms/influxable/blob/develop/influxable/serializers.py"
    click CLIEntry "https://github.com/javidjms/influxable/blob/develop/influxable/command_line.py"
    click AutoGen "https://github.com/javidjms/influxable/blob/develop/influxable/commands/auto_generate.py"
    click Populate "https://github.com/javidjms/influxable/blob/develop/influxable/commands/populate.py"
    click Templates "https://github.com/javidjms/influxable/blob/develop/influxable/templates/auto_generated_measurement.py.jinja"
    click Templates "https://github.com/javidjms/influxable/blob/develop/influxable/templates/simple_measurement.py.jinja"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#1E70BF,color:#000;
    classDef cli fill:#E6FFDB,stroke:#3A7F00,color:#000;
    classDef external fill:#FFE0B2,stroke:#BF5700,color:#000;
    classDef util fill:#F0F0F0,stroke:#888888,color:#000;
    classDef functions fill:#FDE2FF,stroke:#BF00A5,color:#000;
```
