# esakkiappan-nambi/k6-performance-portal architecture

> Architecture diagram of the GitHub repository esakkiappan-nambi/k6-performance-portal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/esakkiappan-nambi/k6-performance-portal
- Repository: https://github.com/esakkiappan-nambi/k6-performance-portal

## Overview

#### Purpose and Shape
This is a full-stack load/API testing system. A Python backend accepts test definitions, captures API/authentication activity, generates and runs k6 JavaScript scripts, and persists run artifacts. A React/Vite frontend provides test creation, execution, capture, history, and report views.  
Paths: `Backend/main.py`, `Backend/k6_runner.py`, `Frontend/k6-UI/src/App.jsx`

#### Entry Points and UI Boundary
Backend HTTP API startup and route composition are centered on `Backend/main.py`; automatic-capture routes are separated under `Backend/router/auto_capture.py`. The browser application enters through Vite’s React bootstrap and mounts route/page components from the application shell.  
Paths: `Backend/main.py`, `Frontend/k6-UI/src/main.jsx`, `Frontend/k6-UI/src/App.jsx`

#### Identity and Access Control
Authentication is a backend concern, with credential/auth logic separated from API capture’s authentication handling. The frontend has Login/Register pages and a route guard, establishing a client/server auth boundary before protected testing and report operations.  
Paths: `Backend/auth.py`, `Backend/api_capture/auth_capture.py`, `Frontend/k6-UI/src/pages/ProtectedRoute.jsx`

#### Test Definition and Script Generation
User-authored or captured requests are converted into executable k6 JavaScript and materialized as generated-script files. This is the primary boundary between application-level test configuration and the external k6 runtime. The Create Test and Run Test UI pages likely submit definitions and initiate executions through the frontend API service.  
Paths: `Backend/generated_scripts/Login Test.js`, `Backend/k6_runner.py`, `Frontend/k6-UI/src/pages/CreateTest.jsx`, `Frontend/k6-UI/src/services/api.jsx`

#### Capture and Correlation Pipeline
API capture is decomposed into request capture, authentication capture, and correlation logic, suggesting a pipeline that records browser/API interactions, detects auth material, and associates requests into a reusable test flow. Auto-capture is exposed independently at the router level and represented by a dedicated UI page.  
Paths: `Backend/api_capture/capture.py`, `Backend/api_capture/correlate.py`, `Backend/router/auto_capture.py`, `Frontend/k6-UI/src/pages/AutoCapture.jsx`

#### Execution, Results, and Reporting
`k6_runner.py` is the execution adapter for the k6 CLI/runtime. Run outputs are retained as numbered JSON summaries and PDF/HTML reports in local backend storage; report/history/dashboard pages consume this lifecycle for display and navigation. Report files indicate filesystem-backed artifacts rather than an external object store.  
Paths: `Backend/k6_runner.py`, `Backend/reports/620_summary.json`, `Backend/reports/620_report.pdf`, `Frontend/k6-UI/src/pages/Report.jsx`, `Frontend/k6-UI/src/pages/History.jsx`

#### Persistence and Input Data
Database access, models, and request/response schemas form the backend persistence and API-contract layer. CSV/XLSX upload handling supports data-driven tests; uploaded source files are stored locally and may feed generated k6 scenarios. Environment values are supplied through a backend `.env` file.  
Paths: `Backend/database.py`, `Backend/models.py`, `Backend/schemas.py`, `Backend/csv_handler.py`, `Backend/uploaded_csv/`

Main entry points: [`Backend/main.py`](https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/main.py) (HTTP API), [`Backend/k6_runner.py`](https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/k6_runner.py) (k6 runner), [`Frontend/k6-UI/src/pages/ProtectedRoute.jsx`](https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Frontend/k6-UI/src/pages/ProtectedRoute.jsx) (Route guard), [`Frontend/k6-UI/src/services/api.jsx`](https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Frontend/k6-UI/src/services/api.jsx) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend API"]
  node_api["HTTP API<br/>FastAPI application<br/>[main.py]"]
  node_auth["Authentication<br/>auth service<br/>[auth.py]"]
  node_contracts["Models &amp; schemas<br/>persistence contracts<br/>[models.py]"]
  node_database[("Database access<br/>database layer<br/>[database.py]")]
  node_uploads["Data uploads<br/>CSV/XLSX handler<br/>[csv_handler.py]"]
  node_uploaded_files["Uploaded datasets<br/>local file storage"]
end

subgraph group_capture["Capture pipeline"]
  node_auto_routes["Auto-capture routes<br/>API router<br/>[auto_capture.py]"]
  node_request_capture["Request capture<br/>capture service<br/>[capture.py]"]
  node_auth_capture["Auth capture<br/>capture service<br/>[auth_capture.py]"]
  node_correlation["Flow correlation<br/>correlation service<br/>[correlate.py]"]
end

subgraph group_execution["Test execution"]
  node_runner["k6 runner<br/>execution adapter<br/>[k6_runner.py]"]
  node_scripts["Generated k6 scripts<br/>JavaScript artifacts<br/>[Login Test.js]"]
  node_k6{{"k6 runtime<br/>external CLI runtime"}}
  node_reports["Run artifacts<br/>local report storage<br/>[620_summary.json]"]
end

subgraph group_frontend["React frontend"]
  node_ui_bootstrap["Vite bootstrap<br/>React entry point<br/>[main.jsx]"]
  node_app["Application shell<br/>React routes<br/>[App.jsx]"]
  node_protected_route["Route guard<br/>auth boundary<br/>[ProtectedRoute.jsx]"]
  node_test_ui["Test creation &amp; run<br/>React pages<br/>[CreateTest.jsx]"]
  node_capture_ui["Auto-capture page<br/>React page<br/>[AutoCapture.jsx]"]
  node_history_ui["History &amp; reports<br/>React pages<br/>[Report.jsx]"]
  node_frontend_api["API client<br/>frontend service<br/>[api.jsx]"]
end

node_ui_bootstrap -->|"mounts"| node_app
node_app -->|"routes through"| node_protected_route
node_protected_route -->|"allows"| node_test_ui
node_protected_route -->|"allows"| node_capture_ui
node_protected_route -->|"allows"| node_history_ui
node_test_ui -->|"submits tests"| node_frontend_api
node_capture_ui -->|"controls capture"| node_frontend_api
node_history_ui -->|"loads artifacts"| node_frontend_api
node_frontend_api -->|"HTTP requests"| node_api
node_api -->|"authenticates"| node_auth
node_api -->|"uses"| node_contracts
node_contracts -->|"persists via"| node_database
node_api -->|"accepts datasets"| node_uploads
node_uploads -->|"stores"| node_uploaded_files
node_api -->|"composes"| node_auto_routes
node_auto_routes -->|"captures requests"| node_request_capture
node_auto_routes -->|"captures auth"| node_auth_capture
node_request_capture -->|"supplies events"| node_correlation
node_auth_capture -->|"supplies auth context"| node_correlation
node_correlation -->|"creates test flow"| node_runner
node_api -->|"starts runs"| node_runner
node_uploads -->|"provides test data"| node_runner
node_runner -->|"materializes"| node_scripts
node_runner -->|"invokes"| node_k6
node_k6 -->|"produces results"| node_reports
node_runner -->|"retains artifacts"| node_reports
node_api -->|"serves results"| node_reports

click node_api "https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/main.py"
click node_auth "https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/auth.py"
click node_contracts "https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/models.py"
click node_database "https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/database.py"
click node_uploads "https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/csv_handler.py"
click node_auto_routes "https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/router/auto_capture.py"
click node_request_capture "https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/api_capture/capture.py"
click node_auth_capture "https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/api_capture/auth_capture.py"
click node_correlation "https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/api_capture/correlate.py"
click node_runner "https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/k6_runner.py"
click node_scripts "https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/generated_scripts/Login%20Test.js"
click node_reports "https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/reports/620_summary.json"
click node_ui_bootstrap "https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Frontend/k6-UI/src/main.jsx"
click node_app "https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Frontend/k6-UI/src/App.jsx"
click node_protected_route "https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Frontend/k6-UI/src/pages/ProtectedRoute.jsx"
click node_test_ui "https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Frontend/k6-UI/src/pages/CreateTest.jsx"
click node_capture_ui "https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Frontend/k6-UI/src/pages/AutoCapture.jsx"
click node_history_ui "https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Frontend/k6-UI/src/pages/Report.jsx"
click node_frontend_api "https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Frontend/k6-UI/src/services/api.jsx"

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_api,node_auth,node_contracts,node_database,node_uploads,node_uploaded_files toneBlue
class node_auto_routes,node_request_capture,node_auth_capture,node_correlation toneAmber
class node_runner,node_scripts,node_k6,node_reports toneMint
class node_ui_bootstrap,node_app,node_protected_route,node_test_ui,node_capture_ui,node_history_ui,node_frontend_api toneRose
```

## Components

### Backend API

- [HTTP API](https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/main.py): FastAPI application · Composes backend routes and protected testing APIs. · `Backend/main.py`
- [Authentication](https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/auth.py): auth service · `Backend/auth.py`
- [Models & schemas](https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/models.py): persistence contracts · `Backend/models.py`
- [Database access](https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/database.py): database layer · `Backend/database.py`
- [Data uploads](https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/csv_handler.py): CSV/XLSX handler · Supports data-driven test inputs. · `Backend/csv_handler.py`
- **Uploaded datasets**: local file storage

### Capture pipeline

- [Auto-capture routes](https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/router/auto_capture.py): API router · `Backend/router/auto_capture.py`
- [Request capture](https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/api_capture/capture.py): capture service · `Backend/api_capture/capture.py`
- [Auth capture](https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/api_capture/auth_capture.py): capture service · Extracts authentication material from captured activity. · `Backend/api_capture/auth_capture.py`
- [Flow correlation](https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/api_capture/correlate.py): correlation service · Associates captured requests into reusable flows. · `Backend/api_capture/correlate.py`

### Test execution

- [k6 runner](https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/k6_runner.py): execution adapter · Generates scripts and invokes the k6 runtime. · `Backend/k6_runner.py`
- [Generated k6 scripts](https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/generated_scripts/Login%20Test.js): JavaScript artifacts · `Backend/generated_scripts/Login Test.js`
- **k6 runtime**: external CLI runtime
- [Run artifacts](https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Backend/reports/620_summary.json): local report storage · Stores JSON summaries and PDF/HTML reports. · `Backend/reports/620_summary.json`

### React frontend

- [Vite bootstrap](https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Frontend/k6-UI/src/main.jsx): React entry point · `Frontend/k6-UI/src/main.jsx`
- [Application shell](https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Frontend/k6-UI/src/App.jsx): React routes · `Frontend/k6-UI/src/App.jsx`
- [Route guard](https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Frontend/k6-UI/src/pages/ProtectedRoute.jsx): auth boundary · Protects testing and report views. · `Frontend/k6-UI/src/pages/ProtectedRoute.jsx`
- [Test creation & run](https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Frontend/k6-UI/src/pages/CreateTest.jsx): React pages · `Frontend/k6-UI/src/pages/CreateTest.jsx`
- [Auto-capture page](https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Frontend/k6-UI/src/pages/AutoCapture.jsx): React page · `Frontend/k6-UI/src/pages/AutoCapture.jsx`
- [History & reports](https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Frontend/k6-UI/src/pages/Report.jsx): React pages · `Frontend/k6-UI/src/pages/Report.jsx`
- [API client](https://github.com/esakkiappan-nambi/k6-performance-portal/blob/main/Frontend/k6-UI/src/services/api.jsx): frontend service · `Frontend/k6-UI/src/services/api.jsx`

## Connections

- Vite bootstrap → Application shell: mounts
- Application shell → Route guard: routes through
- Route guard → Test creation & run: allows
- Route guard → Auto-capture page: allows
- Route guard → History & reports: allows
- Test creation & run → API client: submits tests
- Auto-capture page → API client: controls capture
- History & reports → API client: loads artifacts
- API client → HTTP API: HTTP requests
- HTTP API → Authentication: authenticates
- HTTP API → Models & schemas: uses
- Models & schemas → Database access: persists via
- HTTP API → Data uploads: accepts datasets
- Data uploads → Uploaded datasets: stores
- HTTP API → Auto-capture routes: composes
- Auto-capture routes → Request capture: captures requests
- Auto-capture routes → Auth capture: captures auth
- Request capture → Flow correlation: supplies events
- Auth capture → Flow correlation: supplies auth context
- Flow correlation → k6 runner: creates test flow
- HTTP API → k6 runner: starts runs
- Data uploads → k6 runner: provides test data
- k6 runner → Generated k6 scripts: materializes
- k6 runner → k6 runtime: invokes
- k6 runtime → Run artifacts: produces results
- k6 runner → Run artifacts: retains artifacts
- HTTP API → Run artifacts: serves results