🚀 LoadForge Platform Overview & Architecture

LoadForge is an open-source, local-first performance testing and observability platform designed to give developers immediate, low-latency insights into API capacity, tail latencies, and system bottlenecks.

💡 Why Local-First Observability?

Unlike cloud load testing platforms that incur expensive usage fees and route internal traffic across external networks, LoadForge runs 100% locally on your workstation or internal test environment. Your API credentials, payloads, and benchmarks never leave your machine.

Architecture Overview

LoadForge is built using a zero-dependency architecture packaged into a single Go binary:

Go High-Concurrency Load Engine: Asynchronous goroutine worker pools with tuned HTTP connection reuse (HTTP/1.1 keep-alive and HTTP/2 multiplexing) capable of generating tens of thousands of requests per second.
Embedded React + Tailwind Dashboard: The full-featured Vite React single-page application is compiled into pure JavaScript and embedded directly into the Go binary using Go's embed.FS.
Embedded SQLite Storage Engine: Automatically initializes and manages a zero-config SQLite database at ~/.loadforge/loadforge.db to store test configurations, execution runs, error logs, and metrics.
Real-Time WebSockets Telemetry Hub: Streams lock-free atomic counters for RPS, errors, percentiles, and HTTP status codes to browser clients at sub-second intervals.

System Architecture Diagram

ASCII Architecture Flow

+-------------------------------------------------------------------+
|                        LoadForge Single Binary                    |
|                                                                   |
|  +--------------------+   WebSockets   +-----------------------+  |
|  | Embedded React UI  | <------------> | WebSockets Broadcast  |  |
|  |  (Dashboard/Docs)  |    REST API    |       Telemetry       |  |
|  +--------------------+ <------------> +-----------------------+  |
|                                                    |              |
|                                                    v              |
|  +--------------------+                +-----------------------+  |
|  | SQLite Local DB    | <------------> | High-Concurrency Engine|  |
|  | ~/.loadforge.db    |                | (Goroutine Worker Pool|  |
|  +--------------------+                +-----------------------+  |
+----------------------------------------------------|--------------+
                                                     | HTTP/1.1 & HTTP/2
                                                     v
                                        +-------------------------+
                                        | Target Application API  |
                                        +-------------------------+

⚡ Quick Start & Installation Guide

Method 1: Universal 1-Line Terminal Quick Installer (Recommended)

Auto-detects your operating system (macOS Apple Silicon, macOS Intel, Linux, Windows), downloads LoadForge, sets executable permissions, and launches the dashboard automatically:

bash — Terminal Command

curl -fsSL https://raw.githubusercontent.com/khajumsanjog/LoadForge/main/install.sh | sh

Method 2: 1-Click Source Code ZIP Download

Download the complete project source code containing both backend/ and frontend/ directories:

👉 Download LoadForge-SourceCode.zip

bash — Running from Source

# Extract ZIP and navigate to backend directory
cd LoadForge/backend

# Option A: Run directly with Go
go run main.go -browser

# Option B: Compile standalone binary
go build -o loadforge main.go
./loadforge -port 8080 -browser

💻 CLI Command-Line Flags Reference

Configure runtime options when starting the LoadForge server from your terminal:

Flag	Type	Default Value	Description
`-port`	`int`	`8080`	HTTP server port for dashboard UI, REST API endpoints, and WebSocket stream.
`-db`	`string`	`~/.loadforge/loadforge.db`	Absolute file path to the local SQLite database file.
`-browser`	`bool`	`false`	Automatically opens the web dashboard in system default browser on server startup.
`-v`	`bool`	`false`	Enables verbose debug logging of worker pool states and request timing metrics.

📈 Traffic Load Profiles & Generation Strategies

LoadForge supports 6 traffic generation profiles designed to test baseline throughput, linear scaling, sudden traffic surges, and breaking points.

1. Constant Load Profile

Maintains a fixed target number of Virtual Users (VUs) for a specified test duration (e.g., 100 VUs for 5 minutes). Best for establishing steady-state latency and throughput baselines.

2. Ramp-Up / Ramp-Down

Linearly scales Virtual User concurrency from a starting count to a target peak over a ramp period, then scales back down. Pinpoints exact concurrency thresholds where latency begins to degrade.

3. Spike Test Profile

Instantaneously surges Virtual Users (e.g., 20 VUs → 2,000 VUs in 5 seconds). Tests how fast your web server, connection pool, and auto-scaler recover from sudden bursts.

4. Breakpoint Auto-Stop

Steadily escalates Virtual Users until error rate exceeds threshold (>5% 5xx errors) or P95 latency exceeds maximum SLA limit. Automatically halts the test to prevent cascading server crashes.

5. Stress Test Profile

Pushes traffic beyond expected capacity to determine ultimate breaking point concurrency, memory exhaustion limit, and error failure modes.

6. Soak Test Profile

Runs a sustained moderate load over extended time periods (e.g., 2 hours). Detects slow memory leaks, database connection pool exhaustion, and disk log accumulation.

🔄 Multi-Step User Journeys & Dynamic Extractions

Simulate realistic multi-step user scenarios (e.g., Login → Extract Bearer Token → Fetch Product Catalog → Create Order).

Variable Extraction Types

Source	Expression Format	Example Usage
`body_json`	JSONPath (e.g. `$.data.auth.token`)	Extracts JWT bearer tokens or created item IDs from JSON response bodies.
`header`	Header key name (e.g. `Set-Cookie` or `X-Request-ID`)	Captures session cookies or server transaction correlation IDs.
`body_regex`	Regular expression with capture group (e.g. `session_id=(.*?)&`)	Extracts dynamic tokens from HTML forms, XML, or plain text responses.

Dynamic Variables & Placeholders

Use double-curly brace placeholders anywhere in request headers, URL query parameters, or body payloads:

json — Multi-Step Dynamic Variable Injection

// Step 1: POST /api/v1/auth/login Response
{
  "status": "success",
  "access_token": "eyJhbGciOiJIUzI1Ni..."
}

// Step 2 Request Header:
Authorization: Bearer {{access_token}}
X-Client-Timestamp: {{timestamp}}
X-Random-ID: {{random_uuid}}

📥 API Specification Importers Reference

Convert existing API specs or browser sessions into LoadForge test configurations in one click.

OpenAPI 3.0 / Swagger 2.0: Paste or upload OpenAPI JSON/YAML specs. LoadForge automatically parses endpoints, HTTP methods, path parameters, and sample request body schemas.
Postman Collections v2.1: Import Postman Collection JSON files. Preserves request headers, body payloads, and environment variable mappings.
cURL Command Importer: Paste any single or multi-line cURL command string. LoadForge extracts target URL, HTTP method, headers, and request data.
HAR (HTTP Archive) Importer: Import HAR session files exported from Chrome DevTools to replicate real browser traffic sequences.

📊 Real-Time Telemetry & Quantiles Math

LoadForge uses lock-free atomic counters and exact percentile math algorithms to calculate tail latencies without impacting load generator throughput.

Percentile Metric Definitions

Metric	Definition	Why It Matters
Total RPS	Total HTTP requests completed per second across all Virtual Users.	Measures overall server throughput capacity.
P50 (Median)	Response latency experienced by 50% of requests.	Represents typical user experience.
P90 Line	90% of requests were faster than this time.	Highlights latency progression under load.
P95 / P99 Line	95% and 99% of requests were faster than this latency.	Identifies tail latency for worst-case heavy users.
P99.9 Line	99.9% quantile threshold (1 in 1,000 requests).	Reveals severe garbage collection pauses or DB lock timeouts.

🌊 HTTP Request Timing Waterfalls (TTFB)

LoadForge breaks down HTTP latency into sub-phase timing waterfalls for granular diagnostic analysis:

DNS Lookup Time

Time required to resolve host domain name to target IP address. High DNS latency indicates local resolver or DNS cache issues.

TCP Handshake Time

Duration to establish 3-way TCP socket connection. High TCP latency indicates network congestion or SYN queue backlog.

TLS Handshake Time

Time to negotiate SSL/TLS certificates and key exchange. Indicates crypto CPU overhead or missing HTTP connection keep-alive.

TTFB (Time to First Byte)

Time elapsed from sending request until receiving first response byte. Represents server application code and database query processing time.

🔍 Automated Bottleneck Detection Engine

LoadForge analyzes telemetry streams algorithmically using a 4-step diagnostic framework:

Observation: Detects sudden latency inflection points or error spikes during test execution.
Evidence: Gathers matching HTTP status distributions (e.g. 504 Gateway Timeout or 503 Service Unavailable) and TTFB waterfall spikes.
Likely Root Cause: Classifies problem into Database Connection Lock, Thread/Worker Pool Exhaustion, Memory Leak, or Socket Starvation.
Recommended Action: Provides concrete remediation steps (e.g., increase DB pool size, add HTTP keep-alive header, optimize slow SQL query).

⚖️ Side-by-Side Test Run Comparisons

Compare baseline test runs against new deployment runs to catch performance regressions before production rollout.

LoadForge computes absolute and percentage deltas for:

Total Requests Per Second (% increase / decrease)
P50, P95, and P99 Latency Delays (ms delta)
Error Rate Percentage Variations (% change in 5xx failures)
Endpoint-by-Endpoint latency breakdown comparisons

📑 Multi-Format Benchmark Report Exporters

Export benchmark execution data into multiple formats for sharing with team members or archiving:

Interactive Standalone HTML Report: Fully self-contained HTML file containing embedded interactive metric charts.
Executive PDF Report: Crisp summary report tailored for architecture reviews and executive summaries.
Raw Telemetry JSON: Machine-readable JSON snapshot ideal for CI/CD pipeline assertions.
CSV Metrics Spreadsheet: Raw time-series tabular data for custom analysis in Excel or Grafana.

🛠️ REST API & WebSockets Reference

Automate test executions and telemetry extraction via LoadForge's local REST API:

Method	Endpoint	Description
GET	`/api/configs`	Returns list of all saved test configurations.
POST	`/api/configs`	Create or update a test configuration.
POST	`/api/tests/start`	Starts a load test execution run asynchronously.
POST	`/api/tests/stop`	Stops the currently executing load test run.
GET	`/api/runs`	Returns full historical test execution run history.
POST	`/api/compare`	Compares two test execution runs side-by-side.
WS	`/ws`	WebSocket endpoint broadcasting live telemetry snapshots.

🛡️ Security & Secret Sanitization Policy

⚠️ Authorized Load Testing Disclaimer

Only load test applications, APIs, and servers that you own or have explicit written permission to test. Unauthorized load testing may violate terms of service and network safety policies.

Automatic Secret Payload Masking

LoadForge automatically redacts sensitive authentication payloads, Bearer tokens, API keys, and passwords in reports and database exports by replacing them with [MASKED_SECRET].