# sarathk06/resilient-integration-testing architecture

> Architecture diagram of the GitHub repository sarathk06/resilient-integration-testing, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sarathk06/resilient-integration-testing
- Repository: https://github.com/sarathk06/resilient-integration-testing

## Overview

#### Purpose and entry points
This is a NestJS/TypeORM sample backend whose main product is a reliable API integration-test architecture: Playwright drives real HTTP requests against a per-run MySQL Docker container. Runtime entry points are `src/main.ts` for the application and Playwright global setup for test orchestration. A separate static presentation is served from `demo/`.

#### Application composition
The Nest root module configures dependency wiring and TypeORM persistence in `src/app.module.ts`. The user domain is intentionally small but exercises database semantics:
- Entity/schema and unique-email constraint: `src/user.entity.ts`
- HTTP resource boundary (`POST`, `GET`, `DELETE /users`): `src/users.controller.ts`
- Persistence operations and database-error-to-HTTP mapping: `src/users.service.ts`

#### Database boundary
TypeORM is the application’s ORM boundary; MySQL is the actual persistence engine rather than an in-memory substitute. The `User` entity drives synchronized test schema creation, including auto-increment IDs and unique email enforcement. Duplicate-key behavior crosses from MySQL/TypeORM into service-level conflict handling, then controller HTTP responses.

#### Disposable integration environment
The test lifecycle is owned outside the app:
- `tests/global-setup.ts` creates a MySQL 8 Testcontainers instance on a dynamic port, initializes Nest with that connection, and exposes the running server to tests.
- `tests/global-teardown.ts` closes the Nest server and destroys the container.

This creates isolated database and server state per run, avoiding shared staging resources or local MySQL dependencies.

#### API test execution flow
Playwright is the client-side test runner and communicates over actual network HTTP to the booted Nest process. Integration specs validate end-to-end transitions through controller, service, TypeORM, and MySQL:
- `tests/integration/user-create.spec.ts`
- `tests/integration/user-duplicate.spec.ts`
- `tests/integration/user-delete.spec.ts`

The essential flow is: provision container → synchronize schema/bootstrap Nest → issue HTTP requests → assert responses and persisted state → stop server/container.

#### Alternate external-service tests
A separate live-test mode targets the ReqRes.in public API, independent of Docker and the local Nest application:
- `tests/live/live-website-api.spec.ts`
- `tests/live/live-browser-ui.spec.ts`
- `playwright.live.config.ts`

This is a distinct external-network validation path, not part of the disposable MySQL environment.

#### Delivery and demonstration surfaces
GitHub Actions executes the Docker-backed integration workflow on hosted runners with Docker available: `.github/workflows/integration-tests.yml`. The project also includes a standalone browser-based presentation/demo, separate from backend runtime: `demo/index.html`, `demo/app.js`, and `demo/serve.js`.

Main entry points: [`src/app.module.ts`](https://github.com/sarathk06/resilient-integration-testing/blob/main/src/app.module.ts) (Root module), [`src/main.ts`](https://github.com/sarathk06/resilient-integration-testing/blob/main/src/main.ts) (Application bootstrap), [`src/users.controller.ts`](https://github.com/sarathk06/resilient-integration-testing/blob/main/src/users.controller.ts) (Users HTTP resource), [`src/users.service.ts`](https://github.com/sarathk06/resilient-integration-testing/blob/main/src/users.service.ts) (Users service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Nest backend"]
  node_main["Application bootstrap<br/>NestJS entry point<br/>[main.ts]"]
  node_app_module["Root module<br/>NestJS module<br/>[app.module.ts]"]
  node_users_controller["Users HTTP resource<br/>REST controller"]
  node_users_service["Users service<br/>domain service<br/>[users.service.ts]"]
  node_user_entity["User schema<br/>TypeORM entity<br/>[user.entity.ts]"]
  node_typeorm{{"TypeORM<br/>ORM boundary"}}
end

subgraph group_integration["Disposable integration tests"]
  node_mysql[("MySQL 8<br/>persistence engine")]
  node_global_setup["Global setup<br/>Playwright lifecycle<br/>[global-setup.ts]"]
  node_playwright{{"Playwright runner<br/>HTTP test client"}}
  node_create_spec["Create-user spec<br/>integration spec"]
  node_duplicate_spec["Duplicate-user spec<br/>integration spec"]
  node_delete_spec["Delete-user spec<br/>integration spec"]
  node_global_teardown["Global teardown<br/>Playwright lifecycle<br/>[global-teardown.ts]"]
end

subgraph group_live["External live tests"]
  node_live_config["Live-test config<br/>Playwright configuration"]
  node_live_api_spec["ReqRes API spec<br/>live integration spec"]
  node_live_ui_spec["ReqRes browser UI spec<br/>live browser spec"]
  node_reqres{{"ReqRes.in<br/>public external API"}}
end

subgraph group_delivery["Delivery and demo"]
  node_github_actions["Integration workflow<br/>GitHub Actions workflow"]
  node_demo_server["Demo server<br/>static presentation server<br/>[serve.js]"]
  node_demo_ui["Standalone demo<br/>browser presentation<br/>[index.html]"]
  node_demo_app["Demo behavior<br/>browser script<br/>[app.js]"]
end

node_main -->|"boots"| node_app_module
node_app_module -->|"wires"| node_users_controller
node_app_module -->|"provides"| node_users_service
node_app_module -->|"configures"| node_typeorm
node_users_controller -->|"delegates"| node_users_service
node_users_service -->|"persists through"| node_typeorm
node_typeorm -->|"maps"| node_user_entity
node_typeorm -->|"connects to"| node_mysql
node_global_setup -->|"provisions container"| node_mysql
node_global_setup -->|"initializes server"| node_main
node_playwright -->|"runs"| node_create_spec
node_playwright -->|"runs"| node_duplicate_spec
node_playwright -->|"runs"| node_delete_spec
node_playwright -->|"real HTTP"| node_users_controller
node_global_teardown -.->|"closes"| node_main
node_global_teardown -.->|"destroys container"| node_mysql
node_live_config -->|"selects"| node_live_api_spec
node_live_config -->|"selects"| node_live_ui_spec
node_live_api_spec -->|"calls"| node_reqres
node_live_ui_spec -->|"drives"| node_reqres
node_github_actions -->|"executes"| node_playwright
node_demo_server -->|"serves"| node_demo_ui
node_demo_ui -->|"loads"| node_demo_app

click node_main "https://github.com/sarathk06/resilient-integration-testing/blob/main/src/main.ts"
click node_app_module "https://github.com/sarathk06/resilient-integration-testing/blob/main/src/app.module.ts"
click node_users_controller "https://github.com/sarathk06/resilient-integration-testing/blob/main/src/users.controller.ts"
click node_users_service "https://github.com/sarathk06/resilient-integration-testing/blob/main/src/users.service.ts"
click node_user_entity "https://github.com/sarathk06/resilient-integration-testing/blob/main/src/user.entity.ts"
click node_global_setup "https://github.com/sarathk06/resilient-integration-testing/blob/main/tests/global-setup.ts"
click node_create_spec "https://github.com/sarathk06/resilient-integration-testing/blob/main/tests/integration/user-create.spec.ts"
click node_duplicate_spec "https://github.com/sarathk06/resilient-integration-testing/blob/main/tests/integration/user-duplicate.spec.ts"
click node_delete_spec "https://github.com/sarathk06/resilient-integration-testing/blob/main/tests/integration/user-delete.spec.ts"
click node_global_teardown "https://github.com/sarathk06/resilient-integration-testing/blob/main/tests/global-teardown.ts"
click node_live_config "https://github.com/sarathk06/resilient-integration-testing/blob/main/playwright.live.config.ts"
click node_live_api_spec "https://github.com/sarathk06/resilient-integration-testing/blob/main/tests/live/live-website-api.spec.ts"
click node_live_ui_spec "https://github.com/sarathk06/resilient-integration-testing/blob/main/tests/live/live-browser-ui.spec.ts"
click node_github_actions "https://github.com/sarathk06/resilient-integration-testing/blob/main/.github/workflows/integration-tests.yml"
click node_demo_server "https://github.com/sarathk06/resilient-integration-testing/blob/main/demo/serve.js"
click node_demo_ui "https://github.com/sarathk06/resilient-integration-testing/blob/main/demo/index.html"
click node_demo_app "https://github.com/sarathk06/resilient-integration-testing/blob/main/demo/app.js"

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_main,node_app_module,node_users_controller,node_users_service,node_user_entity,node_typeorm toneBlue
class node_mysql,node_global_setup,node_playwright,node_create_spec,node_duplicate_spec,node_delete_spec,node_global_teardown toneAmber
class node_live_config,node_live_api_spec,node_live_ui_spec,node_reqres toneMint
class node_github_actions,node_demo_server,node_demo_ui,node_demo_app toneRose
```

## Components

### Nest backend

- [Application bootstrap](https://github.com/sarathk06/resilient-integration-testing/blob/main/src/main.ts): NestJS entry point · `src/main.ts`
- [Root module](https://github.com/sarathk06/resilient-integration-testing/blob/main/src/app.module.ts): NestJS module · Wires users and TypeORM persistence. · `src/app.module.ts`
- [Users HTTP resource](https://github.com/sarathk06/resilient-integration-testing/blob/main/src/users.controller.ts): REST controller · Handles POST, GET, and DELETE /users. · `src/users.controller.ts`
- [Users service](https://github.com/sarathk06/resilient-integration-testing/blob/main/src/users.service.ts): domain service · Maps persistence errors to HTTP behavior. · `src/users.service.ts`
- [User schema](https://github.com/sarathk06/resilient-integration-testing/blob/main/src/user.entity.ts): TypeORM entity · Defines generated IDs and unique email. · `src/user.entity.ts`
- **TypeORM**: ORM boundary

### Disposable integration tests

- **MySQL 8**: persistence engine · Real database used for synchronized test schema.
- [Global setup](https://github.com/sarathk06/resilient-integration-testing/blob/main/tests/global-setup.ts): Playwright lifecycle · Starts container, initializes Nest, and exposes the server. · `tests/global-setup.ts`
- **Playwright runner**: HTTP test client
- [Create-user spec](https://github.com/sarathk06/resilient-integration-testing/blob/main/tests/integration/user-create.spec.ts): integration spec · `tests/integration/user-create.spec.ts`
- [Duplicate-user spec](https://github.com/sarathk06/resilient-integration-testing/blob/main/tests/integration/user-duplicate.spec.ts): integration spec · Validates unique-email conflict behavior. · `tests/integration/user-duplicate.spec.ts`
- [Delete-user spec](https://github.com/sarathk06/resilient-integration-testing/blob/main/tests/integration/user-delete.spec.ts): integration spec · `tests/integration/user-delete.spec.ts`
- [Global teardown](https://github.com/sarathk06/resilient-integration-testing/blob/main/tests/global-teardown.ts): Playwright lifecycle · Stops Nest and destroys the container. · `tests/global-teardown.ts`

### External live tests

- [Live-test config](https://github.com/sarathk06/resilient-integration-testing/blob/main/playwright.live.config.ts): Playwright configuration · `playwright.live.config.ts`
- [ReqRes API spec](https://github.com/sarathk06/resilient-integration-testing/blob/main/tests/live/live-website-api.spec.ts): live integration spec · `tests/live/live-website-api.spec.ts`
- [ReqRes browser UI spec](https://github.com/sarathk06/resilient-integration-testing/blob/main/tests/live/live-browser-ui.spec.ts): live browser spec · `tests/live/live-browser-ui.spec.ts`
- **ReqRes.in**: public external API

### Delivery and demo

- [Integration workflow](https://github.com/sarathk06/resilient-integration-testing/blob/main/.github/workflows/integration-tests.yml): GitHub Actions workflow · Runs Docker-backed integration tests on hosted runners. · `.github/workflows/integration-tests.yml`
- [Demo server](https://github.com/sarathk06/resilient-integration-testing/blob/main/demo/serve.js): static presentation server · `demo/serve.js`
- [Standalone demo](https://github.com/sarathk06/resilient-integration-testing/blob/main/demo/index.html): browser presentation · `demo/index.html`
- [Demo behavior](https://github.com/sarathk06/resilient-integration-testing/blob/main/demo/app.js): browser script · `demo/app.js`

## Connections

- Application bootstrap → Root module: boots
- Root module → Users HTTP resource: wires
- Root module → Users service: provides
- Root module → TypeORM: configures
- Users HTTP resource → Users service: delegates
- Users service → TypeORM: persists through
- TypeORM → User schema: maps
- TypeORM → MySQL 8: connects to
- Global setup → MySQL 8: provisions container
- Global setup → Application bootstrap: initializes server
- Playwright runner → Create-user spec: runs
- Playwright runner → Duplicate-user spec: runs
- Playwright runner → Delete-user spec: runs
- Playwright runner → Users HTTP resource: real HTTP
- Global teardown → Application bootstrap: closes
- Global teardown → MySQL 8: destroys container
- Live-test config → ReqRes API spec: selects
- Live-test config → ReqRes browser UI spec: selects
- ReqRes API spec → ReqRes.in: calls
- ReqRes browser UI spec → ReqRes.in: drives
- Integration workflow → Playwright runner: executes
- Demo server → Standalone demo: serves
- Standalone demo → Demo behavior: loads
