# sven-seyfert/apiprobe architecture

> Architecture diagram of the GitHub repository sven-seyfert/apiprobe, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sven-seyfert/apiprobe
- Repository: https://github.com/sven-seyfert/apiprobe

## Overview

APIProbe is a Go CLI for running JSON-defined API checks, test-case variations, and response-change monitoring. The main workflow loads and filters request definitions, prepares bodies and secrets, executes HTTP requests (including auth-token dependencies), formats responses, compares them with saved outputs, and reports changes or errors through configured webhooks. The graph retains README-documented configuration, filtering, secret management, auth, diffing, logging, and notification capabilities. Source coverage is based on the excerpts and SOURCE INDEX; unsampled internals are represented only where documented.

Main entry points: [`main.go`](https://github.com/sven-seyfert/apiprobe/blob/main/main.go) (Run orchestrator), [`internal/exec/exec.go`](https://github.com/sven-seyfert/apiprobe/blob/main/internal/exec/exec.go) (Request and test-case processing), [`internal/flags/flags.go`](https://github.com/sven-seyfert/apiprobe/blob/main/internal/flags/flags.go) (CLI flags), [`internal/report/notify.go`](https://github.com/sven-seyfert/apiprobe/blob/main/internal/report/notify.go) (Notification dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["CLI and definitions"]
  node_flags["CLI flags<br/>[flags.go]"]
  node_loader["Request loading and filtering<br/>[loader.go]"]
  node_requestdata["Input request JSON<br/>[users.json]"]
end

subgraph group_security["Secrets and auth"]
  node_crypto["Secret handling<br/>[obfuscator.go]"]
  node_secretsdb[("Secret database<br/>[sqlite.go]")]
  node_token["Auth token store<br/>[token.go]"]
  node_tokenhandler["Token substitution<br/>[token-handler.go]"]
end

subgraph group_runtime["Request execution"]
  node_main["Run orchestrator<br/>[main.go]"]
  node_curl["HTTP request runner<br/>[curl.go]"]
  node_jq["Response formatting<br/>[jq.go]"]
  node_executor["Request and test-case processing<br/>[exec.go]"]
end

subgraph group_results["Change and reporting"]
  node_outputpath["Output path helper<br/>[path.go]"]
  node_diff["Response change detection<br/>[diff.go]"]
  node_outputfiles["Saved responses"]
  node_report["Run report<br/>[report.go]"]
  node_notify["Notification dispatch<br/>[notify.go]"]
  node_webex["WebEx delivery<br/>[webex.go]"]
  node_teams["Teams delivery<br/>[msteams.go]"]
end

subgraph group_platform["Configuration and logging"]
  node_config["Run configuration<br/>[config.go]"]
  node_logger["Logging<br/>[logger.go]"]
end

node_user(("CLI user"))
node_externalapi(("API service"))
node_webhooks(("Webhook endpoints"))
node_jqcommand["jq processor"]

node_user -->|"starts run"| node_main
node_main -->|"parses flags"| node_flags
node_main -->|"loads config"| node_config
node_main -->|"loads and filters"| node_loader
node_loader -->|"reads definitions"| node_requestdata
node_flags -->|"generates IDs"| node_crypto
node_flags -->|"stores secrets"| node_secretsdb
node_main -->|"seeds database"| node_secretsdb
node_main -->|"resolves secrets"| node_crypto
node_crypto -.->|"reads secrets"| node_secretsdb
node_main -->|"processes requests"| node_executor
node_executor -->|"invokes HTTP"| node_curl
node_curl -->|"sends request"| node_externalapi
node_externalapi -.->|"returns response"| node_curl
node_executor -->|"formats response"| node_jq
node_jq -.->|"runs query"| node_jqcommand
node_main -->|"substitutes auth token"| node_tokenhandler
node_tokenhandler -->|"looks up token"| node_token
node_executor -->|"stores auth result"| node_token
node_executor -->|"builds output path"| node_outputpath
node_executor -->|"compares response"| node_diff
node_diff -->|"reads and writes"| node_outputfiles
node_executor -->|"records outcomes"| node_report
node_main -->|"sends notification"| node_notify
node_notify -.->|"dispatches WebEx"| node_webex
node_notify -.->|"dispatches Teams"| node_teams
node_webex -.->|"posts alerts"| node_webhooks
node_teams -.->|"posts alerts"| node_webhooks
node_executor -.->|"logs execution"| node_logger
node_main -->|"logs run"| node_logger

click node_flags "https://github.com/sven-seyfert/apiprobe/blob/main/internal/flags/flags.go"
click node_loader "https://github.com/sven-seyfert/apiprobe/blob/main/internal/loader/loader.go"
click node_config "https://github.com/sven-seyfert/apiprobe/blob/main/internal/config/config.go"
click node_main "https://github.com/sven-seyfert/apiprobe/blob/main/main.go"
click node_crypto "https://github.com/sven-seyfert/apiprobe/blob/main/internal/crypto/obfuscator.go"
click node_secretsdb "https://github.com/sven-seyfert/apiprobe/blob/main/internal/db/sqlite.go"
click node_token "https://github.com/sven-seyfert/apiprobe/blob/main/internal/auth/token.go"
click node_tokenhandler "https://github.com/sven-seyfert/apiprobe/blob/main/internal/auth/token-handler.go"
click node_requestdata "https://github.com/sven-seyfert/apiprobe/blob/main/data/input/reqres-api/users.json"
click node_curl "https://github.com/sven-seyfert/apiprobe/blob/main/internal/exec/curl.go"
click node_jq "https://github.com/sven-seyfert/apiprobe/blob/main/internal/exec/jq.go"
click node_executor "https://github.com/sven-seyfert/apiprobe/blob/main/internal/exec/exec.go"
click node_outputpath "https://github.com/sven-seyfert/apiprobe/blob/main/internal/fileutil/path.go"
click node_diff "https://github.com/sven-seyfert/apiprobe/blob/main/internal/diff/diff.go"
click node_outputfiles "https://github.com/sven-seyfert/apiprobe/blob/main/data/output/reqres-api/users-test-case-00.json"
click node_report "https://github.com/sven-seyfert/apiprobe/blob/main/internal/report/report.go"
click node_notify "https://github.com/sven-seyfert/apiprobe/blob/main/internal/report/notify.go"
click node_webex "https://github.com/sven-seyfert/apiprobe/blob/main/internal/report/webex.go"
click node_teams "https://github.com/sven-seyfert/apiprobe/blob/main/internal/report/msteams.go"
click node_logger "https://github.com/sven-seyfert/apiprobe/blob/main/internal/logger/logger.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_flags,node_loader,node_requestdata,node_user toneBlue
class node_crypto,node_secretsdb,node_token,node_tokenhandler toneAmber
class node_main,node_curl,node_jq,node_executor,node_externalapi,node_webhooks toneMint
class node_outputpath,node_diff,node_outputfiles,node_report,node_notify,node_webex,node_teams toneRose
class node_config,node_logger,node_jqcommand toneIndigo
```

## Components

### CLI and definitions

- [CLI flags](https://github.com/sven-seyfert/apiprobe/blob/main/internal/flags/flags.go): `internal/flags/flags.go`
- [Request loading and filtering](https://github.com/sven-seyfert/apiprobe/blob/main/internal/loader/loader.go): `internal/loader/loader.go`
- [Input request JSON](https://github.com/sven-seyfert/apiprobe/blob/main/data/input/reqres-api/users.json): `data/input/reqres-api/users.json`

### Secrets and auth

- [Secret handling](https://github.com/sven-seyfert/apiprobe/blob/main/internal/crypto/obfuscator.go): `internal/crypto/obfuscator.go`
- [Secret database](https://github.com/sven-seyfert/apiprobe/blob/main/internal/db/sqlite.go): `internal/db/sqlite.go`
- [Auth token store](https://github.com/sven-seyfert/apiprobe/blob/main/internal/auth/token.go): `internal/auth/token.go`
- [Token substitution](https://github.com/sven-seyfert/apiprobe/blob/main/internal/auth/token-handler.go): `internal/auth/token-handler.go`

### Request execution

- [Run orchestrator](https://github.com/sven-seyfert/apiprobe/blob/main/main.go): `main.go`
- [HTTP request runner](https://github.com/sven-seyfert/apiprobe/blob/main/internal/exec/curl.go): `internal/exec/curl.go`
- [Response formatting](https://github.com/sven-seyfert/apiprobe/blob/main/internal/exec/jq.go): `internal/exec/jq.go`
- [Request and test-case processing](https://github.com/sven-seyfert/apiprobe/blob/main/internal/exec/exec.go): `internal/exec/exec.go`

### Change and reporting

- [Output path helper](https://github.com/sven-seyfert/apiprobe/blob/main/internal/fileutil/path.go): `internal/fileutil/path.go`
- [Response change detection](https://github.com/sven-seyfert/apiprobe/blob/main/internal/diff/diff.go): `internal/diff/diff.go`
- [Saved responses](https://github.com/sven-seyfert/apiprobe/blob/main/data/output/reqres-api/users-test-case-00.json): `data/output/reqres-api/users-test-case-00.json`
- [Run report](https://github.com/sven-seyfert/apiprobe/blob/main/internal/report/report.go): `internal/report/report.go`
- [Notification dispatch](https://github.com/sven-seyfert/apiprobe/blob/main/internal/report/notify.go): `internal/report/notify.go`
- [WebEx delivery](https://github.com/sven-seyfert/apiprobe/blob/main/internal/report/webex.go): `internal/report/webex.go`
- [Teams delivery](https://github.com/sven-seyfert/apiprobe/blob/main/internal/report/msteams.go): `internal/report/msteams.go`

### Configuration and logging

- [Run configuration](https://github.com/sven-seyfert/apiprobe/blob/main/internal/config/config.go): `internal/config/config.go`
- [Logging](https://github.com/sven-seyfert/apiprobe/blob/main/internal/logger/logger.go): `internal/logger/logger.go`

### Other components

- **CLI user**
- **API service**
- **Webhook endpoints**
- **jq processor**

## Connections

- CLI user → Run orchestrator: starts run (evidence: `README.md`)
- Run orchestrator → CLI flags: parses flags (evidence: `main.go`)
- Run orchestrator → Run configuration: loads config (evidence: `main.go`)
- Run orchestrator → Request loading and filtering: loads and filters (evidence: `main.go`)
- Request loading and filtering → Input request JSON: reads definitions (evidence: `internal/loader/loader.go`)
- CLI flags → Secret handling: generates IDs (evidence: `internal/flags/flags.go`)
- CLI flags → Secret database: stores secrets (evidence: `internal/flags/flags.go`)
- Run orchestrator → Secret database: seeds database (evidence: `main.go`)
- Run orchestrator → Secret handling: resolves secrets (evidence: `main.go`)
- Secret handling → Secret database: reads secrets
- Run orchestrator → Request and test-case processing: processes requests (evidence: `main.go`)
- Request and test-case processing → HTTP request runner: invokes HTTP (evidence: `internal/exec/exec.go`)
- HTTP request runner → API service: sends request (evidence: `internal/exec/curl.go`)
- API service → HTTP request runner: returns response
- Request and test-case processing → Response formatting: formats response (evidence: `internal/exec/exec.go`)
- Response formatting → jq processor: runs query
- Run orchestrator → Token substitution: substitutes auth token (evidence: `main.go`)
- Token substitution → Auth token store: looks up token (evidence: `internal/auth/token-handler.go`)
- Request and test-case processing → Auth token store: stores auth result (evidence: `internal/exec/exec.go`)
- Request and test-case processing → Output path helper: builds output path (evidence: `internal/exec/exec.go`)
- Request and test-case processing → Response change detection: compares response (evidence: `internal/exec/exec.go`)
- Response change detection → Saved responses: reads and writes (evidence: `internal/diff/diff.go`)
- Request and test-case processing → Run report: records outcomes (evidence: `internal/exec/exec.go`)
- Run orchestrator → Notification dispatch: sends notification (evidence: `main.go`)
- Notification dispatch → WebEx delivery: dispatches WebEx
- Notification dispatch → Teams delivery: dispatches Teams
- WebEx delivery → Webhook endpoints: posts alerts
- Teams delivery → Webhook endpoints: posts alerts
- Request and test-case processing → Logging: logs execution
- Run orchestrator → Logging: logs run (evidence: `main.go`)
