# eysap/frida-il2cpp-trace architecture

> Architecture diagram of the GitHub repository eysap/frida-il2cpp-trace, 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/eysap/frida-il2cpp-trace
- Repository: https://github.com/eysap/frida-il2cpp-trace

## Overview

Frida IL2CPP Trace is a terminal-driven runtime instrumentation tool. The user selects a target process and supplies class/method filters; the host attaches an agent, which discovers the selected class, filters its methods, installs hooks, inspects calls and return values, and reports events for terminal or JSONL output. The graph preserves the documented device, spawn, and output capabilities. Host CLI, configuration loading, and output details are represented from the tree and README; their internal wiring is not sampled, so those links are limited to documented workflow.

Main entry points: [`src/tools/class-hooker.ts`](https://github.com/eysap/frida-il2cpp-trace/blob/main/src/tools/class-hooker.ts) (Hook workflow), [`src/host/session.ts`](https://github.com/eysap/frida-il2cpp-trace/blob/main/src/host/session.ts) (Frida session), [`src/host/cli.ts`](https://github.com/eysap/frida-il2cpp-trace/blob/main/src/host/cli.ts) (CLI entry), [`src/agent/engine/hook-manager.ts`](https://github.com/eysap/frida-il2cpp-trace/blob/main/src/agent/engine/hook-manager.ts) (Hook manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host CLI"]
  node_cli["CLI entry<br/>[cli.ts]"]
  node_options["Option parsing<br/>[options.ts]"]
  node_loader["Config loading<br/>[config-loader.ts]"]
  node_session["Frida session<br/>[session.ts]"]
  node_output["Event output<br/>[output.ts]"]
end

subgraph group_agent["Agent instrumentation"]
  node_orchestrator["Hook workflow<br/>[class-hooker.ts]"]
  node_discovery["Class discovery<br/>[discovery.ts]"]
  node_filtering["Method filtering<br/>[filtering.ts]"]
  node_hooks["Hook manager<br/>[hook-manager.ts]"]
  node_inspector["Value inspection<br/>[inspector.ts]"]
  node_reporter["Agent reporting"]
  node_bootstrap["Agent bootstrap<br/>[bootstrap.ts]"]
  node_rpc["Agent RPC<br/>[index.ts]"]
end

subgraph group_shared["Shared contracts"]
  node_config["Config validation<br/>[config.ts]"]
  node_selectors["Selectors<br/>[selectors.ts]"]
  node_events["Event types<br/>[events.ts]"]
end

subgraph group_integration["Runtime integration"]
  node_runtime["IL2CPP adapter<br/>[il2cpp-adapter.ts]"]
end

node_user(("Terminal user"))
node_configfile["Hook configuration<br/>[class-hooker.json]"]
node_frida["Frida runtime"]
node_target(("Unity target"))

node_user -->|"invokes"| node_cli
node_user -->|"provides"| node_configfile
node_cli -->|"parses options"| node_options
node_cli -->|"loads config"| node_loader
node_loader -->|"validates"| node_config
node_cli -->|"starts session"| node_session
node_cli -->|"selects output"| node_output
node_session -->|"attaches and loads"| node_frida
node_frida -->|"instruments"| node_target
node_session -->|"calls agent"| node_rpc
node_rpc -->|"starts or detaches"| node_bootstrap
node_bootstrap -->|"runs workflow"| node_orchestrator
node_orchestrator -->|"validates config"| node_config
node_orchestrator -->|"selects class"| node_discovery
node_discovery -->|"finds classes"| node_runtime
node_orchestrator -->|"lists methods"| node_runtime
node_orchestrator -->|"filters methods"| node_filtering
node_orchestrator -->|"installs hooks"| node_hooks
node_hooks -->|"attaches methods"| node_runtime
node_hooks -->|"inspects values"| node_inspector
node_hooks -->|"reports events"| node_reporter
node_discovery -->|"reports selection"| node_reporter
node_reporter -->|"sends typed events"| node_events
node_reporter -->|"sends agent messages"| node_session
node_session -->|"forwards events"| node_output
node_session -->|"detaches hooks"| node_hooks
node_config -->|"uses selectors"| node_selectors

click node_configfile "https://github.com/eysap/frida-il2cpp-trace/blob/main/examples/class-hooker.json"
click node_cli "https://github.com/eysap/frida-il2cpp-trace/blob/main/src/host/cli.ts"
click node_options "https://github.com/eysap/frida-il2cpp-trace/blob/main/src/host/options.ts"
click node_loader "https://github.com/eysap/frida-il2cpp-trace/blob/main/src/host/config-loader.ts"
click node_session "https://github.com/eysap/frida-il2cpp-trace/blob/main/src/host/session.ts"
click node_output "https://github.com/eysap/frida-il2cpp-trace/blob/main/src/host/output.ts"
click node_orchestrator "https://github.com/eysap/frida-il2cpp-trace/blob/main/src/tools/class-hooker.ts"
click node_discovery "https://github.com/eysap/frida-il2cpp-trace/blob/main/src/agent/engine/discovery.ts"
click node_filtering "https://github.com/eysap/frida-il2cpp-trace/blob/main/src/agent/engine/filtering.ts"
click node_hooks "https://github.com/eysap/frida-il2cpp-trace/blob/main/src/agent/engine/hook-manager.ts"
click node_inspector "https://github.com/eysap/frida-il2cpp-trace/blob/main/src/agent/engine/inspector.ts"
click node_reporter "https://github.com/eysap/frida-il2cpp-trace/blob/main/src/agent/message-reporter.ts"
click node_bootstrap "https://github.com/eysap/frida-il2cpp-trace/blob/main/src/agent/bootstrap.ts"
click node_rpc "https://github.com/eysap/frida-il2cpp-trace/blob/main/src/agent/index.ts"
click node_config "https://github.com/eysap/frida-il2cpp-trace/blob/main/src/shared/config.ts"
click node_selectors "https://github.com/eysap/frida-il2cpp-trace/blob/main/src/shared/selectors.ts"
click node_events "https://github.com/eysap/frida-il2cpp-trace/blob/main/src/shared/events.ts"
click node_runtime "https://github.com/eysap/frida-il2cpp-trace/blob/main/src/agent/runtime/il2cpp-adapter.ts"

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_options,node_loader,node_session,node_output,node_user toneBlue
class node_orchestrator,node_discovery,node_filtering,node_hooks,node_inspector,node_reporter,node_bootstrap,node_rpc toneAmber
class node_config,node_selectors,node_events toneMint
class node_runtime toneRose
class node_configfile toneTeal
class node_frida,node_target toneIndigo
```

## Components

### Host CLI

- [CLI entry](https://github.com/eysap/frida-il2cpp-trace/blob/main/src/host/cli.ts): `src/host/cli.ts`
- [Option parsing](https://github.com/eysap/frida-il2cpp-trace/blob/main/src/host/options.ts): `src/host/options.ts`
- [Config loading](https://github.com/eysap/frida-il2cpp-trace/blob/main/src/host/config-loader.ts): `src/host/config-loader.ts`
- [Frida session](https://github.com/eysap/frida-il2cpp-trace/blob/main/src/host/session.ts): `src/host/session.ts`
- [Event output](https://github.com/eysap/frida-il2cpp-trace/blob/main/src/host/output.ts): `src/host/output.ts`

### Agent instrumentation

- [Hook workflow](https://github.com/eysap/frida-il2cpp-trace/blob/main/src/tools/class-hooker.ts): `src/tools/class-hooker.ts`
- [Class discovery](https://github.com/eysap/frida-il2cpp-trace/blob/main/src/agent/engine/discovery.ts): `src/agent/engine/discovery.ts`
- [Method filtering](https://github.com/eysap/frida-il2cpp-trace/blob/main/src/agent/engine/filtering.ts): `src/agent/engine/filtering.ts`
- [Hook manager](https://github.com/eysap/frida-il2cpp-trace/blob/main/src/agent/engine/hook-manager.ts): `src/agent/engine/hook-manager.ts`
- [Value inspection](https://github.com/eysap/frida-il2cpp-trace/blob/main/src/agent/engine/inspector.ts): `src/agent/engine/inspector.ts`
- [Agent reporting](https://github.com/eysap/frida-il2cpp-trace/blob/main/src/agent/message-reporter.ts): `src/agent/message-reporter.ts`
- [Agent bootstrap](https://github.com/eysap/frida-il2cpp-trace/blob/main/src/agent/bootstrap.ts): `src/agent/bootstrap.ts`
- [Agent RPC](https://github.com/eysap/frida-il2cpp-trace/blob/main/src/agent/index.ts): `src/agent/index.ts`

### Shared contracts

- [Config validation](https://github.com/eysap/frida-il2cpp-trace/blob/main/src/shared/config.ts): `src/shared/config.ts`
- [Selectors](https://github.com/eysap/frida-il2cpp-trace/blob/main/src/shared/selectors.ts): `src/shared/selectors.ts`
- [Event types](https://github.com/eysap/frida-il2cpp-trace/blob/main/src/shared/events.ts): `src/shared/events.ts`

### Runtime integration

- [IL2CPP adapter](https://github.com/eysap/frida-il2cpp-trace/blob/main/src/agent/runtime/il2cpp-adapter.ts): `src/agent/runtime/il2cpp-adapter.ts`

### Other components

- **Terminal user**
- [Hook configuration](https://github.com/eysap/frida-il2cpp-trace/blob/main/examples/class-hooker.json): `examples/class-hooker.json`
- **Frida runtime**
- **Unity target**

## Connections

- Terminal user → CLI entry: invokes
- Terminal user → Hook configuration: provides
- CLI entry → Option parsing: parses options
- CLI entry → Config loading: loads config
- Config loading → Config validation: validates
- CLI entry → Frida session: starts session
- CLI entry → Event output: selects output
- Frida session → Frida runtime: attaches and loads
- Frida runtime → Unity target: instruments
- Frida session → Agent RPC: calls agent
- Agent RPC → Agent bootstrap: starts or detaches
- Agent bootstrap → Hook workflow: runs workflow
- Hook workflow → Config validation: validates config
- Hook workflow → Class discovery: selects class
- Class discovery → IL2CPP adapter: finds classes
- Hook workflow → IL2CPP adapter: lists methods
- Hook workflow → Method filtering: filters methods
- Hook workflow → Hook manager: installs hooks
- Hook manager → IL2CPP adapter: attaches methods
- Hook manager → Value inspection: inspects values
- Hook manager → Agent reporting: reports events
- Class discovery → Agent reporting: reports selection
- Agent reporting → Event types: sends typed events
- Agent reporting → Frida session: sends agent messages
- Frida session → Event output: forwards events
- Frida session → Hook manager: detaches hooks
- Config validation → Selectors: uses selectors