# ewertonalex/performance-tester architecture

> Architecture diagram of the GitHub repository ewertonalex/performance-tester, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ewertonalex/performance-tester
- Repository: https://github.com/ewertonalex/performance-tester

## Overview

##### Main Components
- Frontend Application: Built with Next.js (using TypeScript, TailwindCSS, and Chart.js). This lives under the “src” folder (e.g., src/app/, src/components/) and is responsible for presenting the user interface, showing dashboards/charts, and handling user interactions (including performance test configuration and results display).
- Backend Server: Located in the “server” folder. It includes:
- The main index.js which likely bootstraps the application.
- Master components (master.ts) that coordinate distributed testing.
- Worker processes (worker.ts) which execute the tests.
- Templates and scripts for generating K6 test scripts (under server/templates and server/scripts).
- API Endpoints: Organized under “src/app/api” with subdirectories for chat, distributed-test, test, and test status. These endpoints handle communication between the frontend and backend.
- K6 Integration: Both in the “server” directory (for scripted load tests and scenario management) and in the generated K6 scripts (referenced via server/k6.ts). K6 is used to execute the performance tests and collect metrics.
- Docker & Deployment: The root-level Dockerfile and docker-compose.yml are used to containerize and deploy the application, separating services into containers (app, server, and multiple worker containers).

##### Relationships and Interactions
- User Interaction Flow: The user interacts with the frontend UI to configure tests and receive results. These requests are sent via API routes to the backend server.
- API Communication: The frontend’s API endpoints (e.g., /api/distributed-test, /api/test) pass test parameters to the backend which then triggers the corresponding K6 scripts.
- Master-Worker Coordination: The backend master process (in server/master.ts) parses test configurations, generates the appropriate K6 scripts using templates, and disseminates the load among multiple worker nodes. Workers (started with server/worker.ts) run the tests and send back results.
- Metrics & Results Aggregation: Performance metrics from K6 tests are then aggregated and served back to the frontend for visualization (using Chart.js) and possibly PDF generation.
- External Integrations: The chat assistant (leveraging Google Gemini AI) is integrated at the frontend level for user guidance and troubleshooting.

##### Architectural Patterns and Design Principles
- Full-Stack Separation: Clear separation between the frontend (Next.js, React components) and backend (Node.js/Express-style server with master/worker distribution).
- Microservice and Containerization: Using Docker and docker-compose to separate concerns (individual containers for app, server, and workers) and ease scalability.
- Distributed Testing Pattern: Master–Worker architecture where a master component coordinates test execution over multiple worker nodes.
- API-Driven Communication: RESTful endpoints and WebSocket connections for real-time updates between different parts of the system.
- Template-Driven Script Generation: The use of Handlebars (.hbs templates in the server/templates directory) to dynamically generate K6 test scripts based on user inputs.

##### Relevant Technologies and Frameworks
- Frontend: Next.js 14, TailwindCSS, TypeScript, Chart.js
- Backend: Node.js, Express.js (for the test distribution server), K6 (for load testing), Handlebars for templating
- Containerization: Docker, Docker Compose
- External Services: Google Gemini AI for chat assistance

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    U["User"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        F["Frontend (Next.js, React & TailwindCSS)"]:::frontend
        C["Chat Assistant (Google Gemini AI)"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        A["API Endpoints (RESTful)"]:::api
    end

    %% Backend Layer
    subgraph "Backend Layer"
        B["Backend API Server (Node.js/Express)"]:::backend
        M["Master Coordinator (Distributed Test Manager)"]:::backend
        W["Worker Nodes (K6 Test Executors)"]:::backend
        K["K6 Integration (Load Testing Engine)"]:::integration
        T["Template Generation (Handlebars Templates)"]:::integration
        S["Test Scripts Support"]:::integration
    end

    %% Deployment
    subgraph "Deployment"
        D1["Dockerfile"]:::docker
        D2["docker-compose.yml"]:::docker
    end

    %% Data Flow
    U --> F
    F --> C
    F --> A
    A --> B
    B --> M
    M --> T
    T --> K
    K --> W
    W --> M
    M --> B
    B --> A
    A --> F

    %% Deployment connections (containerization)
    D1 --- F
    D1 --- B
    D1 --- W
    D2 --- F
    D2 --- B
    D2 --- W

    %% Styles
    classDef frontend fill:#B3E5FC,stroke:#039BE5,stroke-width:2px;
    classDef api fill:#FFE082,stroke:#FF8F00,stroke-width:2px;
    classDef backend fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef integration fill:#F8BBD0,stroke:#C2185B,stroke-width:2px;
    classDef docker fill:#D1C4E9,stroke:#5E35B1,stroke-width:2px;
    classDef external fill:#FFCDD2,stroke:#E53935,stroke-width:2px;

    %% Click Events
    click F "https://github.com/ewertonalex/performance-tester/tree/main/src/app/"
    click A "https://github.com/ewertonalex/performance-tester/tree/main/src/app/api/"
    click B "https://github.com/ewertonalex/performance-tester/tree/main/server/"
    click M "https://github.com/ewertonalex/performance-tester/blob/main/server/master.ts"
    click W "https://github.com/ewertonalex/performance-tester/blob/main/server/worker.ts"
    click K "https://github.com/ewertonalex/performance-tester/blob/main/server/k6.ts"
    click T "https://github.com/ewertonalex/performance-tester/tree/main/server/templates/"
    click S "https://github.com/ewertonalex/performance-tester/tree/main/server/scripts/"
    click D1 "https://github.com/ewertonalex/performance-tester/tree/main/Dockerfile"
    click D2 "https://github.com/ewertonalex/performance-tester/blob/main/docker-compose.yml"
    click C "https://github.com/ewertonalex/performance-tester/blob/main/src/app/components/ChatBot.tsx"
```
