How inspectr-hq/inspectr works
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.