# evg4b/uncors architecture

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

- Interactive diagram: https://gitdiagram.com/evg4b/uncors
- Repository: https://github.com/evg4b/uncors

## Overview

UNCORS is a development HTTP/HTTPS proxy that maps local hosts to upstreams and replaces CORS headers. The main workflow is CLI startup, configuration-driven runtime construction, host/path routing, then a selected handler returning the response through the server. The README also documents mocking, scripting, static files, caching, rewriting, HAR capture, wildcard mapping, and generated-certificate HTTPS. Several subsystem links are documented rather than source-verified because their implementation excerpts were not provided.

Main entry points: [`internal/config/mapping.go`](https://github.com/evg4b/uncors/blob/main/internal/config/mapping.go) (Config and mappings), [`internal/handler/router/router.go`](https://github.com/evg4b/uncors/blob/main/internal/handler/router/router.go) (Host router), [`internal/server/server.go`](https://github.com/evg4b/uncors/blob/main/internal/server/server.go) (HTTP server), [`internal/handler/proxy/handler.go`](https://github.com/evg4b/uncors/blob/main/internal/handler/proxy/handler.go) (Upstream proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Startup and UI"]
  node_main["CLI entry<br/>[main.go]"]
  node_cli["CLI commands"]
  node_interactive["Interactive UI<br/>[app.go]"]
  node_tui["Terminal output<br/>[output.go]"]
end

subgraph group_config["Configuration and runtime"]
  node_config["Config and mappings<br/>[mapping.go]"]
  node_runtime["Runtime builder<br/>[runtime.go]"]
end

subgraph group_routing["Request handling"]
  node_router["Host router<br/>[router.go]"]
end

subgraph group_features["Proxy features"]
  node_proxy["Upstream proxy<br/>[handler.go]"]
  node_urlreplace["URL replacement<br/>[replacer.go]"]
  node_rewrite["Request rewriting<br/>[handler.go]"]
  node_mock["Response mocking"]
  node_script["Lua scripts<br/>[handler.go]"]
  node_static["Static files<br/>[middleware.go]"]
  node_cache["Response cache<br/>[middleware.go]"]
  node_har["HAR capture<br/>[middleware.go]"]
end

subgraph group_serving["Server and observability"]
  node_server["HTTP server<br/>[server.go]"]
  node_tls["TLS certificates"]
  node_tracker["Request tracker<br/>[request_tracker.go]"]
end

node_developer(("Developer"))
node_upstream(("Upstream service"))

node_developer -->|"starts"| node_main
node_main -->|"dispatches"| node_cli
node_cli -->|"loads"| node_config
node_cli -->|"builds"| node_runtime
node_runtime -->|"constructs"| node_router
node_runtime -->|"configures"| node_proxy
node_router -->|"routes default"| node_proxy
node_router -->|"routes matches"| node_mock
node_router -->|"routes matches"| node_script
node_router -->|"registers paths"| node_static
node_router -->|"wraps routes"| node_rewrite
node_router -->|"wraps default"| node_cache
node_router -->|"wraps default"| node_har
node_proxy -->|"rewrites URLs"| node_urlreplace
node_proxy -->|"forwards request"| node_upstream
node_proxy -->|"reads response"| node_upstream
node_cli -->|"starts server"| node_server
node_runtime -->|"provides targets"| node_server
node_server -->|"serves handlers"| node_router
node_server -->|"emits events"| node_tracker
node_server -.->|"uses certificates"| node_tls
node_developer -->|"runs interactively"| node_interactive
node_interactive -->|"starts and restarts"| node_server
node_interactive -->|"watches events"| node_tracker
node_interactive -->|"prints requests"| node_tui
node_config -.->|"defines host mappings"| node_urlreplace
node_config -.->|"enables HTTPS"| node_tls
node_config -.->|"configures responses"| node_mock
node_config -.->|"configures scripts"| node_script
node_config -.->|"configures serving"| node_static
node_config -.->|"configures caching"| node_cache
node_config -.->|"configures recording"| node_har
node_config -.->|"configures rewrites"| node_rewrite

click node_main "https://github.com/evg4b/uncors/blob/main/main.go"
click node_cli "https://github.com/evg4b/uncors/blob/main/internal/cli/run_non_interactive.go"
click node_interactive "https://github.com/evg4b/uncors/blob/main/internal/uncors_app/app.go"
click node_config "https://github.com/evg4b/uncors/blob/main/internal/config/mapping.go"
click node_runtime "https://github.com/evg4b/uncors/blob/main/internal/di/runtime.go"
click node_router "https://github.com/evg4b/uncors/blob/main/internal/handler/router/router.go"
click node_proxy "https://github.com/evg4b/uncors/blob/main/internal/handler/proxy/handler.go"
click node_urlreplace "https://github.com/evg4b/uncors/blob/main/internal/urlreplacer/replacer.go"
click node_rewrite "https://github.com/evg4b/uncors/blob/main/internal/handler/rewrite/handler.go"
click node_mock "https://github.com/evg4b/uncors/tree/main/internal/handler/mock"
click node_script "https://github.com/evg4b/uncors/blob/main/internal/handler/script/handler.go"
click node_static "https://github.com/evg4b/uncors/blob/main/internal/handler/static/middleware.go"
click node_cache "https://github.com/evg4b/uncors/blob/main/internal/handler/cache/middleware.go"
click node_har "https://github.com/evg4b/uncors/blob/main/internal/handler/har/middleware.go"
click node_server "https://github.com/evg4b/uncors/blob/main/internal/server/server.go"
click node_tls "https://github.com/evg4b/uncors/blob/main/internal/server/host_cert_manager.go"
click node_tracker "https://github.com/evg4b/uncors/blob/main/internal/server/request_tracker.go"
click node_tui "https://github.com/evg4b/uncors/blob/main/internal/tui/output.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_main,node_cli,node_interactive,node_tui toneBlue
class node_config,node_runtime toneAmber
class node_router toneMint
class node_proxy,node_urlreplace,node_rewrite,node_mock,node_script,node_static,node_cache,node_har toneRose
class node_server,node_tls,node_tracker,node_developer,node_upstream toneIndigo
```

## Components

### Startup and UI

- [CLI entry](https://github.com/evg4b/uncors/blob/main/main.go): `main.go`
- [CLI commands](https://github.com/evg4b/uncors/blob/main/internal/cli/run_non_interactive.go): `internal/cli/run_non_interactive.go`
- [Interactive UI](https://github.com/evg4b/uncors/blob/main/internal/uncors_app/app.go): `internal/uncors_app/app.go`
- [Terminal output](https://github.com/evg4b/uncors/blob/main/internal/tui/output.go): `internal/tui/output.go`

### Configuration and runtime

- [Config and mappings](https://github.com/evg4b/uncors/blob/main/internal/config/mapping.go): `internal/config/mapping.go`
- [Runtime builder](https://github.com/evg4b/uncors/blob/main/internal/di/runtime.go): `internal/di/runtime.go`

### Request handling

- [Host router](https://github.com/evg4b/uncors/blob/main/internal/handler/router/router.go): `internal/handler/router/router.go`

### Proxy features

- [Upstream proxy](https://github.com/evg4b/uncors/blob/main/internal/handler/proxy/handler.go): `internal/handler/proxy/handler.go`
- [URL replacement](https://github.com/evg4b/uncors/blob/main/internal/urlreplacer/replacer.go): `internal/urlreplacer/replacer.go`
- [Request rewriting](https://github.com/evg4b/uncors/blob/main/internal/handler/rewrite/handler.go): `internal/handler/rewrite/handler.go`
- [Response mocking](https://github.com/evg4b/uncors/tree/main/internal/handler/mock): `internal/handler/mock`
- [Lua scripts](https://github.com/evg4b/uncors/blob/main/internal/handler/script/handler.go): `internal/handler/script/handler.go`
- [Static files](https://github.com/evg4b/uncors/blob/main/internal/handler/static/middleware.go): `internal/handler/static/middleware.go`
- [Response cache](https://github.com/evg4b/uncors/blob/main/internal/handler/cache/middleware.go): `internal/handler/cache/middleware.go`
- [HAR capture](https://github.com/evg4b/uncors/blob/main/internal/handler/har/middleware.go): `internal/handler/har/middleware.go`

### Server and observability

- [HTTP server](https://github.com/evg4b/uncors/blob/main/internal/server/server.go): `internal/server/server.go`
- [TLS certificates](https://github.com/evg4b/uncors/blob/main/internal/server/host_cert_manager.go): `internal/server/host_cert_manager.go`
- [Request tracker](https://github.com/evg4b/uncors/blob/main/internal/server/request_tracker.go): `internal/server/request_tracker.go`

### Other components

- **Developer**
- **Upstream service**

## Connections

- Developer → CLI entry: starts (evidence: `main.go`)
- CLI entry → CLI commands: dispatches (evidence: `main.go`)
- CLI commands → Config and mappings: loads (evidence: `internal/cli/run_non_interactive.go`)
- CLI commands → Runtime builder: builds (evidence: `internal/cli/run_non_interactive.go`)
- Runtime builder → Host router: constructs (evidence: `internal/di/runtime.go`)
- Runtime builder → Upstream proxy: configures (evidence: `internal/di/runtime.go`)
- Host router → Upstream proxy: routes default (evidence: `internal/handler/router/router.go`)
- Host router → Response mocking: routes matches (evidence: `internal/handler/router/router.go`)
- Host router → Lua scripts: routes matches (evidence: `internal/handler/router/router.go`)
- Host router → Static files: registers paths (evidence: `internal/handler/router/router.go`)
- Host router → Request rewriting: wraps routes (evidence: `internal/handler/router/router.go`)
- Host router → Response cache: wraps default (evidence: `internal/handler/router/router.go`)
- Host router → HAR capture: wraps default (evidence: `internal/handler/router/router.go`)
- Upstream proxy → URL replacement: rewrites URLs (evidence: `internal/handler/proxy/handler.go`)
- Upstream proxy → Upstream service: forwards request (evidence: `internal/handler/proxy/handler.go`)
- Upstream proxy → Upstream service: reads response (evidence: `internal/handler/proxy/handler.go`)
- CLI commands → HTTP server: starts server (evidence: `internal/cli/run_non_interactive.go`)
- Runtime builder → HTTP server: provides targets (evidence: `internal/di/runtime.go`)
- HTTP server → Host router: serves handlers (evidence: `internal/server/server.go`)
- HTTP server → Request tracker: emits events (evidence: `internal/server/server.go`)
- HTTP server → TLS certificates: uses certificates
- Developer → Interactive UI: runs interactively
- Interactive UI → HTTP server: starts and restarts (evidence: `internal/uncors_app/app.go`)
- Interactive UI → Request tracker: watches events (evidence: `internal/uncors_app/app.go`)
- Interactive UI → Terminal output: prints requests (evidence: `internal/uncors_app/app.go`)
- Config and mappings → URL replacement: defines host mappings
- Config and mappings → TLS certificates: enables HTTPS
- Config and mappings → Response mocking: configures responses
- Config and mappings → Lua scripts: configures scripts
- Config and mappings → Static files: configures serving
- Config and mappings → Response cache: configures caching
- Config and mappings → HAR capture: configures recording
- Config and mappings → Request rewriting: configures rewrites
