Skip to content

PerfShop — Technical documentation

PerfShop is a pedagogical chaos engineering platform that materializes, on a realistic e-commerce application, every type of anomaly that a testing and performance professional encounters during their career. This documentation is the technical bible of reference for understanding the architecture, the APIs, the available chaos families, the metrics and the complete ecosystem.

This documentation is not a hands-on lab manual. The exercises are sold separately with the commercial license and hosted on a dedicated portal. This reference covers the platform itself: its code, its components, its interfaces, its design choices.

It is intended for instructors who run training sessions, for students who want to understand what happens under the hood, for curious developers exploring a modern observability ecosystem, and for QA teams looking for a shared training ground. See Audience for the detailed target groups.

The ecosystem at a glance

flowchart TB
  subgraph Users[Users]
    Prof[👨‍🏫 Instructor]
    Student[🎓 Students]
    Dev[👨‍💻 Developers]
  end

  subgraph Entry[Entry point]
    Welcome[🏠 Welcome page<br/>service directory]
  end

  subgraph Apps[Applications]
    Shop[🛒 Shop React<br/>e-commerce frontend]
    ChaosAdmin[⚡ chaos-admin<br/>instructor panel + student page]
    MonitoringHTML[📊 HTML monitoring<br/>real-time dashboard]
    ScriptsUI[📜 Scripts UI]
    JMeterUI[⚡ JMeter UI]
    Docs[📚 MkDocs<br/>this documentation]
  end

  subgraph Backend[Backend]
    SpringBoot[☕ Spring Boot 3.2<br/>+ Java 21]
    MySQL[(🗄️ MySQL 8)]
  end

  subgraph Obs[Observability]
    Prometheus[Prometheus]
    Grafana[Grafana]
    Loki[Loki]
    Tempo[Tempo]
    Pyroscope[Pyroscope]
    OpenSearch[OpenSearch]
  end

  subgraph QA[QA stack]
    SquashTM[Squash TM]
    Selenium[Selenium Grid]
    TestRunner[Test Runner<br/>Robot + pytest]
    Forgejo[Forgejo Git]
  end

  Users --> Welcome
  Welcome --> Shop
  Welcome --> ChaosAdmin
  Welcome --> MonitoringHTML
  Welcome --> Docs

  Shop --> SpringBoot
  ChaosAdmin --> SpringBoot
  MonitoringHTML --> SpringBoot
  ScriptsUI --> SpringBoot
  JMeterUI --> SpringBoot

  SpringBoot --> MySQL
  SpringBoot -.metrics.-> Prometheus
  SpringBoot -.logs.-> Loki
  SpringBoot -.traces.-> Tempo
  SpringBoot -.profiles.-> Pyroscope
  SpringBoot -.logs.-> OpenSearch

  Prometheus --> Grafana
  Loki --> Grafana
  Tempo --> Grafana
  Pyroscope --> Grafana

  QA --> SpringBoot

PerfShop is a complete ecosystem: Spring Boot 3.2 + Java 21 backend, React 18 + Vite frontend, MySQL 8 database, Prometheus/Grafana/Loki/Tempo/Pyroscope/OpenSearch observability, Selenium/Squash TM/JMeter/polyglot test-runner QA stack, self-hosted Forgejo Git. A single docker compose up starts everything.

The thirteen sections of this documentation

🏁 Introduction

The "why" of PerfShop. This section explains the pedagogical philosophy, the target audiences, the licensing terms, and provides a complete glossary of the vocabulary used throughout the rest of the documentation.

🏗️ Architecture

The technical "how". System overview, technical stack, deployment topology, data schema, authentication flow, multi-session pedagogical management, Docker composition, network and domains.

👁️ Observability

The diagnostic backbone of PerfShop. Prometheus metrics, Grafana dashboards, Loki and Promtail logs, Tempo traces, Pyroscope profiles, alternative OpenSearch logs, and simplified HTML dashboard.

🧪 QA stack

Test management and execution tools integrated into the platform: Squash TM for test case management, Squash Orchestrator for automated execution, Selenium Grid, a polyglot test runner Robot Framework + pytest, JMeter and its web launcher, Scripts UI for online editing, Forgejo as a self-hosted Git server.

⚡ Chaos Engineering

The pedagogical heart of PerfShop. Seven chaos families that can be activated on demand: backend Performance, 20 pre-wired weather scenarios, Functional Chaos (Java exceptions), Business Chaos (16 silent anomalies), Security Chaos (12 OWASP flaws), Scripting Chaos (rolling HMAC tokens), Frontend Chaos (CPU burn, memory leak, DOM flood), and exhaustive reference of the exposed Prometheus metrics.

🎓 Pedagogical journey

The escape-room subsystem of PerfShop. Concept and architecture, five levels BAC1 to BAC5, enigma system, dynamic agent code, star system, hints and progression, standalone success page, final themes.

🔌 API reference

Exhaustive documentation of the REST endpoints exposed by the Spring Boot backend: catalog, cart, orders, user profile, country reference data, administration, vulnerable admin portal, chaos-admin, student chaos, student pedagogical, license.

🖥️ User interfaces

Detailed description of every user interface: React e-commerce frontend, student chaos page (6 tabs), HTML student monitoring, instructor chaos-admin panel, vulnerable admin portal (S10-S12 surface), welcome landing page.

🔒 Security and license

The protection and access-control mechanisms: RSA-PSS 2048 license system with hash integrity, admin authentication (sessions + X-Admin-Token), freemium rules and Master levels.

🛠️ Local development

How to fetch the code, start the stack, iterate on the backend or frontend, and contribute through Forgejo.

🌍 Internationalization

Global FR/EN strategy (and five target languages), backend, frontend, pedagogical enigmas and ancillary tools dictionaries. A single environment variable — PERFSHOP_LANG — propagated across the whole stack.

📖 Guides

Practical use-case-oriented guides: quick start, student guide, custom JMeter script creation, hackathon and training scenarios, Squash TM and Squash Orchestrator setup, Robot Framework, Forgejo, Scripts UI guides, and license activation.

📎 Appendices

Exhaustive references useful at any moment: environment variables, full database schema, and technical FAQ.

License

PerfShop is published under a dual license:

  • AGPL-3.0-or-later for open source use — free use, modification and redistribution provided that modifications are published when the instance is exposed on a network
  • Commercial license for use cases that cannot satisfy the AGPL obligations — training sold to third parties, integration into a proprietary product, access to the turnkey lab library

See License (summary) and License system (technical) for details.

Contact