# noviscient/formidium-api-python architecture

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

- Interactive diagram: https://gitdiagram.com/noviscient/formidium-api-python
- Repository: https://github.com/noviscient/formidium-api-python

## Overview

##### Project type and purpose
- This is a *client-library* (SDK) that wraps HTTP calls to the Formidium REST API.
- Its purpose is to expose a clean Python interface (`API` class in `formidium.py`) so downstream code can invoke methods like `trades()` and `positions()` without dealing with raw HTTP logic.

##### File structure
- Top-level files:
- `formidium.py` — core Python module implementing the API wrapper
- `tests.py` — end-to-end tests for the wrapper methods
- `.env.example` & README — configuration guidance
- `pyproject.toml` & `requirements.txt` — dependency management
- UV lock files & instructions for environment management (`uv.lock`)
- No “frontend” or “backend” per se—this is purely a library + test harness.

##### Extract key details from the README
- Uses UV (Astral’s environment manager) to install dependencies into a `.venv`.
- Expects a `.env` file with credentials to drive the HTTP calls.
- Tests are run via pytest against a live or mocked API endpoint.

##### Main components and relationships
a. Components:
- Developer / Consumer Code — your own application or scripts that `import formidium.API`.
- The `formidium` module — contains the `API` class, credential loader, HTTP client logic (e.g., `requests`).
- Environment Manager (UV + virtualenv) — ensures reproducible Python environment and installed deps.
- Configuration Layer — `.env` file → loaded at runtime, populating API credentials.
- External Service — the Formidium REST API endpoints on the Internet.
- Test Harness — `pytest`, using `tests.py` to validate wrapper behavior.

b. Interactions:
1. Developer writes code → instantiates `API(base_url, api_key, passphrase, api_secret)`.
2. `API` module loads credentials from `.env` if not passed explicitly.
3. `API` methods construct HTTP requests → sent over the network to Formidium’s endpoints.
4. Formidium responds with JSON → `API` parses response and returns Python objects.
5. Tests invoke `API` methods in a controlled environment to assert correctness.
6. UV manages the Python runtime and dependencies so that `formidium.py` and `tests.py` run in a consistent environment.

c. Architectural patterns & design principles
- Single Responsibility — `API` class only handles request construction/response parsing.
- Dependency Injection — credentials and base URL can be passed in or loaded from `.env`.
- Environment Isolation — UV + virtualenv ensure “it works on my machine” consistency.
- Test-Driven Approach — `tests.py` as the integration test suite against live or stubbed endpoints.

d. Technologies & frameworks to annotate
- Python 3.x runtime
- UV (Astral) for env management
- virtualenv (the `.venv` folder)
- `requests` (or similar HTTP client) as a library inside `formidium.py`
- `pytest` for testing
- `.env` for runtime configuration

##### Detail
- Break `formidium.py` into sub-components if desired: Authentication, Request Builder, Response Parser.
- `.env` loader as a distinct step in the flow.

1. Environment Layer (UV → `.venv` → Python interpreter)
2. Library Layer (formidium module broken into config loader, HTTP client, business methods)
3. External Layer (Formidium REST API)
4. Consumer Layer (Developer application code + pytest tests)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Environment Layer
    subgraph "Environment Layer"
        direction TB
        UV["UV (Astral Env Manager)"]:::env
        VENV[".venv (virtualenv)"]:::env
        Python["Python 3.x Interpreter"]:::env
    end

    %% Library Layer
    subgraph "Library Layer"
        direction TB
        EnvLoader["Config Loader (.env)"]:::lib
        subgraph "Core Module: formidium.py"
            direction TB
            AuthComp["Authentication Component"]:::lib
            ReqBuilder["Request Builder (requests)"]:::lib
            RespParser["Response Parser"]:::lib
            APIMethods["API Business Methods"]:::lib
        end
    end

    %% External Layer
    subgraph "External Layer"
        direction TB
        FormAPI["Formidium REST API"]:::ext
    end

    %% Consumer Layer
    subgraph "Consumer Layer"
        direction TB
        DevCode["Developer Application Code"]:::lib
        Tests["pytest Test Suite"]:::test
    end

    %% Documentation & Config Files
    subgraph "Project Files"
        direction TB
        EnvExample[".env.example"]:::doc
        PyProj["pyproject.toml"]:::doc
        ReqTxt["requirements.txt"]:::doc
        UVLock["uv.lock"]:::doc
        Readme["README.md"]:::doc
        GitIgnore[".gitignore"]:::doc
    end

    %% Connections within Environment
    UV --> VENV --> Python

    %% Config flow
    EnvExample --> EnvLoader
    EnvLoader --> AuthComp

    %% Library flows
    Python --> EnvLoader
    Python --> AuthComp
    AuthComp --> ReqBuilder
    ReqBuilder -->|HTTP Request| FormAPI
    FormAPI -->|JSON Response| RespParser
    RespParser --> APIMethods
    APIMethods --> DevCode

    %% Tests interaction
    Python --> Tests
    Tests --> APIMethods

    %% Developer code
    DevCode --> APIMethods

    %% Documentation references
    Readme --> UV
    Readme --> DevCode
    GitIgnore --> VENV

    %% Click Events
    click AuthComp "https://github.com/noviscient/formidium-api-python/blob/master/formidium.py"
    click ReqBuilder "https://github.com/noviscient/formidium-api-python/blob/master/formidium.py"
    click RespParser "https://github.com/noviscient/formidium-api-python/blob/master/formidium.py"
    click APIMethods "https://github.com/noviscient/formidium-api-python/blob/master/formidium.py"
    click Tests "https://github.com/noviscient/formidium-api-python/blob/master/tests.py"
    click EnvExample "https://github.com/noviscient/formidium-api-python/blob/master/.env.example"
    click PyProj "https://github.com/noviscient/formidium-api-python/blob/master/pyproject.toml"
    click ReqTxt "https://github.com/noviscient/formidium-api-python/blob/master/requirements.txt"
    click UVLock "https://github.com/noviscient/formidium-api-python/blob/master/uv.lock"
    click Readme "https://github.com/noviscient/formidium-api-python/blob/master/README.md"
    click GitIgnore "https://github.com/noviscient/formidium-api-python/blob/master/.gitignore"

    %% Styles
    classDef env fill:#e0f7e0,stroke:#2d8f2d,color:#2d8f2d
    classDef lib fill:#e0f0ff,stroke:#1a4f9c,color:#1a4f9c
    classDef ext fill:#ffe0e0,stroke:#9c2d2d,color:#9c2d2d
    classDef test fill:#fff8e0,stroke:#9c8f2d,color:#9c8f2d
    classDef doc fill:#f0f0f0,stroke:#8f8f8f,color:#4f4f4f
```
