# wie-project/ps4recomp architecture

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

- Interactive diagram: https://gitdiagram.com/wie-project/ps4recomp
- Repository: https://github.com/wie-project/ps4recomp

## Overview

PS4Recomp is a macOS Apple Silicon AOT recompiler and runtime for decrypted PS4 game folders. The main user flow is to analyze or build a game through the CLI: load ELF/game data, inspect control flow, translate x86-64 instructions to ARM64, emit native assembly, and run the result with PS4-compatible runtime services. Graphics translation and Orbis subsystem emulation are important parallel capabilities. The README documents the high-level flow; several runtime and graphics implementation links are not visible in the sampled source, so those relationships are omitted rather than inferred.

Main entry points: [`pkg/runtime/core/recomp_runtime.h`](https://github.com/wie-project/ps4recomp/blob/main/pkg/runtime/core/recomp_runtime.h) (Recomp runtime), [`pkg/cli/cli.go`](https://github.com/wie-project/ps4recomp/blob/main/pkg/cli/cli.go) (PS4Recomp CLI), [`pkg/lifter/arm64_lifter.go`](https://github.com/wie-project/ps4recomp/blob/main/pkg/lifter/arm64_lifter.go) (ARM64 lifter), [`pkg/emitter/asm_emitter.go`](https://github.com/wie-project/ps4recomp/blob/main/pkg/emitter/asm_emitter.go) (Assembly emitter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["CLI and analysis"]
  node_cli["PS4Recomp CLI<br/>[cli.go]"]
  node_elf["ELF loader<br/>[loader.go]"]
  node_analyzer["Executable analyzer<br/>[analyzer.go]"]
  node_disasm["CFG and disassembly<br/>[cfg.go]"]
end

subgraph group_translation["Native translation"]
  node_lifter["ARM64 lifter<br/>[arm64_lifter.go]"]
  node_emitter["Assembly emitter<br/>[asm_emitter.go]"]
  node_bundle["macOS app output<br/>[cli.go]"]
end

subgraph group_runtime["Orbis runtime"]
  node_runtimecore["Recomp runtime<br/>[recomp_runtime.h]"]
  node_kernel["Kernel services"]
  node_uservice["User service<br/>[ps4_user_service.c]"]
  node_sysservice["System service"]
end

subgraph group_graphics["Graphics translation"]
  node_graphics["Metal graphics"]
  node_gcnapi["GCN recompiler API<br/>[gcn_recompiler.h]"]
end

subgraph group_integrations["Media and input"]
  node_audio["Audio services"]
  node_atrac["ATRAC9 decoding<br/>[ps4_ajm.c]"]
  node_videodec["Video decoding"]
  node_controller["Controller input"]
end

node_user(("Game developer"))
node_game["Decrypted game folder"]
node_nativeapp["Native ARM64 app"]

node_user -->|"invokes"| node_cli
node_cli -.->|"loads game"| node_elf
node_game -->|"supplies input"| node_cli
node_cli -.->|"analyzes"| node_analyzer
node_cli -.->|"inspects CFG"| node_disasm
node_cli -->|"recompiles"| node_lifter
node_lifter -.->|"emits assembly"| node_emitter
node_emitter -->|"builds output"| node_bundle
node_bundle -->|"produces"| node_nativeapp
node_nativeapp -.->|"runs with"| node_runtimecore
node_runtimecore -.->|"provides services"| node_kernel
node_runtimecore -->|"dispatches shims"| node_uservice
node_runtimecore -->|"dispatches shims"| node_sysservice
node_runtimecore -.->|"runs graphics"| node_graphics
node_graphics -.->|"exposes API"| node_gcnapi
node_runtimecore -.->|"provides audio"| node_audio
node_runtimecore -.->|"decodes audio"| node_atrac
node_runtimecore -.->|"decodes video"| node_videodec
node_runtimecore -.->|"handles input"| node_controller

click node_cli "https://github.com/wie-project/ps4recomp/blob/main/pkg/cli/cli.go"
click node_elf "https://github.com/wie-project/ps4recomp/blob/main/pkg/elfloader/loader.go"
click node_analyzer "https://github.com/wie-project/ps4recomp/blob/main/pkg/analyzer/analyzer.go"
click node_disasm "https://github.com/wie-project/ps4recomp/blob/main/pkg/disasm/cfg.go"
click node_lifter "https://github.com/wie-project/ps4recomp/blob/main/pkg/lifter/arm64_lifter.go"
click node_emitter "https://github.com/wie-project/ps4recomp/blob/main/pkg/emitter/asm_emitter.go"
click node_runtimecore "https://github.com/wie-project/ps4recomp/blob/main/pkg/runtime/core/recomp_runtime.h"
click node_kernel "https://github.com/wie-project/ps4recomp/tree/main/pkg/runtime/kernel"
click node_uservice "https://github.com/wie-project/ps4recomp/blob/main/pkg/runtime/modules/libSceUserService/ps4_user_service.c"
click node_sysservice "https://github.com/wie-project/ps4recomp/blob/main/pkg/runtime/modules/libSceSystemService/ps4_system_service.c"
click node_graphics "https://github.com/wie-project/ps4recomp/tree/main/3rdparty/gcn-recompiler"
click node_gcnapi "https://github.com/wie-project/ps4recomp/blob/main/3rdparty/gcn-recompiler/include/gcn_recompiler.h"
click node_audio "https://github.com/wie-project/ps4recomp/tree/main/pkg/runtime/modules/libSceAudioOut"
click node_atrac "https://github.com/wie-project/ps4recomp/blob/main/pkg/runtime/modules/libSceAjm/ps4_ajm.c"
click node_videodec "https://github.com/wie-project/ps4recomp/tree/main/pkg/runtime/modules/libSceVideodec"
click node_controller "https://github.com/wie-project/ps4recomp/tree/main/pkg/runtime/modules/libScePad"
click node_bundle "https://github.com/wie-project/ps4recomp/blob/main/pkg/cli/cli.go"

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_elf,node_analyzer,node_disasm toneBlue
class node_lifter,node_emitter,node_bundle toneAmber
class node_runtimecore,node_kernel,node_uservice,node_sysservice toneMint
class node_graphics,node_gcnapi toneRose
class node_audio,node_atrac,node_videodec,node_controller,node_user,node_game,node_nativeapp toneIndigo
```

## Components

### CLI and analysis

- [PS4Recomp CLI](https://github.com/wie-project/ps4recomp/blob/main/pkg/cli/cli.go): `pkg/cli/cli.go`
- [ELF loader](https://github.com/wie-project/ps4recomp/blob/main/pkg/elfloader/loader.go): `pkg/elfloader/loader.go`
- [Executable analyzer](https://github.com/wie-project/ps4recomp/blob/main/pkg/analyzer/analyzer.go): `pkg/analyzer/analyzer.go`
- [CFG and disassembly](https://github.com/wie-project/ps4recomp/blob/main/pkg/disasm/cfg.go): `pkg/disasm/cfg.go`

### Native translation

- [ARM64 lifter](https://github.com/wie-project/ps4recomp/blob/main/pkg/lifter/arm64_lifter.go): `pkg/lifter/arm64_lifter.go`
- [Assembly emitter](https://github.com/wie-project/ps4recomp/blob/main/pkg/emitter/asm_emitter.go): `pkg/emitter/asm_emitter.go`
- [macOS app output](https://github.com/wie-project/ps4recomp/blob/main/pkg/cli/cli.go): `pkg/cli/cli.go`

### Orbis runtime

- [Recomp runtime](https://github.com/wie-project/ps4recomp/blob/main/pkg/runtime/core/recomp_runtime.h): `pkg/runtime/core/recomp_runtime.h`
- [Kernel services](https://github.com/wie-project/ps4recomp/tree/main/pkg/runtime/kernel): `pkg/runtime/kernel`
- [User service](https://github.com/wie-project/ps4recomp/blob/main/pkg/runtime/modules/libSceUserService/ps4_user_service.c): `pkg/runtime/modules/libSceUserService/ps4_user_service.c`
- [System service](https://github.com/wie-project/ps4recomp/blob/main/pkg/runtime/modules/libSceSystemService/ps4_system_service.c): `pkg/runtime/modules/libSceSystemService/ps4_system_service.c`

### Graphics translation

- [Metal graphics](https://github.com/wie-project/ps4recomp/tree/main/3rdparty/gcn-recompiler): `3rdparty/gcn-recompiler`
- [GCN recompiler API](https://github.com/wie-project/ps4recomp/blob/main/3rdparty/gcn-recompiler/include/gcn_recompiler.h): `3rdparty/gcn-recompiler/include/gcn_recompiler.h`

### Media and input

- [Audio services](https://github.com/wie-project/ps4recomp/tree/main/pkg/runtime/modules/libSceAudioOut): `pkg/runtime/modules/libSceAudioOut`
- [ATRAC9 decoding](https://github.com/wie-project/ps4recomp/blob/main/pkg/runtime/modules/libSceAjm/ps4_ajm.c): `pkg/runtime/modules/libSceAjm/ps4_ajm.c`
- [Video decoding](https://github.com/wie-project/ps4recomp/tree/main/pkg/runtime/modules/libSceVideodec): `pkg/runtime/modules/libSceVideodec`
- [Controller input](https://github.com/wie-project/ps4recomp/tree/main/pkg/runtime/modules/libScePad): `pkg/runtime/modules/libScePad`

### Other components

- **Game developer**
- **Decrypted game folder**
- **Native ARM64 app**

## Connections

- Game developer → PS4Recomp CLI: invokes (evidence: `README.md`)
- PS4Recomp CLI → ELF loader: loads game
- Decrypted game folder → PS4Recomp CLI: supplies input (evidence: `README.md`)
- PS4Recomp CLI → Executable analyzer: analyzes
- PS4Recomp CLI → CFG and disassembly: inspects CFG
- PS4Recomp CLI → ARM64 lifter: recompiles (evidence: `README.md`)
- ARM64 lifter → Assembly emitter: emits assembly
- Assembly emitter → macOS app output: builds output (evidence: `README.md`)
- macOS app output → Native ARM64 app: produces (evidence: `README.md`)
- Native ARM64 app → Recomp runtime: runs with
- Recomp runtime → Kernel services: provides services
- Recomp runtime → User service: dispatches shims (evidence: `pkg/runtime/modules/libSceUserService/ps4_user_service.c`)
- Recomp runtime → System service: dispatches shims (evidence: `pkg/runtime/modules/libSceSystemService/ps4_system_service.c`)
- Recomp runtime → Metal graphics: runs graphics
- Metal graphics → GCN recompiler API: exposes API
- Recomp runtime → Audio services: provides audio
- Recomp runtime → ATRAC9 decoding: decodes audio
- Recomp runtime → Video decoding: decodes video
- Recomp runtime → Controller input: handles input