1. Executive Overview & Vision
2. Global Architecture & End-to-End Topology
3. Organization Repositories Directory
4. The System Under Test (SUT)
5. Quality Engineering & Automation Platforms
   • Centralized Playwright E2E & API Suites
   • Centralized Grafana k6 Performance Testing
   • Test Management & Linear Webhook Sync (Squash TM)
   • AI-Driven Defect Analytics & Reporting (ReportPortal)
6. ChatOps & Developer Experience (Discord Bot)
7. Cloud Infrastructure, Staging VM & Ingress
8. Master Public Routing Directory
9. Security, Networking & Secrets Management
10. Local Development & Contribution Workflow

Modern engineering organizations operating distributed microservices frequently suffer from QA fragmentation: tests are siloed inside application repositories, performance benchmarks are run inconsistently, test case management is disconnected from sprint tickets, and results are scattered across individual CI runner logs.

Omni-Suites solves this by establishing a centralized, enterprise-grade Quality Engineering ecosystem:

• Decoupled Automation Platforms: Centralized repositories for E2E/API testing (test-suites) and load/performance testing (perf-suites) that run against ephemeral, staging, or production environments without modifying application source code.
• Bi-Directional Requirement Traceability: Issues in Linear labeled with ready-for-tc automatically synchronize with Squash TM via omni-integration, auto-generating structured test cases and preserving test coverage history.
• Unified Observability & AI Categorization: All browser and API test executions automatically publish metrics, error logs, and failure screenshots directly to a self-hosted ReportPortal v5.15 cluster with automated defect classification.
• Interactive ChatOps: Team members can execute on-demand regression suites (/run-tests) or stress benchmarks (/run-perf) directly from Discord, streaming real-time embeds and artifact links back into communication channels.

flowchart TD
    subgraph Clients ["Public Ingress & Users"]
        WebUser["End User / Browser"]
        QAUser["QA Engineer / Tester"]
        LinearWH["Linear Webhooks"]
        DiscordUser["Discord ChatOps (/run-tests, /run-perf)"]
    end

    subgraph Edge ["Central Edge Reverse Proxy (infra/traefik)"]
        TraefikProxy["Traefik v3.7 Edge Proxy<br/>Port 80 (HTTP) -> 443 (HTTPS)<br/>Auto Let's Encrypt TLS"]
    end

    WebUser -->|frontend-svc.test-suites-poc.work.gd| TraefikProxy
    QAUser -->|squash-tcms.test-suites-poc.work.gd/squash| TraefikProxy
    QAUser -->|report-portal.test-suites-poc.work.gd| TraefikProxy
    LinearWH -->|hooks.test-suites-poc.work.gd/webhooks/linear| TraefikProxy
    DiscordUser -->|hooks.test-suites-poc.work.gd/api/discord/interactions| TraefikProxy

    subgraph AppsStack ["Core Application Stack (infra/apps)"]
        subgraph FrontEnds ["UI Layer"]
            OmniClient["omni-client (:80)<br/>React 18 + Vite SPA"]
        end

        subgraph Backends ["Microservices Layer"]
            OrderSvc["order-service (:3000)<br/>NestJS + Prisma"]
            InvSvc["inventory-service (:3001)<br/>NestJS + Prisma"]
            NotifSvc["notification-service (:3002)<br/>NestJS + Prisma"]
            IntegrationSvc["omni-integration (:3003)<br/>NestJS Discord & Linear Webhook"]
        end

        subgraph DBs ["Polyglot Persistence Layer (apps-internal network)"]
            PostgresApps[("postgres-db (:5432)<br/>order_db & omni_integration_db")]
            MySQLApps[("mysql-db (:3306)<br/>inventory_db")]
            MongoApps[("mongo-db (:27017)<br/>notification_db (Replica Set rs0)")]
        end
    end

    subgraph QAStack ["Quality & Test Management Infrastructure"]
        subgraph SquashStack ["infra/squash-tm"]
            SquashApp["squash-tm (:8080/squash)<br/>Test Management System"]
            SquashDB[("squash-tm-pg (:5432)<br/>PostgreSQL 15")]
        end

        subgraph RPStack ["infra/report-portal"]
            RPGateway["report-portal-gateway (:8080)<br/>Internal Traefik Gateway"]
            RPServices["ReportPortal Microservices<br/>(API, UAT, UI, Jobs)"]
            RPDB[("postgres (:5432)<br/>PostgreSQL 18.4")]
            RPRabbitMQ[("rabbitmq (:5672)<br/>RabbitMQ 4.3")]
            RPOpenSearch[("opensearch (:9200)<br/>OpenSearch 3.8")]
            RPAnalyzer["service-auto-analyzer (:5001)<br/>AI Defect Clustering"]
        end
    end

    subgraph TestExecution ["Test Execution Engines (GitHub Actions Runners)"]
        PlaywrightEngine["Playwright Test Engine (test-suites)<br/>UI & API Tests"]
        K6Engine["Grafana k6 Engine (perf-suites)<br/>Load, Stress, Spike Tests"]
    end

    TraefikProxy --> OmniClient
    TraefikProxy --> OrderSvc
    TraefikProxy --> InvSvc
    TraefikProxy --> NotifSvc
    TraefikProxy --> IntegrationSvc
    TraefikProxy --> SquashApp
    TraefikProxy --> RPGateway

    OmniClient -.->|Browser API Requests| TraefikProxy
    OrderSvc -->|HTTP RPC :3001| InvSvc
    OrderSvc -->|HTTP RPC :3002| NotifSvc
    OrderSvc --> PostgresApps
    InvSvc --> MySQLApps
    NotifSvc --> MongoApps
    IntegrationSvc --> PostgresApps

    IntegrationSvc -->|REST API :8080/squash| SquashApp
    IntegrationSvc -->|Dispatch Workflow| PlaywrightEngine
    IntegrationSvc -->|Dispatch Workflow| K6Engine

    SquashApp --> SquashDB
    RPGateway --> RPServices
    RPServices --> RPDB
    RPServices --> RPRabbitMQ
    RPServices --> RPOpenSearch
    RPAnalyzer --> RPRabbitMQ
    RPAnalyzer --> RPOpenSearch

    PlaywrightEngine -->|Run Tests Against Services| TraefikProxy
    PlaywrightEngine -->|Report Results & Traces| RPServices
    PlaywrightEngine -->|Sync Test Runs| SquashApp
    K6Engine -->|Load & Stress Ingestion| TraefikProxy

The business platform simulates a multi-tier e-commerce order workflow:

[User clicks Buy on omni-client]
          │
          ▼
    [POST /orders] ──────────────────────────┐
          │ (HTTP RPC :3001)                 │
          ▼                                  ▼
[POST /inventory/deduct]               [POST /notifications] (HTTP RPC :3002)
          │                                  │
          ▼                                  ▼
   (Deducts stock in MySQL)          (Logs event in MongoDB replica set)
          │                                  │
          └────────────────┬─────────────────┘
                           ▼
             (Persists Order in PostgreSQL)
                           │
                           ▼
          [Order Confirmation Displayed in UI]

• Order Service (:3000): POST /orders, GET /orders, GET /orders/:id, GET /health
• Inventory Service (:3001): GET /inventory, POST /inventory/deduct, GET /health
• Notification Service (:3002): GET /notifications, POST /notifications, GET /health
• Omni Integration (:3003): POST /webhooks/linear, POST /api/discord/interactions, GET /health

• Technology: Playwright Test, TypeScript, Page Object Model (POM), custom domain fixtures.
• Scope: Multi-browser E2E testing (Chromium, Firefox, WebKit), end-to-end purchasing flows, and standalone REST API validation against microservice contracts.
• Execution Options: Triggered via GitHub Actions workflow_dispatch, scheduled nightly runs, or Discord ChatOps.
• Direct Integration: Native reporting into ReportPortal using @reportportal/agent-js-playwright and test status syncing into Squash TM.

• Technology: Grafana k6, TypeScript, Webpack bundling, Domain-Driven Design layout (src/core, src/modules, src/journeys).
• Workload Profiles:
  • smoke: Quick verification of performance baseline.
  • load: Sustained target VU throughput testing.
  • stress: Ramp-up beyond capacity to detect degradation breakpoints.
  • spike: Instant surge in concurrent traffic to test elastic recovery.
• Quality Gates: Strict SLA thresholds evaluated at runtime (e.g. p(95) < 500ms, errors < 1%).
• Artifact Reporting: Automated HTML performance dashboards, raw metric summaries (summary.json), and GitHub Actions job summaries.

• Technology: Squash TM (Java Spring Boot), PostgreSQL 15.
• Automated Sync: When developers or PMs label a ticket in Linear with ready-for-tc:
  1. Linear fires a webhook to https://hooks.test-suites-poc.work.gd/webhooks/linear.
  2. omni-integration validates the secret and parses preconditions, steps, and expected results.
  3. A new test case is created in Squash TM under project omni-suites.
  4. Mapping IDs are idempotently recorded in omni_integration_db.

• Technology: ReportPortal v5.15 (12 microservices, PostgreSQL 18, RabbitMQ, OpenSearch, Python ML auto-analyzer).
• Capabilities:
  • Real-time test log streaming and video/screenshot artifact ingestion.
  • Flaky test identification and execution trends across releases.
  • Machine learning defect triage: automatically clusters failures into Product Bug, Automation Bug, System Issue, or To Investigate.

Omni-Suites embeds QA triggers directly into developer team workflows through Discord Slash Commands:

Upon completion, the bot posts rich status embeds to the #test-releases channel containing pass/fail metrics, duration, and direct links to GitHub Actions summaries and ReportPortal launches.

The staging cloud environment runs on a dedicated virtual machine (/opt/omni-infra) managed with modular Docker Compose stacks:

/opt/omni-infra/
├── traefik/         # Ingress reverse proxy, TLS termination, edge network
├── apps/            # Microservices, omni-client, databases (Postgres, MySQL, Mongo)
├── squash-tm/       # Squash TM application & dedicated PostgreSQL database
└── report-portal/   # ReportPortal v5.15 distributed analytics cluster

• edge (External Bridge): Created by Traefik. Connects public-facing HTTP backends (omni-client, order-service, inventory-service, notification-service, omni-integration, squash-tm, report-portal-gateway).
• apps-internal (Private): Completely isolates databases (postgres-db, mysql-db, mongo-db) and direct inter-service RPC calls.
• squash-internal (Private): Dedicated link between squash-tm and its PostgreSQL instance.
• reportportal (Private): Internal mesh between ReportPortal microservices, PostgreSQL 18, RabbitMQ, and OpenSearch.

All services are publicly resolved via HTTPS under the test-suites-poc.work.gd domain:

1. Firewall & Ingress Surface:
   • Only ports 22 (SSH), 80 (HTTP challenge / redirect), and 443 (HTTPS) are exposed on the host VM.
   • Zero Host Database Ports: No database ports (5432, 3306, 27017, 9200, 5672) are published to the host or internet.
2. Automated SSL/TLS:
   • Traefik v3 manages Let's Encrypt certificates using ACME HTTP-01 challenges, storing keys securely in the letsencrypt Docker volume (/letsencrypt/acme.json).
3. Cryptographic Validation:
   • Linear webhooks verify HMAC signatures against LINEAR_WEBHOOK_SECRET.
   • Discord interactions verify cryptographic Ed25519 signatures against DISCORD_PUBLIC_KEY.
4. Environment Isolation:
   • All .env files are strictly excluded from version control via .gitignore.
   • GitHub Actions secrets and variables inject credentials securely into CI/CD runners.

# Clone the central workspace
git clone https://github.com/omni-suites/.github.git omni-suites
cd omni-suites

# Clone individual repositories into app/ and quality suites
git clone https://github.com/omni-suites/omni-client.git app/omni-client
git clone https://github.com/omni-suites/order-service.git app/order-service
git clone https://github.com/omni-suites/inventory-service.git app/inventory-service
git clone https://github.com/omni-suites/notification-service.git app/notification-service
git clone https://github.com/omni-suites/omni-integration.git app/omni-integration
git clone https://github.com/omni-suites/test-suites.git test-suites
git clone https://github.com/omni-suites/perf-suites.git perf-suites
git clone https://github.com/omni-suites/infra.git infra

cd test-suites
cp .env.sample .env
npm install
npx playwright test --project=chromium

cd perf-suites
cp .env.sample .env
npm install
npm run build
npm run test:smoke