[Docs]: Naming Environment Variables

[TonyB9000]

It would make coding easier if required environment variables could indicate - by naming - whether they are merely intended to simplify the job of the (cron'd) launcher, or must be passed through (exported) to the simboard collection system itself.

Presently, "SIMBOARD_ROOT" holds the parent path to both the simboard repository and the simboard operations directory (pwd for crontab initial execution.) These are codified as "SIMBOARD_MODULES" and "SIMBOARD_WORKDIR", exported by the launcher as follows:

export SIMBOARD_MODULES="${SIMBOARD_ROOT}/repository/simboard/backend"
export SIMBOARD_WORKDIR="${SIMBOARD_ROOT}/operations"

These may be overridden explicitly in the site.config file, but need not. However, it is unclear whether these need to be exported for uptake in the subsequently invoked SIMBOARD_INGESTOR_MODULE:

app.scripts.ingestion.hpc_upload_archive_ingestor

I don't know if there is a trivial way to expose what downstream processes expect to read in terms of environment variables. If such exists, there is perhaps little need for refined variable naming.

The Great AI suggests maintaining a json table:

{
  "variables": [
    {"name": "APP_MODE", "required": true, "secret": false},
    {"name": "API_TOKEN", "required": true, "secret": true},
    {"name": "LOG_LEVEL", "required": false, "default": "info"}
  ]
}

But this does not serve to tell you, at a given point of processing in the call-stack, which ENV VARS are already read and which still need to be.

I posed a further question:

When working code in the middle of a process call-stack, it seems problematic to know which ENV VARS have already been read, or have been exported for later reading, or still need to be exported for processes further down the call stack. The decoupled nature of ENV VARS as a means of communicating values (as opposed to explicit command-line parameters) seems a detriment to development.

The Great AI replied:

That concern is valid. Environment variables are intentionally implicit, process-wide configuration, so they provide weak visibility and no built-in tracking of:

    Which variables were read
    Which values were inherited
    Which variables were modified or exported
    Which downstream process expects them
    Whether a variable is stale or incorrectly scoped

A useful approach is to treat environment variables as an explicit interface rather than ambient state:

    Define an environment contract
        Required and optional variables
        Defaults and allowed values
        Secret classification
        Producer and consumer
        Scope and lifetime

    Centralize access
        Read variables through a configuration module or wrapper.
        Avoid scattered calls to getenv, os.environ, or equivalent APIs.
        Record access metadata in development or test builds.

    Track propagation explicitly
        Construct a deliberate child-process environment.
        Use allowlists rather than inheriting everything.
        Log variable names and actions, but never secret values.

    Validate at process boundaries
        Run an environment check before starting a component.
        Fail early when required variables are missing or invalid.
        Optionally expose a schema for tooling and CI.

    Prefer explicit parameters within the application
        Convert environment variables into a typed configuration object at startup.
        Pass that object or its relevant fields through internal APIs.
        Reserve environment variables for process-boundary configuration.

and furthermore:

A practical lifecycle model is:

process environment
        |
        v
startup configuration loader
        |
        v
validated typed configuration
        |
        v
explicit application parameters
        |
        v
allowlisted child-process environment

Environment variables remain useful for deployment and process boundaries, but they are generally a poor substitute for explicit interfaces inside a call stack. A configuration schema plus centralized loading and controlled propagation can make their behavior observable without losing their deployment convenience.