# fred1268/okapi architecture

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

- Interactive diagram: https://gitdiagram.com/fred1268/okapi
- Repository: https://github.com/fred1268/okapi

## Overview

##### Main Components
- CLI / Entry Point:
– Represented by main.go, it is the starting point that parses command-line arguments (using the go-clap dependency) and orchestrates how tests are executed.
- Configuration Manager:
– Responsible for reading and parsing the configuration file (e.g., assets/config.json) that defines server details and authentication mechanisms.
- Test Loader:
– Scans the test directory (assets/tests or a user-specified directory) for files ending with “.test.json”. It loads each test file, including any auxiliary payload or expected response files.
- Test Executor / Runner:
– Iterates over the loaded tests (either sequentially or in parallel as dictated by command-line flags and file structure). It handles executing individual test cases.
- HTTP Client:
– Handles actual HTTP requests based on parameters drawn from each test (method, endpoint, payload, URL parameters). It also embeds custom headers (like X-okapi-testname) for debugging.
- Response Validator:
– Compares actual HTTP responses (status codes and payloads) against the expected output (supporting JSON comparisons and regular expression matching).
- & Substitution Module:
– Manages dynamic variable capturing from responses (e.g., captured IDs) and environment variable substitution for endpoints, payloads, and config fields.
- Logger / Debug Module:
– Provides detailed output when tests are executed in verbose or debug mode. This module logs request details, error messages, and overall test results.

##### And Illustrate Relationships/Interactions
- Configuration Manager: to load the server definitions from the config file.
- Test Loader: to fetch all the test files from the file system.
– The Test Executor then takes the loaded tests and, for each test case, interacts with:
- The HTTP Client (which issues the request to the target API server as defined in the configuration).
- The Response Validator (which compares returned responses with expected ones).
- The Capture & Substitution Module (to process dynamic test data and substitutions for subsequent tests).
– The Logger/Debug Module is used throughout these components to output runtime debugging and status information.
– Underpinning many of these processes are internal libraries, as seen in the testing/internal directories (JSON processing, logging helpers, and string utilities). They should be included as helper modules connected to their consumers (e.g., Test Executor and HTTP Client).

##### Architectural Patterns and Design Principles
– Modularity: Each component (configuration parsing, test loading, executing, HTTP handling, validation) is logically separated. Consider using distinct modules or packages for these concerns if extending the architecture.
– Extensibility: The design supports both sequential and parallel execution modes. It also supports environment-dependent configuration and variable capture, which can be shown as optional processing blocks.
– Reusability: The use of internal packages for JSON handling, logging, and other utilities should be highlighted as reusable components across the test lifecycle.

##### Relevant Technologies, Frameworks, or Libraries
– Golang is the base platform.
– The go-clap library is used for command-line parsing.
– Standard Go packages for HTTP (net/http) would be used for making web requests.
– The project leverages JSON parsing and testing facilities built into the Go ecosystem.

- For example, “CLI invokes Configuration Manager” or “Test Executor sends HTTP request via HTTP Client.”
– Make sure to illustrate optional flows (like setup and teardown files) by marking them separately, as these files can affect the test lifecycle.
– Annotate any external dependencies such as the go-clap library and point out that environment variables and dynamic captures are integral parts of the request and response processing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Layer"
        CLI["Command-Line Interface (Entry Point)"]:::cli
    end

    subgraph "Configuration & Test Setup"
        CONFIG["Configuration Manager"]:::config
        LOADER["Test Loader"]:::config
    end

    subgraph "Test Execution Layer"
        EXEC["Test Executor / Runner"]:::executor
        HTTP["HTTP Client"]:::executor
        RESP["Response Validator"]:::executor
        CAPT["Capture & Substitution Module"]:::executor
        LOGGER["Logger / Debug Module"]:::executor
    end

    subgraph "Internal Libraries"
        JSON["JSON Processing"]:::internal
        OSUTIL["OS Utilities"]:::internal
    end

    CLI -->|"invokes"| CONFIG
    CLI -->|"invokes"| LOADER
    CONFIG -->|"provides_config_to"| EXEC
    LOADER -->|"provides_tests_to"| EXEC
    EXEC -->|"calls"| HTTP
    EXEC -->|"calls"| RESP
    EXEC -->|"calls"| CAPT
    EXEC --- LOGGER
    HTTP --- LOGGER
    RESP --- LOGGER
    CAPT --- LOGGER

    HTTP -->|"uses"| JSON
    EXEC -->|"uses"| JSON
    HTTP -->|"uses"| OSUTIL

    click CLI "https://github.com/fred1268/okapi/blob/development/main.go"
    click CONFIG "https://github.com/fred1268/okapi/blob/development/assets/config.json"
    click CONFIG "https://github.com/fred1268/okapi/blob/development/testing/config.go"
    click LOADER "https://github.com/fred1268/okapi/blob/development/testing/loader.go"
    click EXEC "https://github.com/fred1268/okapi/blob/development/testing/test.go"
    click HTTP "https://github.com/fred1268/okapi/blob/development/testing/client.go"
    click RESP "https://github.com/fred1268/okapi/blob/development/testing/api.go"
    click LOGGER "https://github.com/fred1268/okapi/blob/development/testing/internal/log/log.go"
    click JSON "https://github.com/fred1268/okapi/blob/development/testing/internal/json/json.go"
    click OSUTIL "https://github.com/fred1268/okapi/blob/development/testing/internal/os/strings.go"

    classDef cli fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef config fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef executor fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef internal fill:#f8d7da,stroke:#333,stroke-width:2px;
```
