# ranitmukherjee/keploy architecture

> Architecture diagram of the GitHub repository ranitmukherjee/keploy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ranitmukherjee/keploy
- Repository: https://github.com/ranitmukherjee/keploy

## Overview

##### Project type and purpose
- Keploy is a developer-centric, language-agnostic API test generator and recorder/replayer. It is neither a typical web app nor a microservice. It consists of:
- A CLI front-end (commands: record, test, import, export, ut-gen)
- A core agent that instruments your app via eBPF and proxies network/DB calls
- A service/orchestrator layer that processes recordings into testcases, stores them, and replays them
- A pluggable storage layer for mocks/tests (YAML, file system)
- Integrations with various protocols (HTTP/1.x, HTTP/2, gRPC) and databases (MySQL, Postgres, Mongo, Redis)

##### File structure
- Top-level commands in /cli implement the user interface and invoke the agent and service APIs.
- /pkg/core contains the agent:
- hooks/ (eBPF attachments)
- proxy/ (intercept and record/replay integrations for HTTP, gRPC, DB protocols)
- record.go, replay.go, tester/ (in-process mode)
- /pkg/service orchestrates recordings and test generation:
- record, replay, import, export, utgen, orchestrator subpackages
- /pkg/platform abstracts environment concerns:
- telemetry, docker support, coverage collectors, storage backends (YAML)
- /pkg/models defines domain objects: Testcase, Mock, Config, Transport protocols, etc.

##### Key insights from README
- CLI bootstraps agent (no code changes) and starts proxy.
- Agent transparently intercepts ALL CRUD network interactions and eBPF-recorded syscalls.
- Service layer converts recordings into tests/mocks and can replay them offline.
- Ut-gen embeds an LLM to auto-generate unit tests from code.

## Diagram (Mermaid)

```mermaid
graph TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["Keploy CLI"]:::frontend
        CLI -->|start/stop gRPC/HTTP| Agent
        CLI -->|trigger replay/test| Service
        CLI -->|trigger ut-gen| Service
    end
    click CLI "https://github.com/ranitmukherjee/keploy/blob/main/cli/cli.go"

    %% Agent Layer
    subgraph "Agent Layer" 
        Hooks["eBPF Hooks"]:::agent
        Proxy["Proxy Interceptors"]:::agent
        Recorder["Recorder Module"]:::agent
        Replayer["Replayer Module"]:::agent
        Tester["In-Process Tester"]:::agent

        Agent["Agent (pkg/core)"]:::agent
        Agent --> Hooks
        Agent --> Proxy
        Agent --> Recorder
        Agent --> Replayer
        Agent --> Tester
    end
    click Hooks "https://github.com/ranitmukherjee/keploy/tree/main/pkg/core/hooks/"
    click Proxy "https://github.com/ranitmukherjee/keploy/tree/main/pkg/core/proxy/integrations/"
    click Recorder "https://github.com/ranitmukherjee/keploy/blob/main/pkg/core/record.go"
    click Replayer "https://github.com/ranitmukherjee/keploy/blob/main/pkg/core/replay.go"
    click Tester "https://github.com/ranitmukherjee/keploy/blob/main/pkg/core/tester/tester.go"

    %% Application Process
    Application["User Application Process"]:::agent
    Proxy <-->|intercepts traffic| Application

    %% Service Layer
    subgraph "Service Orchestrator Layer"
        RecordSvc["Record Service"]:::service
        ReplaySvc["Replay Service"]:::service
        ImportSvc["Import Service"]:::service
        ExportSvc["Export Service"]:::service
        UTGenSvc["UT-Gen Service"]:::service
        Orchestrator["Orchestrator"]:::service
        ContractAPI["Service Contracts/API"]:::service

        Service["Service (pkg/service)"]:::service
        Service --> RecordSvc
        Service --> ReplaySvc
        Service --> ImportSvc
        Service --> ExportSvc
        Service --> UTGenSvc
        Service --> Orchestrator
        Service --> ContractAPI
    end
    click RecordSvc "https://github.com/ranitmukherjee/keploy/tree/main/pkg/service/record/"
    click ReplaySvc "https://github.com/ranitmukherjee/keploy/tree/main/pkg/service/replay/"
    click ImportSvc "https://github.com/ranitmukherjee/keploy/blob/main/pkg/service/import/import.go"
    click ExportSvc "https://github.com/ranitmukherjee/keploy/blob/main/pkg/service/export/export.go"
    click UTGenSvc "https://github.com/ranitmukherjee/keploy/tree/main/pkg/service/utgen/"
    click Orchestrator "https://github.com/ranitmukherjee/keploy/tree/main/pkg/service/orchestrator/"
    click ContractAPI "https://github.com/ranitmukherjee/keploy/tree/main/pkg/service/contract/"

    Agent -->|streams events| Service
    CLI -->|calls service API| Service

    %% Platform & Storage Layer
    subgraph "Platform Adapters Layer"
        YAML["YAML Storage Backend"]:::platform
        StorageIF["Storage Interface"]:::platform
        Docker["Docker Support"]:::platform
        Coverage["Coverage Collectors"]:::platform
        Telemetry["Telemetry Emitter"]:::platform
        Auth["Auth Abstractions"]:::platform

        Platform["Platform (pkg/platform)"]:::platform
        Platform --> YAML
        Platform --> StorageIF
        Platform --> Docker
        Platform --> Coverage
        Platform --> Telemetry
        Platform --> Auth
    end
    click YAML "https://github.com/ranitmukherjee/keploy/tree/main/pkg/platform/yaml/"
    click StorageIF "https://github.com/ranitmukherjee/keploy/blob/main/pkg/platform/storage/storage.go"
    click Docker "https://github.com/ranitmukherjee/keploy/tree/main/pkg/platform/docker/"
    click Coverage "https://github.com/ranitmukherjee/keploy/tree/main/pkg/platform/coverage/"
    click Telemetry "https://github.com/ranitmukherjee/keploy/tree/main/pkg/platform/telemetry/"
    click Auth "https://github.com/ranitmukherjee/keploy/tree/main/pkg/platform/auth/"

    Service -->|persist/retrieve| Platform

    %% Domain Models
    Models["Domain Models (pkg/models)"]:::platform
    click Models "https://github.com/ranitmukherjee/keploy/tree/main/pkg/models/"

    Service -->|uses| Models
    Agent -->|uses| Models

    %% External Services
    subgraph "External Services"
        HTTP["HTTP Services"]:::external
        GRPC["gRPC Services"]:::external
        MySQL["MySQL"]:::external
        Postgres["Postgres"]:::external
        MongoDB["MongoDB"]:::external
        Redis["Redis"]:::external
        LLM["LLM Provider"]:::external
    end

    Application -->|HTTP/gRPC/DB calls| HTTP
    Application -->|HTTP/gRPC/DB calls| GRPC
    Application -->|DB calls| MySQL
    Application -->|DB calls| Postgres
    Application -->|DB calls| MongoDB
    Application -->|DB calls| Redis

    UTGenSvc -->|prompts| LLM
    LLM -->|returns tests| UTGenSvc

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0969DA,stroke-width:1px
    classDef agent fill:#DFFFE0,stroke:#2E8B57,stroke-width:1px
    classDef service fill:#FFEFD5,stroke:#FF8C00,stroke-width:1px
    classDef platform fill:#F0F0F0,stroke:#A9A9A9,stroke-width:1px
    classDef external fill:#F5F5F5,stroke:#696969,stroke-width:1px,stroke-dasharray: 2 2
```
