# corridor/configurable-http-proxy architecture

> Architecture diagram of the GitHub repository corridor/configurable-http-proxy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/corridor/configurable-http-proxy
- Repository: https://github.com/corridor/configurable-http-proxy

## Overview

##### Project type and purpose
- This is an open-source, drop-in replacement for the NodeJS configurable-http-proxy (CHP), written in pure Python.
- It acts as a standalone HTTP/WebSocket reverse proxy with an embedded REST API for dynamic route configuration and pluggable storage backends.

##### File structure
- Top level:
- `configurable_http_proxy/`: main Python package
- `configurable_http_proxy_test/`: unit tests
- `.github/`, CI/CD workflows
- `pyproject.toml`, `requirements.txt`: build and dependency definitions
- Inside the package:
- `cli.py`: CLI entrypoint and argument parsing
- `configproxy.py`: core server orchestration (starting listener, wiring components)
- `handlers.py`: HTTP/WebSocket request handlers and API endpoint definitions
- `store.py` & `dbstore.py`: in-memory versus SQLAlchemy-backed storage implementations
- `trie.py`: routing data structure for fast prefix lookups
- `templates/`: HTML templates for error pages
- Patterns & configs:
- Single-process, modular layering (CLI → core → handlers → storage)
- Supports multiple storage backends via a strategy pattern (pluggable)
- `.github/workflows/`: automated tests, builds, and deploy steps

##### README for additional insights
- Confirms support for HTTP & WebSocket proxying, REST API for route management, token-based auth, custom headers, timeouts, error page customization.
- Highlights optional SQL storage for HA scenarios.

##### Detail without overcomplicating
- Break the system into the seven components listed above.
- Special behaviors (e.g., “trie-based lookup for routing”, “strategy pattern for storage”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Proxy System"
        CLI["CLI Layer"]:::compute
        Core["Proxy Core<br/>(Listener & Orchestrator)"]:::compute
        subgraph "Request Handlers"
            HTTP["HTTP/WebSocket Handler"]:::compute
            REST["REST API Handler"]:::compute
        end
        Router["Router<br/>(trie-based lookup)"]:::compute
        subgraph "Storage Backends"
            MemStore["In-Memory Store"]:::storage
            DBStore["SQLAlchemy Store"]:::storage
        end
        Templates["Template Renderer"]:::storage
        Logger["Logger"]:::compute
    end

    External1["Upstream Target Servers"]:::external
    SQLDB["SQL Database"]:::external

    CLI -->|"initializes"| Core
    Core -->|"registers handlers"| HTTP
    Core -->|"registers handlers"| REST

    HTTP -->|"routes via"| Router
    REST -->|"CRUD routes"| MemStore
    REST -->|"CRUD routes"| DBStore

    Router -->|"lookup routes"| MemStore
    Router -->|"lookup routes"| DBStore
    Router -->|"resolves target"| External1
    HTTP -->|"forwards request"| External1

    HTTP -->|"on error"| Templates
    REST -->|"on error"| Templates

    Core -->|"logs events"| Logger
    HTTP -->|"logs events"| Logger
    REST -->|"logs events"| Logger
    MemStore -->|"logs events"| Logger
    DBStore -->|"logs events"| Logger

    DBStore -->|"SQLAlchemy ORM"| SQLDB

    click CLI "https://github.com/corridor/configurable-http-proxy/blob/main/configurable_http_proxy/cli.py"
    click Core "https://github.com/corridor/configurable-http-proxy/blob/main/configurable_http_proxy/configproxy.py"
    click HTTP "https://github.com/corridor/configurable-http-proxy/blob/main/configurable_http_proxy/handlers.py"
    click REST "https://github.com/corridor/configurable-http-proxy/blob/main/configurable_http_proxy/handlers.py"
    click Router "https://github.com/corridor/configurable-http-proxy/blob/main/configurable_http_proxy/trie.py"
    click MemStore "https://github.com/corridor/configurable-http-proxy/blob/main/configurable_http_proxy/store.py"
    click DBStore "https://github.com/corridor/configurable-http-proxy/blob/main/configurable_http_proxy/dbstore.py"
    click Templates "https://github.com/corridor/configurable-http-proxy/blob/main/configurable_http_proxy/templates/404.html"

    classDef compute fill:#a2d2ff,stroke:#000,stroke-width:1px
    classDef storage fill:#ffafcc,stroke:#000,stroke-width:1px
    classDef external fill:#caffbf,stroke:#000,stroke-width:1px
```
