# edgurgel/mimic architecture

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

- Interactive diagram: https://gitdiagram.com/edgurgel/mimic
- Repository: https://github.com/edgurgel/mimic

## Overview

##### Project type and purpose
- This is an open-source Elixir library (“Mimic”) that provides a mocking DSL and runtime for tests.
- It hooks into existing modules by copying their BEAM code at test time, intercepts calls, and routes them through a per-process ETS table and a central server to apply stubs, expectations, rejections, and type checks.

##### File structure
- Top‐level mix files (mix.exs, mix.lock) and config (.credo.exs, .formatter.exs) indicate a standard Elixir OTP library.
- lib/mimic/application.ex defines the application/ supervision tree.
- lib/mimic/server.ex implements a GenServer or similar process to manage ETS tables and routing.
- lib/mimic/dsl.ex provides a DSL wrapper.
- lib/mimic/type_check.ex integrates optional Ham-based type validation.
- lib/mimic/module.ex, cover.ex define core helpers.
- lib/mimic/*.ex contain error types (UnexpectedCallError, VerificationError) and control modules.
- Tests under test/ drive the behavior via ExUnit.

##### README for additional insights
- Describes how Mimic.copy/1 creates a “copied” version of a module and installs run-time hooks.
- All calls to a copied module go first through an ETS lookup (per‐pid) to decide whether to call a stub, an expected function, or original implementation (or raise).
- verify!/1 and ExUnit integration enforce that expectations are met.

##### Elements
- “copy/2” from Test → Server
- “write stub/expect” from Test → ETS
- “foo/arity call” from Test → Proxy Module → ETS/Server
- “invoke stub/fn” or “invoke original”
- “record call” back into ETS
- “verify!” or automatic end-of-test → Server → compare expectations
- Green = user/test processes
- Blue = core engine (Server + ETS)
- Orange = proxy modules & code-injection
- Grey = optional TypeCheck plugin

##### Details
- Separation between proxy (injected) modules and original modules.
- Essential touches: supervision, ETS lookup, code injection, DSL vs. core calls.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User/Test Layer
    subgraph "User/Test Layer"
        direction TB
        TestProcess["ExUnit Test Process"]:::user
        TestHelper["test/test_helper.exs\n(Test Helper)"]:::user
    end

    %% Core Engine
    subgraph "Core Engine"
        direction TB
        Application["Mimic.Application\n(Supervision Tree)"]:::core
        Server["Mimic.Server\n(GenServer managing ETS)"]:::core
        ETS["ETS: mimic_table_by_pid"]:::core
    end

    %% DSL Layer
    subgraph "DSL Layer"
        direction TB
        DSL["Mimic.DSL\n(stub/expect/reject API)"]:::core
    end

    %% Proxy & Code-Injection
    subgraph "Proxy & Code-Injection"
        direction TB
        ModuleCopy["Mimic.Module\n(code injection core)"]:::proxy
        ProxyModule["Proxy Module\n(copied & patched BEAM)"]:::proxy
    end

    %% Original Modules
    subgraph "Original Modules"
        direction TB
        Original["Original Module\n(under test)"]:::proxy
        TestModules["test/support/test_modules.ex\n(Test Modules)"]:::proxy
    end

    %% Plugins
    subgraph "Optional Plugin"
        direction TB
        TypeCheck["Mimic.TypeCheck\n(Ham integration)"]:::plugin
    end

    %% Error Definitions
    subgraph "Error Definitions"
        direction TB
        Error["lib/mimic/error.ex\n(Generic Errors)"]:::core
        UnexpectedError["lib/mimic/unexpected_call_error.ex\n(UnexpectedCallError)"]:::core
        VerificationError["lib/mimic/verification_error.ex\n(VerificationError)"]:::core
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        Cover["lib/mimic/cover.ex\n(Core Helpers)"]:::core
        Entry["lib/mimic.ex\n(Entry Point)"]:::core
    end

    %% Connections
    TestProcess -->|copy/2| Server
    TestProcess --> DSL
    DSL -->|API call| Server
    DSL -->|write stub/expect| ETS

    TestProcess -->|foo/arity call| ProxyModule
    ProxyModule -->|lookup| ETS
    ETS -->|info| ProxyModule
    ProxyModule -->|invoke stub/fn or original| TestProcess
    ProxyModule -->|record call| ETS

    TestProcess -->|verify!/end-of-test| Server
    Server -->|compare expectations| ETS
    Server -->|raise VerificationError| VerificationError

    Server --> ETS
    Application --> Server

    ModuleCopy --> ProxyModule
    Original --> ProxyModule

    TypeCheck --> ModuleCopy
    TypeCheck --> Server

    Entry --> DSL
    Entry --> ModuleCopy
    Entry --> TypeCheck

    Cover --> Server
    Cover --> ModuleCopy

    Error --> Server

    %% Click Events
    click Application "https://github.com/edgurgel/mimic/blob/main/lib/mimic/application.ex"
    click Server "https://github.com/edgurgel/mimic/blob/main/lib/mimic/server.ex"
    click DSL "https://github.com/edgurgel/mimic/blob/main/lib/mimic/dsl.ex"
    click TypeCheck "https://github.com/edgurgel/mimic/blob/main/lib/mimic/type_check.ex"
    click ModuleCopy "https://github.com/edgurgel/mimic/blob/main/lib/mimic/module.ex"
    click Cover "https://github.com/edgurgel/mimic/blob/main/lib/mimic/cover.ex"
    click Error "https://github.com/edgurgel/mimic/blob/main/lib/mimic/error.ex"
    click UnexpectedError "https://github.com/edgurgel/mimic/blob/main/lib/mimic/unexpected_call_error.ex"
    click VerificationError "https://github.com/edgurgel/mimic/blob/main/lib/mimic/verification_error.ex"
    click Entry "https://github.com/edgurgel/mimic/blob/main/lib/mimic.ex"
    click TestModules "https://github.com/edgurgel/mimic/blob/main/test/support/test_modules.ex"
    click TestHelper "https://github.com/edgurgel/mimic/blob/main/test/test_helper.exs"

    %% Styles
    classDef user fill:#a2f5a2,stroke:#000
    classDef core fill:#a2d1f9,stroke:#000
    classDef proxy fill:#f9d29d,stroke:#000
    classDef plugin fill:#d3d3d3,stroke:#000
```
