# pythagora-io/pythagora architecture

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

- Interactive diagram: https://gitdiagram.com/pythagora-io/pythagora
- Repository: https://github.com/pythagora-io/pythagora

## Overview

Pythagora records server activity and replays it to validate integration tests, including HTTP responses and MongoDB behavior; it also exposes a separate GPT-assisted unit-test generation and expansion workflow. Generated tests can be exported to Jest. The runtime excerpts establish the capture/replay and export relationships shown below. Unit-generation internals and some integrations are only documented or indexed, so uncertain connections are dashed or omitted.

Main entry points: [`src/commands/export.js`](https://github.com/pythagora-io/pythagora/blob/main/src/commands/export.js) (Export orchestration), [`src/Pythagora.js`](https://github.com/pythagora-io/pythagora/blob/main/src/Pythagora.js) (Capture replay engine), [`src/helpers/mongodb.js`](https://github.com/pythagora-io/pythagora/blob/main/src/helpers/mongodb.js) (Mongo replay), [`src/helpers/starting.js`](https://github.com/pythagora-io/pythagora/blob/main/src/helpers/starting.js) (Runtime startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Capture and replay"]
  node_cli["CLI entry<br/>[run.js]"]
  node_startup["Runtime startup<br/>[starting.js]"]
  node_engine["Capture replay engine<br/>[Pythagora.js]"]
  node_middleware["HTTP middleware<br/>[middlewares.js]"]
  node_test_runner["Replay runner"]
  node_http_patch["HTTP patches<br/>[http.js]"]
  node_express_patch["Express patch<br/>[express.js]"]
end

subgraph group_storage["State and integrations"]
  node_mongo_patch["Mongo instrumentation"]
  node_mongo_helpers["Mongo replay<br/>[mongodb.js]"]
  node_mongo_rules["Mongo operation rules<br/>[mongodb.js]"]
  node_redis_interceptor["Redis interceptor<br/>[redis.js]"]
end

subgraph group_unit["Unit test generation"]
  node_unit_generate["Generate unit tests<br/>[unitTests.js]"]
  node_unit_expand["Expand unit tests<br/>[unitTestsExpand.js]"]
  node_unit_api["API configuration<br/>[api.js]"]
  node_unit_gui["CLI interaction<br/>[cmdGUI.js]"]
end

subgraph group_export["Jest export"]
  node_export_cmd["Export orchestration<br/>[export.js]"]
  node_export_helpers["Jest test export<br/>[exports.js]"]
  node_jest_cmd["Run Jest tests<br/>[jest.js]"]
end

subgraph group_shared["Shared support"]
  node_args["Argument config<br/>[getArgs.js]"]
  node_common["Test data utilities<br/>[common.js]"]
  node_logging["Status and diagnostics<br/>[cmdPrint.js]"]
  node_legacy["Legacy conversion<br/>[legacy.js]"]
end

node_developer(("Developer"))
node_app["Express app"]
node_mongo[("MongoDB")]
node_redis[("Redis")]
node_gpt["GPT service"]

node_developer -->|"starts command"| node_cli
node_cli -.->|"starts runtime"| node_startup
node_startup -->|"initializes"| node_engine
node_startup -->|"starts replay"| node_test_runner
node_app -.->|"handles requests"| node_middleware
node_middleware -->|"prepares database"| node_mongo_helpers
node_middleware -->|"sets mode"| node_redis_interceptor
node_engine -->|"cleans database"| node_mongo_helpers
node_engine -->|"replays requests"| node_test_runner
node_engine -->|"initializes"| node_redis_interceptor
node_engine -->|"uses utilities"| node_common
node_mongo_patch -->|"delegates replay"| node_mongo_helpers
node_mongo_patch -->|"reads operation rules"| node_mongo_rules
node_mongo_helpers -->|"uses operation rules"| node_mongo_rules
node_mongo_helpers -.->|"reads and writes"| node_mongo
node_redis_interceptor -.->|"intercepts activity"| node_redis
node_express_patch -->|"installs middleware"| node_middleware
node_http_patch -->|"uses startup"| node_startup
node_test_runner -->|"compares test data"| node_common
node_developer -->|"requests generation"| node_unit_generate
node_developer -->|"requests expansion"| node_unit_expand
node_unit_generate -->|"uses API config"| node_unit_api
node_unit_generate -->|"uses CLI interface"| node_unit_gui
node_unit_expand -->|"uses API config"| node_unit_api
node_unit_expand -->|"uses CLI interface"| node_unit_gui
node_unit_api -.->|"configures API access"| node_gpt
node_export_cmd -->|"loads generated tests"| node_common
node_export_cmd -->|"converts legacy tests"| node_legacy
node_export_cmd -->|"gets API config"| node_unit_api
node_export_cmd -->|"exports eligible tests"| node_export_helpers
node_export_cmd -->|"reads arguments"| node_args
node_export_helpers -.->|"generates Jest content"| node_gpt
node_jest_cmd -.->|"runs generated tests"| node_developer
node_test_runner -->|"reports results"| node_logging

click node_cli "https://github.com/pythagora-io/pythagora/blob/main/src/bin/run.js"
click node_startup "https://github.com/pythagora-io/pythagora/blob/main/src/helpers/starting.js"
click node_engine "https://github.com/pythagora-io/pythagora/blob/main/src/Pythagora.js"
click node_middleware "https://github.com/pythagora-io/pythagora/blob/main/src/helpers/middlewares.js"
click node_test_runner "https://github.com/pythagora-io/pythagora/blob/main/src/RunPythagoraTests.js"
click node_http_patch "https://github.com/pythagora-io/pythagora/blob/main/src/patches/http.js"
click node_express_patch "https://github.com/pythagora-io/pythagora/blob/main/src/patches/express.js"
click node_mongo_patch "https://github.com/pythagora-io/pythagora/blob/main/src/patches/mongo-collection.js"
click node_mongo_helpers "https://github.com/pythagora-io/pythagora/blob/main/src/helpers/mongodb.js"
click node_mongo_rules "https://github.com/pythagora-io/pythagora/blob/main/src/const/mongodb.js"
click node_redis_interceptor "https://github.com/pythagora-io/pythagora/blob/main/src/helpers/redis.js"
click node_unit_generate "https://github.com/pythagora-io/pythagora/blob/main/src/helpers/unitTests.js"
click node_unit_expand "https://github.com/pythagora-io/pythagora/blob/main/src/helpers/unitTestsExpand.js"
click node_unit_api "https://github.com/pythagora-io/pythagora/blob/main/src/helpers/api.js"
click node_unit_gui "https://github.com/pythagora-io/pythagora/blob/main/src/helpers/cmdGUI.js"
click node_export_cmd "https://github.com/pythagora-io/pythagora/blob/main/src/commands/export.js"
click node_export_helpers "https://github.com/pythagora-io/pythagora/blob/main/src/helpers/exports.js"
click node_jest_cmd "https://github.com/pythagora-io/pythagora/blob/main/src/commands/jest.js"
click node_args "https://github.com/pythagora-io/pythagora/blob/main/src/utils/getArgs.js"
click node_common "https://github.com/pythagora-io/pythagora/blob/main/src/utils/common.js"
click node_logging "https://github.com/pythagora-io/pythagora/blob/main/src/utils/cmdPrint.js"
click node_legacy "https://github.com/pythagora-io/pythagora/blob/main/src/utils/legacy.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_cli,node_startup,node_engine,node_middleware,node_test_runner,node_http_patch,node_express_patch toneBlue
class node_mongo_patch,node_mongo_helpers,node_mongo_rules,node_redis_interceptor,node_mongo,node_redis toneAmber
class node_unit_generate,node_unit_expand,node_unit_api,node_unit_gui toneMint
class node_export_cmd,node_export_helpers,node_jest_cmd toneRose
class node_args,node_common,node_logging,node_legacy,node_developer,node_app,node_gpt toneIndigo
```

## Components

### Capture and replay

- [CLI entry](https://github.com/pythagora-io/pythagora/blob/main/src/bin/run.js): `src/bin/run.js`
- [Runtime startup](https://github.com/pythagora-io/pythagora/blob/main/src/helpers/starting.js): `src/helpers/starting.js`
- [Capture replay engine](https://github.com/pythagora-io/pythagora/blob/main/src/Pythagora.js): `src/Pythagora.js`
- [HTTP middleware](https://github.com/pythagora-io/pythagora/blob/main/src/helpers/middlewares.js): `src/helpers/middlewares.js`
- [Replay runner](https://github.com/pythagora-io/pythagora/blob/main/src/RunPythagoraTests.js): `src/RunPythagoraTests.js`
- [HTTP patches](https://github.com/pythagora-io/pythagora/blob/main/src/patches/http.js): `src/patches/http.js`
- [Express patch](https://github.com/pythagora-io/pythagora/blob/main/src/patches/express.js): `src/patches/express.js`

### State and integrations

- [Mongo instrumentation](https://github.com/pythagora-io/pythagora/blob/main/src/patches/mongo-collection.js): `src/patches/mongo-collection.js`
- [Mongo replay](https://github.com/pythagora-io/pythagora/blob/main/src/helpers/mongodb.js): `src/helpers/mongodb.js`
- [Mongo operation rules](https://github.com/pythagora-io/pythagora/blob/main/src/const/mongodb.js): `src/const/mongodb.js`
- [Redis interceptor](https://github.com/pythagora-io/pythagora/blob/main/src/helpers/redis.js): `src/helpers/redis.js`

### Unit test generation

- [Generate unit tests](https://github.com/pythagora-io/pythagora/blob/main/src/helpers/unitTests.js): `src/helpers/unitTests.js`
- [Expand unit tests](https://github.com/pythagora-io/pythagora/blob/main/src/helpers/unitTestsExpand.js): `src/helpers/unitTestsExpand.js`
- [API configuration](https://github.com/pythagora-io/pythagora/blob/main/src/helpers/api.js): `src/helpers/api.js`
- [CLI interaction](https://github.com/pythagora-io/pythagora/blob/main/src/helpers/cmdGUI.js): `src/helpers/cmdGUI.js`

### Jest export

- [Export orchestration](https://github.com/pythagora-io/pythagora/blob/main/src/commands/export.js): `src/commands/export.js`
- [Jest test export](https://github.com/pythagora-io/pythagora/blob/main/src/helpers/exports.js): `src/helpers/exports.js`
- [Run Jest tests](https://github.com/pythagora-io/pythagora/blob/main/src/commands/jest.js): `src/commands/jest.js`

### Shared support

- [Argument config](https://github.com/pythagora-io/pythagora/blob/main/src/utils/getArgs.js): `src/utils/getArgs.js`
- [Test data utilities](https://github.com/pythagora-io/pythagora/blob/main/src/utils/common.js): `src/utils/common.js`
- [Status and diagnostics](https://github.com/pythagora-io/pythagora/blob/main/src/utils/cmdPrint.js): `src/utils/cmdPrint.js`
- [Legacy conversion](https://github.com/pythagora-io/pythagora/blob/main/src/utils/legacy.js): `src/utils/legacy.js`

### Other components

- **Developer**
- **Express app**
- **MongoDB**
- **Redis**
- **GPT service**

## Connections

- Developer → CLI entry: starts command
- CLI entry → Runtime startup: starts runtime
- Runtime startup → Capture replay engine: initializes (evidence: `src/helpers/starting.js`)
- Runtime startup → Replay runner: starts replay (evidence: `src/helpers/starting.js`)
- Express app → HTTP middleware: handles requests
- HTTP middleware → Mongo replay: prepares database (evidence: `src/helpers/middlewares.js`)
- HTTP middleware → Redis interceptor: sets mode (evidence: `src/helpers/middlewares.js`)
- Capture replay engine → Mongo replay: cleans database (evidence: `src/Pythagora.js`)
- Capture replay engine → Replay runner: replays requests (evidence: `src/Pythagora.js`)
- Capture replay engine → Redis interceptor: initializes (evidence: `src/Pythagora.js`)
- Capture replay engine → Test data utilities: uses utilities (evidence: `src/Pythagora.js`)
- Mongo instrumentation → Mongo replay: delegates replay (evidence: `src/patches/mongo-collection.js`)
- Mongo instrumentation → Mongo operation rules: reads operation rules (evidence: `src/patches/mongo-collection.js`)
- Mongo replay → Mongo operation rules: uses operation rules (evidence: `src/helpers/mongodb.js`)
- Mongo replay → MongoDB: reads and writes
- Redis interceptor → Redis: intercepts activity
- Express patch → HTTP middleware: installs middleware (evidence: `src/patches/express.js`)
- HTTP patches → Runtime startup: uses startup (evidence: `src/patches/http.js`)
- Replay runner → Test data utilities: compares test data (evidence: `src/RunPythagoraTests.js`)
- Developer → Generate unit tests: requests generation
- Developer → Expand unit tests: requests expansion
- Generate unit tests → API configuration: uses API config (evidence: `src/helpers/unitTests.js`)
- Generate unit tests → CLI interaction: uses CLI interface (evidence: `src/helpers/unitTests.js`)
- Expand unit tests → API configuration: uses API config (evidence: `src/helpers/unitTestsExpand.js`)
- Expand unit tests → CLI interaction: uses CLI interface (evidence: `src/helpers/unitTestsExpand.js`)
- API configuration → GPT service: configures API access
- Export orchestration → Test data utilities: loads generated tests (evidence: `src/commands/export.js`)
- Export orchestration → Legacy conversion: converts legacy tests (evidence: `src/commands/export.js`)
- Export orchestration → API configuration: gets API config (evidence: `src/commands/export.js`)
- Export orchestration → Jest test export: exports eligible tests (evidence: `src/commands/export.js`)
- Export orchestration → Argument config: reads arguments (evidence: `src/commands/export.js`)
- Jest test export → GPT service: generates Jest content
- Run Jest tests → Developer: runs generated tests
- Replay runner → Status and diagnostics: reports results (evidence: `src/RunPythagoraTests.js`)