# pgundlupetvenkatesh/mdb_api_layer architecture

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

- Interactive diagram: https://gitdiagram.com/pgundlupetvenkatesh/mdb_api_layer
- Repository: https://github.com/pgundlupetvenkatesh/mdb_api_layer

## Overview

mdb_api_layer is a Python framework for exercising TMDB through a layered API client, with integration, contract, and performance testing. Its primary workflow is test suites using configured API clients to send requests and validate responses; contract and load testing provide distinct test modes. A separate failure-analysis branch diagnoses test failures with an LLM, evaluates diagnosis quality, and exposes tools through MCP. The graph follows README-described connections and sampled source references; several test and AI implementation details are represented only at their documented directory or module paths.

Main entry points: [`tests`](https://github.com/pgundlupetvenkatesh/mdb_api_layer/tree/main/tests) (API test suites), [`api/base_api.py`](https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/api/base_api.py) (HTTP base client), [`evals/__main__.py`](https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/evals/__main__.py) (Evaluation runner), [`evals/judge.py`](https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/evals/judge.py) (LLM judge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["TMDB Client"]
  node_config["Configuration<br/>[config.py]"]
  node_base["HTTP base client<br/>[base_api.py]"]
  node_movies["Movies client<br/>[movies_api.py]"]
  node_otherclients["Domain clients"]
end

subgraph group_testing["Test Framework"]
  node_suites["API test suites"]
  node_fixtures["Fixtures and hooks<br/>[conftest.py]"]
  node_schemas["Response schemas"]
  node_helpers["Test helpers"]
  node_testdata["Test data"]
  node_contracts["Pact contracts"]
end

subgraph group_analysis["Failure Analysis"]
  node_failure["Failure analyzer"]
  node_mcp["MCP tools"]
  node_mcpserver["MCP server<br/>[server.py]"]
  node_dataset["Golden dataset"]
  node_loader["Dataset loader<br/>[dataset.py]"]
  node_evalrunner["Evaluation runner<br/>[__main__.py]"]
  node_judge["LLM judge<br/>[judge.py]"]
  node_telemetry["Token telemetry<br/>[telemetry.py]"]
end

subgraph group_ops["Performance Testing"]
  node_locust["Locust scenarios<br/>[locustfile.py]"]
end

node_engineer(("Test author"))
node_pytest(("Pytest runner"))
node_tmdb["TMDB API"]
node_groq["Groq LLM"]

node_engineer -->|"authors tests"| node_suites
node_pytest -->|"wires fixtures"| node_fixtures
node_fixtures -->|"supports"| node_suites
node_suites -->|"uses client"| node_movies
node_suites -->|"uses clients"| node_otherclients
node_base -->|"reads settings"| node_config
node_movies -->|"inherits"| node_base
node_otherclients -->|"inherits"| node_base
node_base -->|"sends requests"| node_tmdb
node_suites -->|"validates responses"| node_schemas
node_suites -->|"uses assertions"| node_helpers
node_suites -->|"uses test data"| node_testdata
node_contracts -->|"tests contracts"| node_tmdb
node_locust -->|"generates load"| node_tmdb
node_mcpserver -->|"dispatches tools"| node_mcp
node_mcp -->|"invokes analyzer"| node_failure
node_failure -->|"requests diagnosis"| node_groq
node_evalrunner -->|"loads cases"| node_loader
node_loader -.->|"reads cases"| node_dataset
node_evalrunner -->|"runs diagnosis"| node_failure
node_evalrunner -->|"scores diagnosis"| node_judge
node_judge -.->|"requests verdict"| node_groq
node_judge -->|"records usage"| node_telemetry

click node_config "https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/config/config.py"
click node_base "https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/api/base_api.py"
click node_movies "https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/api/movies_api.py"
click node_otherclients "https://github.com/pgundlupetvenkatesh/mdb_api_layer/tree/main/api"
click node_suites "https://github.com/pgundlupetvenkatesh/mdb_api_layer/tree/main/tests"
click node_fixtures "https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/tests/conftest.py"
click node_schemas "https://github.com/pgundlupetvenkatesh/mdb_api_layer/tree/main/tests/schemas"
click node_helpers "https://github.com/pgundlupetvenkatesh/mdb_api_layer/tree/main/tests/helpers"
click node_testdata "https://github.com/pgundlupetvenkatesh/mdb_api_layer/tree/main/tests/data"
click node_contracts "https://github.com/pgundlupetvenkatesh/mdb_api_layer/tree/main/tests/contracts"
click node_failure "https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/tests/helpers/failure_analyzer.py"
click node_mcp "https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/failure_mcp/tools/analyze_test_failure.py"
click node_mcpserver "https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/failure_mcp/server.py"
click node_dataset "https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/evals/golden_dataset.yaml"
click node_loader "https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/evals/dataset.py"
click node_evalrunner "https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/evals/__main__.py"
click node_judge "https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/evals/judge.py"
click node_telemetry "https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/telemetry.py"
click node_locust "https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/performance/locustfile.py"

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_config,node_base,node_movies,node_otherclients toneBlue
class node_suites,node_fixtures,node_schemas,node_helpers,node_testdata,node_contracts toneAmber
class node_failure,node_mcp,node_mcpserver,node_dataset,node_loader,node_evalrunner,node_judge,node_telemetry,node_tmdb toneMint
class node_locust toneRose
class node_engineer,node_pytest,node_groq toneIndigo
```

## Components

### TMDB Client

- [Configuration](https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/config/config.py): `config/config.py`
- [HTTP base client](https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/api/base_api.py): `api/base_api.py`
- [Movies client](https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/api/movies_api.py): `api/movies_api.py`
- [Domain clients](https://github.com/pgundlupetvenkatesh/mdb_api_layer/tree/main/api): `api`

### Test Framework

- [API test suites](https://github.com/pgundlupetvenkatesh/mdb_api_layer/tree/main/tests): `tests`
- [Fixtures and hooks](https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/tests/conftest.py): `tests/conftest.py`
- [Response schemas](https://github.com/pgundlupetvenkatesh/mdb_api_layer/tree/main/tests/schemas): `tests/schemas`
- [Test helpers](https://github.com/pgundlupetvenkatesh/mdb_api_layer/tree/main/tests/helpers): `tests/helpers`
- [Test data](https://github.com/pgundlupetvenkatesh/mdb_api_layer/tree/main/tests/data): `tests/data`
- [Pact contracts](https://github.com/pgundlupetvenkatesh/mdb_api_layer/tree/main/tests/contracts): `tests/contracts`

### Failure Analysis

- [Failure analyzer](https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/tests/helpers/failure_analyzer.py): `tests/helpers/failure_analyzer.py`
- [MCP tools](https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/failure_mcp/tools/analyze_test_failure.py): `failure_mcp/tools/analyze_test_failure.py`
- [MCP server](https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/failure_mcp/server.py): `failure_mcp/server.py`
- [Golden dataset](https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/evals/golden_dataset.yaml): `evals/golden_dataset.yaml`
- [Dataset loader](https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/evals/dataset.py): `evals/dataset.py`
- [Evaluation runner](https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/evals/__main__.py): `evals/__main__.py`
- [LLM judge](https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/evals/judge.py): `evals/judge.py`
- [Token telemetry](https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/telemetry.py): `telemetry.py`

### Performance Testing

- [Locust scenarios](https://github.com/pgundlupetvenkatesh/mdb_api_layer/blob/main/performance/locustfile.py): `performance/locustfile.py`

### Other components

- **Test author**
- **Pytest runner**
- **TMDB API**
- **Groq LLM**

## Connections

- Test author → API test suites: authors tests (evidence: `README.md`)
- Pytest runner → Fixtures and hooks: wires fixtures (evidence: `README.md`)
- Fixtures and hooks → API test suites: supports (evidence: `README.md`)
- API test suites → Movies client: uses client (evidence: `README.md`)
- API test suites → Domain clients: uses clients (evidence: `README.md`)
- HTTP base client → Configuration: reads settings (evidence: `api/base_api.py`)
- Movies client → HTTP base client: inherits (evidence: `api/movies_api.py`)
- Domain clients → HTTP base client: inherits (evidence: `api/account_api.py`)
- HTTP base client → TMDB API: sends requests (evidence: `README.md`)
- API test suites → Response schemas: validates responses (evidence: `README.md`)
- API test suites → Test helpers: uses assertions (evidence: `README.md`)
- API test suites → Test data: uses test data (evidence: `README.md`)
- Pact contracts → TMDB API: tests contracts (evidence: `README.md`)
- Locust scenarios → TMDB API: generates load (evidence: `README.md`)
- MCP server → MCP tools: dispatches tools (evidence: `failure_mcp/server.py`)
- MCP tools → Failure analyzer: invokes analyzer (evidence: `failure_mcp/tools/analyze_test_failure.py`)
- Failure analyzer → Groq LLM: requests diagnosis (evidence: `README.md`)
- Evaluation runner → Dataset loader: loads cases (evidence: `evals/__main__.py`)
- Dataset loader → Golden dataset: reads cases
- Evaluation runner → Failure analyzer: runs diagnosis (evidence: `evals/__main__.py`)
- Evaluation runner → LLM judge: scores diagnosis (evidence: `evals/__main__.py`)
- LLM judge → Groq LLM: requests verdict
- LLM judge → Token telemetry: records usage (evidence: `evals/judge.py`)
