Architecture
============

High-Level Flow
---------------

::

    +------------------+     HTTPS      +------------------+
    |   Web Browser    | <----------->  |  Caddy (Host)    |
    |  or API Consumer |                | 70.88.205.138    |
    +------------------+                +------------------+
                                               |
                                               | reverse proxy
                                               v
    +------------------+     HTTP       +------------------+
    |  CT 400          | <----------->  |  Flask Server    |
    | evercycle-api    |   port 5000    |  api_server.py   |
    | 10.1.10.173      |                +------------------+
    +------------------+                       |
                                               | requests
                                               v
    +------------------+     HTTPS      +------------------+
    |  Auth cache      |                | Evercycle Cloud  |
    | auth.properties  |                | api.evercycle.io |
    +------------------+                +------------------+

Component Responsibilities
--------------------------

**api_server.py (Flask REST Server)**
  * Exposes HTTP endpoints for health checks, auth, listing, and dynamic API proxying.
  * Manages token lifecycle (acquire, refresh, expiry check) via a background lock.
  * Patches ``EvercycleApiClient.call_api`` at runtime for certain endpoints
    (e.g., ``get-asset-id``) to inject path parameters into the URL.

**evercycle_api.py (CLI Client)**
  * Command-line tool for auth, listing, and calling APIs.
  * Reads/writes ``auth.properties`` and JSON configs in ``evercycle-api/config/``.

**api_client.py (Generic HTTP Client)**
  * Low-level ``requests.Session`` wrapper.
  * Supports endpoint discovery, interactive mode, and request/response history.

**api_runner.py (Config Generator & Runner)**
  * Parses markdown API specs to generate JSON configs.
  * Runs individual or all APIs in sequence.
  * Auto-injects tokens from ``auth.properties`` into config headers after sign-in.

**evercycle_api_runner.py (Interactive TUI)**
  * Menu-driven interactive tool for calling endpoints.
  * Prompts for headers, path params, query params, and body fields at runtime.

Data Flow for an Authenticated Request
--------------------------------------

1. Client calls ``POST /api/auth`` with Evercycle credentials.
2. ``api_server.py`` forwards the request to ``https://api.evercycle.io/v1/auth/signin``.
3. Tokens (``AccessToken``, ``IdToken``, ``RefreshToken``) are stored in
   ``auth.properties`` inside the ``evercycle-api`` directory.
4. Subsequent calls to ``/api/<api_name>`` trigger ``refresh_auth_token()``.
5. If the token is expired, the server attempts a refresh using the
   Evercycle refresh endpoint; if that fails, it re-authenticates using
   ``config/auth-signin.json``.
6. The API call is executed by ``EvercycleApiClient.call_api``, which:
   * Loads the JSON config for the requested API
   * Substitutes path parameters
   * Injects auth headers
   * Dispatches the HTTP request
   * Returns the JSON response

CORS Architecture
-----------------

* ``flask_cors.CORS(app)`` is applied globally.
* ``ALLOWED_ORIGINS`` restricts actual ``Access-Control-Allow-Origin`` to:
  * ``http://localhost:3000``
  * ``http://127.0.0.1:3000``
  * ``https://ui.veraetime.net``
  * ``https://*.ngrok.io``
  * ``https://*.ngrok-free.app``
* Preflight ``OPTIONS`` requests return permissive headers for any origin to
  avoid preflight failures, but credentialed requests still require a matching
  origin on the actual call.