# inspectr-hq/inspectr architecture

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

- Interactive diagram: https://gitdiagram.com/inspectr-hq/inspectr
- Repository: https://github.com/inspectr-hq/inspectr

## Overview

##### Main Components
- API Proxy Server (Inspectr Core):
– Listens on a specified port (default “:8080”) to capture incoming HTTP requests.
– Forwards the requests to a backend service (if configured) and relays responses.
– Wraps each operation in a CloudEvents envelope for standardized logging.
- Embedded Inspectr App (UI Component):
– Runs on a separate port (default “4004”) providing a real‑time user interface for viewing incoming requests and responses.
– Utilizes SSE (Server-Sent Events) or similar techniques to broadcast updates.
- Inspectr Ingress (Public Exposure Module):
– When enabled (via “--expose”), provides a public endpoint (with customizable subdomain via “--channel”) to expose the local proxy.
– Forwards public traffic to the local Inspectr instance.
- Request Capture & Logger:
– Captures and prints request/response summaries on the console if enabled.
– Maintains a persistent history storage (or in‑memory, controlled by configuration options such as store-path).
- Schema Definitions & Assets:
– The schema directory outlines the JSON schema definitions and examples; these define the structure of requests/operations and the CloudEvents wrapping.
– Assets include images and branding materials for the UI elements.
- Configuration and Runtime:
– Command-line options and an optional YAML config file (.inspectr.yaml) govern behavior (e.g., ports, backend URL, expose options, etc.).

##### Relationships and Data Flow
– External Client Requests (from front-end or third-party systems) hit the API Proxy.
– The Proxy processes the request:
– Either returns a default 200 OK (catch mode) or forwards the request to an actual backend service.
– Logs the request in the console (if enabled), wraps it in CloudEvents, and sends it to the UI.
– The Embedded Inspectr App fetches and displays the captured requests and responses in real time.
– When public exposure is needed, the Inspectr Ingress component creates a publicly accessible URL that routes incoming requests to the local proxy.
– Internally, configuration files (package.json, .inspectr.yaml) and schema definitions support the core logic and ensure compliance with defined request/response formats.

##### Architectural Patterns and Design Principles
– Separation of Concerns: The architecture separates the API proxy logic from the UI and public ingress components.
– Modularity: Each component (proxy core, UI, ingress) is designed as an independent module that can be enabled or disabled via configuration.
– Real-Time Data Flow: Utilizes event-driven communication (such as SSE) for real-time logging and user updates.
– Extensibility: Supporting both a command-line interface and YAML configuration provides flexibility in deployment and usage.

##### Final Advice for the Principal Software Engineer
– Label every component (API Proxy, UI App, Backend Service, Inspectr Ingress, Logging/Database) clearly.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Services"
        A("External Client Request"):::external
        F("Inspectr Ingress (Public Exposure)"):::ingress
        D("Backend Service"):::external
    end

    subgraph "Proxy Core"
        B("API Proxy Server\n(Intercepts HTTP Requests,\nwraps in CloudEvents, forwards to backend)"):::proxy
        C("Request Capture & Logger\n(captures/prints summaries)"):::logger
        I("Configuration & Runtime\n(package.json, README.md, .inspectr.yaml)"):::config
        G("Schema Definitions\n(Defines JSON schema & CloudEvents)"):::schema
    end

    subgraph "UI Layer"
        E("Inspectr App UI\n(Real-time display on port 4004)"):::ui
        H("UI Assets\n(Images & Branding)"):::schema
    end

    A -->|"capture&forward"| B
    F -->|"public_route"| B
    B -->|"forward_request"| D
    D -->|"response_return"| B
    B -->|"log"| C
    B -->|"SSE_update"| E
    I -->|"configure"| B
    G -->|"define_schema"| B
    H -->|"branding"| E

    click B "https://github.com/inspectr-hq/inspectr/blob/main/package.json"
    click E "https://github.com/inspectr-hq/inspectr/tree/main/assets/logo"
    click G "https://github.com/inspectr-hq/inspectr/tree/main/schema"
    click H "https://github.com/inspectr-hq/inspectr/tree/main/assets"
    click I "https://github.com/inspectr-hq/inspectr/blob/main/package.json"
    click I "https://github.com/inspectr-hq/inspectr/blob/main/README.md"

    classDef proxy fill:#85C1E9,stroke:#2E86C1,stroke-width:2px;
    classDef ui fill:#82E0AA,stroke:#28B463,stroke-width:2px;
    classDef ingress fill:#F5B041,stroke:#D35400,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#F4D03F,stroke-width:2px;
    classDef config fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;
    classDef logger fill:#F1948A,stroke:#C0392B,stroke-width:2px;
    classDef schema fill:#BB8FCE,stroke:#8E44AD,stroke-width:2px;
```
