# momo5502/sogen architecture

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

- Interactive diagram: https://gitdiagram.com/momo5502/sogen
- Repository: https://github.com/momo5502/sogen

## Overview

Sogen executes Windows and Linux binaries by emulating CPU instructions and operating-system syscall behavior, with selectable CPU backends. The main workflow is to submit a program through the web playground or a native analyzer, run it in the relevant OS emulator, and inspect or control execution through hooks and debugger interfaces. Major supporting capabilities include module loading, memory management, state snapshots, Python bindings, and managed subprocesses. Several subsystem links below are documented in the README; unsampled implementation details are not treated as verified call paths.

Main entry points: [`src/windows-emulator/windows_emulator.hpp`](https://github.com/momo5502/sogen/blob/main/src/windows-emulator/windows_emulator.hpp) (Windows emulator), [`src/linux-emulator/linux_emulator.cpp`](https://github.com/momo5502/sogen/blob/main/src/linux-emulator/linux_emulator.cpp) (Linux emulator), [`src/windows-analyzer/main.cpp`](https://github.com/momo5502/sogen/blob/main/src/windows-analyzer/main.cpp) (Windows analyzer), [`page/src/App.tsx`](https://github.com/momo5502/sogen/blob/main/page/src/App.tsx) (Web app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Web app<br/>[App.tsx]"]
  node_landing["Landing page<br/>[landing-page.tsx]"]
  node_playground["Emulation playground<br/>[playground.tsx]"]
  node_webworker["Emulator worker<br/>[emulator-worker.js]"]
end

subgraph group_runtime["Execution runtime"]
  node_backends["CPU backends"]
  node_modules["Binary module loading<br/>[module_manager.cpp]"]
  node_winmemory["Windows memory<br/>[memory_manager.cpp]"]
  node_linuxmemory["Linux memory"]
  node_snapshot["State snapshots<br/>[serialization.hpp]"]
end

subgraph group_os["Guest operating systems"]
  node_windows["Windows emulator"]
  node_linux["Linux emulator<br/>[linux_emulator.cpp]"]
  node_winservices["Windows services"]
  node_linuxservices["Linux syscalls"]
  node_filesystem["Guest filesystem<br/>[file_system.hpp]"]
  node_registry["Windows registry"]
end

subgraph group_control["Inspection and control"]
  node_debugger["Debugger event handling<br/>[event_handler.cpp]"]
  node_gdb["GDB protocol"]
end

subgraph group_integration["External interfaces"]
  node_analyzer["Windows analyzer<br/>[main.cpp]"]
  node_linuxanalyzer["Linux analyzer<br/>[main.cpp]"]
  node_python["Python bindings<br/>[sogen_module.cpp]"]
  node_process["Managed processes"]
end

node_user(("Program user"))

node_user -->|"opens"| node_webapp
node_webapp -->|"routes to"| node_landing
node_webapp -->|"routes to"| node_playground
node_playground -.->|"dispatches work"| node_webworker
node_user -->|"starts program"| node_analyzer
node_user -.->|"starts program"| node_linuxanalyzer
node_analyzer -->|"sets up"| node_windows
node_analyzer -->|"uses managed process"| node_process
node_analyzer -.->|"hooks execution"| node_debugger
node_linuxanalyzer -.->|"runs in"| node_linux
node_windows -->|"executes with"| node_backends
node_linux -->|"executes with"| node_backends
node_windows -->|"loads PE modules"| node_modules
node_windows -->|"manages guest memory"| node_winmemory
node_linux -.->|"manages guest memory"| node_linuxmemory
node_windows -.->|"dispatches syscalls"| node_winservices
node_linux -.->|"dispatches syscalls"| node_linuxservices
node_windows -->|"uses filesystem"| node_filesystem
node_windows -.->|"uses registry"| node_registry
node_user -->|"inspects execution"| node_debugger
node_debugger -->|"controls emulator"| node_windows
node_user -->|"connects debugger"| node_gdb
node_gdb -.->|"debugs externally"| node_windows
node_windows -->|"snapshots state"| node_snapshot
node_user -->|"drives runtime"| node_python
node_python -->|"creates application"| node_windows

click node_webapp "https://github.com/momo5502/sogen/blob/main/page/src/App.tsx"
click node_landing "https://github.com/momo5502/sogen/blob/main/page/src/landing-page.tsx"
click node_playground "https://github.com/momo5502/sogen/blob/main/page/src/playground.tsx"
click node_webworker "https://github.com/momo5502/sogen/blob/main/page/public/emulator-worker.js"
click node_analyzer "https://github.com/momo5502/sogen/blob/main/src/windows-analyzer/main.cpp"
click node_linuxanalyzer "https://github.com/momo5502/sogen/blob/main/src/linux-analyzer/main.cpp"
click node_windows "https://github.com/momo5502/sogen/blob/main/src/windows-emulator/windows_emulator.hpp"
click node_linux "https://github.com/momo5502/sogen/blob/main/src/linux-emulator/linux_emulator.cpp"
click node_backends "https://github.com/momo5502/sogen/blob/main/src/backend-selection/backend_selection.cpp"
click node_modules "https://github.com/momo5502/sogen/blob/main/src/windows-emulator/module/module_manager.cpp"
click node_winmemory "https://github.com/momo5502/sogen/blob/main/src/windows-emulator/memory_manager.cpp"
click node_linuxmemory "https://github.com/momo5502/sogen/blob/main/src/linux-emulator/linux_memory_manager.cpp"
click node_winservices "https://github.com/momo5502/sogen/blob/main/src/windows-emulator/syscall_dispatcher.cpp"
click node_linuxservices "https://github.com/momo5502/sogen/blob/main/src/linux-emulator/linux_syscall_dispatcher.cpp"
click node_filesystem "https://github.com/momo5502/sogen/blob/main/src/windows-emulator/file_system.hpp"
click node_registry "https://github.com/momo5502/sogen/blob/main/src/windows-emulator/registry/registry_manager.cpp"
click node_snapshot "https://github.com/momo5502/sogen/blob/main/src/emulator/serialization.hpp"
click node_debugger "https://github.com/momo5502/sogen/blob/main/src/debugger/event_handler.cpp"
click node_gdb "https://github.com/momo5502/sogen/blob/main/src/gdb-stub/connection_handler.cpp"
click node_python "https://github.com/momo5502/sogen/blob/main/src/python-bindings/sogen_module.cpp"
click node_process "https://github.com/momo5502/sogen/blob/main/src/process-manager/subprocess_process_manager.cpp"

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_webapp,node_landing,node_playground,node_webworker,node_user toneBlue
class node_backends,node_modules,node_winmemory,node_linuxmemory,node_snapshot toneAmber
class node_windows,node_linux,node_winservices,node_linuxservices,node_filesystem,node_registry toneMint
class node_debugger,node_gdb toneRose
class node_analyzer,node_linuxanalyzer,node_python,node_process toneIndigo
```

## Components

### Web experience

- [Web app](https://github.com/momo5502/sogen/blob/main/page/src/App.tsx): `page/src/App.tsx`
- [Landing page](https://github.com/momo5502/sogen/blob/main/page/src/landing-page.tsx): `page/src/landing-page.tsx`
- [Emulation playground](https://github.com/momo5502/sogen/blob/main/page/src/playground.tsx): `page/src/playground.tsx`
- [Emulator worker](https://github.com/momo5502/sogen/blob/main/page/public/emulator-worker.js): `page/public/emulator-worker.js`

### Execution runtime

- [CPU backends](https://github.com/momo5502/sogen/blob/main/src/backend-selection/backend_selection.cpp): `src/backend-selection/backend_selection.cpp`
- [Binary module loading](https://github.com/momo5502/sogen/blob/main/src/windows-emulator/module/module_manager.cpp): `src/windows-emulator/module/module_manager.cpp`
- [Windows memory](https://github.com/momo5502/sogen/blob/main/src/windows-emulator/memory_manager.cpp): `src/windows-emulator/memory_manager.cpp`
- [Linux memory](https://github.com/momo5502/sogen/blob/main/src/linux-emulator/linux_memory_manager.cpp): `src/linux-emulator/linux_memory_manager.cpp`
- [State snapshots](https://github.com/momo5502/sogen/blob/main/src/emulator/serialization.hpp): `src/emulator/serialization.hpp`

### Guest operating systems

- [Windows emulator](https://github.com/momo5502/sogen/blob/main/src/windows-emulator/windows_emulator.hpp): `src/windows-emulator/windows_emulator.hpp`
- [Linux emulator](https://github.com/momo5502/sogen/blob/main/src/linux-emulator/linux_emulator.cpp): `src/linux-emulator/linux_emulator.cpp`
- [Windows services](https://github.com/momo5502/sogen/blob/main/src/windows-emulator/syscall_dispatcher.cpp): `src/windows-emulator/syscall_dispatcher.cpp`
- [Linux syscalls](https://github.com/momo5502/sogen/blob/main/src/linux-emulator/linux_syscall_dispatcher.cpp): `src/linux-emulator/linux_syscall_dispatcher.cpp`
- [Guest filesystem](https://github.com/momo5502/sogen/blob/main/src/windows-emulator/file_system.hpp): `src/windows-emulator/file_system.hpp`
- [Windows registry](https://github.com/momo5502/sogen/blob/main/src/windows-emulator/registry/registry_manager.cpp): `src/windows-emulator/registry/registry_manager.cpp`

### Inspection and control

- [Debugger event handling](https://github.com/momo5502/sogen/blob/main/src/debugger/event_handler.cpp): `src/debugger/event_handler.cpp`
- [GDB protocol](https://github.com/momo5502/sogen/blob/main/src/gdb-stub/connection_handler.cpp): `src/gdb-stub/connection_handler.cpp`

### External interfaces

- [Windows analyzer](https://github.com/momo5502/sogen/blob/main/src/windows-analyzer/main.cpp): `src/windows-analyzer/main.cpp`
- [Linux analyzer](https://github.com/momo5502/sogen/blob/main/src/linux-analyzer/main.cpp): `src/linux-analyzer/main.cpp`
- [Python bindings](https://github.com/momo5502/sogen/blob/main/src/python-bindings/sogen_module.cpp): `src/python-bindings/sogen_module.cpp`
- [Managed processes](https://github.com/momo5502/sogen/blob/main/src/process-manager/subprocess_process_manager.cpp): `src/process-manager/subprocess_process_manager.cpp`

### Other components

- **Program user**

## Connections

- Program user → Web app: opens (evidence: `page/src/App.tsx`)
- Web app → Landing page: routes to (evidence: `page/src/App.tsx`)
- Web app → Emulation playground: routes to (evidence: `page/src/App.tsx`)
- Emulation playground → Emulator worker: dispatches work
- Program user → Windows analyzer: starts program (evidence: `README.md`)
- Program user → Linux analyzer: starts program
- Windows analyzer → Windows emulator: sets up (evidence: `src/windows-analyzer/main.cpp`)
- Windows analyzer → Managed processes: uses managed process (evidence: `src/windows-analyzer/main.cpp`)
- Windows analyzer → Debugger event handling: hooks execution
- Linux analyzer → Linux emulator: runs in
- Windows emulator → CPU backends: executes with (evidence: `README.md`)
- Linux emulator → CPU backends: executes with (evidence: `README.md`)
- Windows emulator → Binary module loading: loads PE modules (evidence: `src/windows-emulator/module/module_manager.cpp`)
- Windows emulator → Windows memory: manages guest memory (evidence: `src/windows-emulator/windows_emulator.hpp`)
- Linux emulator → Linux memory: manages guest memory
- Windows emulator → Windows services: dispatches syscalls
- Linux emulator → Linux syscalls: dispatches syscalls
- Windows emulator → Guest filesystem: uses filesystem (evidence: `src/windows-emulator/windows_emulator.hpp`)
- Windows emulator → Windows registry: uses registry
- Program user → Debugger event handling: inspects execution (evidence: `README.md`)
- Debugger event handling → Windows emulator: controls emulator (evidence: `src/debugger/event_handler.cpp`)
- Program user → GDB protocol: connects debugger (evidence: `README.md`)
- GDB protocol → Windows emulator: debugs externally
- Windows emulator → State snapshots: snapshots state (evidence: `README.md`)
- Program user → Python bindings: drives runtime (evidence: `README.md`)
- Python bindings → Windows emulator: creates application (evidence: `README.md`)
