# sentomk/nekomata architecture

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

- Interactive diagram: https://gitdiagram.com/sentomk/nekomata
- Repository: https://github.com/sentomk/nekomata

## Overview

Nekomata is a C/C++ native hot-reload library: an application watches a reload group, receives a published object generation, prepares it away from the update path, then commits or rolls back entry-point changes at the caller’s safe point while preserving state. The repository also contains a browser/Wasm reload path, a PE backend, and an optional TUI. README documents the end-to-end behavior; source excerpts show selected orchestration and backend details, so unsampled subsystem links are omitted or marked unverified.

Main entry points: [`src/runtime/managed_worker.cpp`](https://github.com/sentomk/nekomata/blob/main/src/runtime/managed_worker.cpp) (Generation preparation), [`src/backends/elf/runtime/loader.cpp`](https://github.com/sentomk/nekomata/blob/main/src/backends/elf/runtime/loader.cpp) (ELF object loader), [`src/runtime/native_session.cpp`](https://github.com/sentomk/nekomata/blob/main/src/runtime/native_session.cpp) (Native session), [`src/runtime/reload_transaction.cpp`](https://github.com/sentomk/nekomata/blob/main/src/runtime/reload_transaction.cpp) (Reload transaction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Reload runtime"]
  node_session_api["Session API<br/>[session.hpp]"]
  node_native_session["Native session<br/>[native_session.cpp]"]
  node_discovery["Descriptor discovery"]
  node_worker["Generation preparation<br/>[managed_worker.cpp]"]
  node_stream["Generation stream"]
  node_transaction["Reload transaction"]
end

subgraph group_protocol["Generation protocol"]
  node_publisher["Generation publisher<br/>[publisher.cpp]"]
  node_offer["Generation offer"]
  node_descriptor["Group descriptor"]
end

subgraph group_native["Native backends"]
  node_elf_loader["ELF object loader<br/>[loader.cpp]"]
  node_elf_symbols["Process symbols"]
  node_elf_binary["ELF binary reader<br/>[binary_file.cpp]"]
  node_pe_loader["PE object loader<br/>[loader.cpp]"]
  node_pe_layout["PE image layout<br/>[image_layout.hpp]"]
end

subgraph group_browser["Browser backend"]
  node_wasm_session["Wasm session<br/>[session.cpp]"]
  node_wasm_poller["Offer poller<br/>[offer_poller.hpp]"]
  node_wasm_candidate["Module candidate<br/>[candidate.hpp]"]
end

subgraph group_ui["Monitoring"]
  node_monitor["TUI monitor<br/>[monitor.cpp]"]
end

node_application(("Application"))

node_application -->|"watches and updates"| node_session_api
node_session_api -.->|"drives session"| node_native_session
node_native_session -->|"discovers descriptors"| node_discovery
node_native_session -.->|"prepares groups"| node_worker
node_worker -->|"polls generations"| node_stream
node_worker -.->|"prepares reloads"| node_transaction
node_application -->|"safe-point update"| node_transaction
node_publisher -->|"publishes generation"| node_offer
node_publisher -->|"serializes descriptors"| node_descriptor
node_offer -.->|"feeds generations"| node_stream
node_descriptor -.->|"configures groups"| node_discovery
node_worker -->|"loads objects"| node_elf_loader
node_elf_loader -->|"resolves symbols"| node_elf_symbols
node_elf_binary -.->|"parses object input"| node_elf_loader
node_transaction -.->|"activates prepared code"| node_elf_loader
node_worker -.->|"loads objects"| node_pe_loader
node_pe_loader -->|"uses image layout"| node_pe_layout
node_application -->|"watches and updates"| node_wasm_session
node_wasm_session -->|"creates pollers"| node_wasm_poller
node_wasm_poller -->|"prepares candidates"| node_wasm_candidate
node_application -.->|"observes reload status"| node_monitor

click node_session_api "https://github.com/sentomk/nekomata/blob/main/include/neko/session.hpp"
click node_native_session "https://github.com/sentomk/nekomata/blob/main/src/runtime/native_session.cpp"
click node_discovery "https://github.com/sentomk/nekomata/blob/main/src/runtime/descriptor_discovery.cpp"
click node_worker "https://github.com/sentomk/nekomata/blob/main/src/runtime/managed_worker.cpp"
click node_stream "https://github.com/sentomk/nekomata/blob/main/src/runtime/generation_stream.cpp"
click node_transaction "https://github.com/sentomk/nekomata/blob/main/src/runtime/reload_transaction.cpp"
click node_publisher "https://github.com/sentomk/nekomata/blob/main/src/runtime/publisher.cpp"
click node_offer "https://github.com/sentomk/nekomata/blob/main/src/protocol/generation_offer.cpp"
click node_descriptor "https://github.com/sentomk/nekomata/blob/main/src/protocol/group_descriptor.cpp"
click node_elf_loader "https://github.com/sentomk/nekomata/blob/main/src/backends/elf/runtime/loader.cpp"
click node_elf_symbols "https://github.com/sentomk/nekomata/blob/main/src/backends/elf/runtime/process_symbols.hpp"
click node_elf_binary "https://github.com/sentomk/nekomata/blob/main/src/backends/elf/format/binary_file.cpp"
click node_pe_loader "https://github.com/sentomk/nekomata/blob/main/src/backends/pe/runtime/loader.cpp"
click node_pe_layout "https://github.com/sentomk/nekomata/blob/main/src/backends/pe/format/image_layout.hpp"
click node_wasm_session "https://github.com/sentomk/nekomata/blob/main/src/backends/wasm/session.cpp"
click node_wasm_poller "https://github.com/sentomk/nekomata/blob/main/src/backends/wasm/offer_poller.hpp"
click node_wasm_candidate "https://github.com/sentomk/nekomata/blob/main/src/backends/wasm/candidate.hpp"
click node_monitor "https://github.com/sentomk/nekomata/blob/main/src/tui/monitor.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_session_api,node_native_session,node_discovery,node_worker,node_stream,node_transaction toneBlue
class node_publisher,node_offer,node_descriptor toneAmber
class node_elf_loader,node_elf_symbols,node_elf_binary,node_pe_loader,node_pe_layout toneMint
class node_wasm_session,node_wasm_poller,node_wasm_candidate toneRose
class node_monitor,node_application toneIndigo
```

## Components

### Reload runtime

- [Session API](https://github.com/sentomk/nekomata/blob/main/include/neko/session.hpp): `include/neko/session.hpp`
- [Native session](https://github.com/sentomk/nekomata/blob/main/src/runtime/native_session.cpp): `src/runtime/native_session.cpp`
- [Descriptor discovery](https://github.com/sentomk/nekomata/blob/main/src/runtime/descriptor_discovery.cpp): `src/runtime/descriptor_discovery.cpp`
- [Generation preparation](https://github.com/sentomk/nekomata/blob/main/src/runtime/managed_worker.cpp): `src/runtime/managed_worker.cpp`
- [Generation stream](https://github.com/sentomk/nekomata/blob/main/src/runtime/generation_stream.cpp): `src/runtime/generation_stream.cpp`
- [Reload transaction](https://github.com/sentomk/nekomata/blob/main/src/runtime/reload_transaction.cpp): `src/runtime/reload_transaction.cpp`

### Generation protocol

- [Generation publisher](https://github.com/sentomk/nekomata/blob/main/src/runtime/publisher.cpp): `src/runtime/publisher.cpp`
- [Generation offer](https://github.com/sentomk/nekomata/blob/main/src/protocol/generation_offer.cpp): `src/protocol/generation_offer.cpp`
- [Group descriptor](https://github.com/sentomk/nekomata/blob/main/src/protocol/group_descriptor.cpp): `src/protocol/group_descriptor.cpp`

### Native backends

- [ELF object loader](https://github.com/sentomk/nekomata/blob/main/src/backends/elf/runtime/loader.cpp): `src/backends/elf/runtime/loader.cpp`
- [Process symbols](https://github.com/sentomk/nekomata/blob/main/src/backends/elf/runtime/process_symbols.hpp): `src/backends/elf/runtime/process_symbols.hpp`
- [ELF binary reader](https://github.com/sentomk/nekomata/blob/main/src/backends/elf/format/binary_file.cpp): `src/backends/elf/format/binary_file.cpp`
- [PE object loader](https://github.com/sentomk/nekomata/blob/main/src/backends/pe/runtime/loader.cpp): `src/backends/pe/runtime/loader.cpp`
- [PE image layout](https://github.com/sentomk/nekomata/blob/main/src/backends/pe/format/image_layout.hpp): `src/backends/pe/format/image_layout.hpp`

### Browser backend

- [Wasm session](https://github.com/sentomk/nekomata/blob/main/src/backends/wasm/session.cpp): `src/backends/wasm/session.cpp`
- [Offer poller](https://github.com/sentomk/nekomata/blob/main/src/backends/wasm/offer_poller.hpp): `src/backends/wasm/offer_poller.hpp`
- [Module candidate](https://github.com/sentomk/nekomata/blob/main/src/backends/wasm/candidate.hpp): `src/backends/wasm/candidate.hpp`

### Monitoring

- [TUI monitor](https://github.com/sentomk/nekomata/blob/main/src/tui/monitor.cpp): `src/tui/monitor.cpp`

### Other components

- **Application**

## Connections

- Application → Session API: watches and updates
- Session API → Native session: drives session
- Native session → Descriptor discovery: discovers descriptors (evidence: `src/runtime/native_session.cpp`)
- Native session → Generation preparation: prepares groups
- Generation preparation → Generation stream: polls generations (evidence: `src/runtime/managed_worker.cpp`)
- Generation preparation → Reload transaction: prepares reloads
- Application → Reload transaction: safe-point update
- Generation publisher → Generation offer: publishes generation
- Generation publisher → Group descriptor: serializes descriptors
- Generation offer → Generation stream: feeds generations
- Group descriptor → Descriptor discovery: configures groups
- Generation preparation → ELF object loader: loads objects
- ELF object loader → Process symbols: resolves symbols (evidence: `src/backends/elf/runtime/loader.cpp`)
- ELF binary reader → ELF object loader: parses object input
- Reload transaction → ELF object loader: activates prepared code
- Generation preparation → PE object loader: loads objects
- PE object loader → PE image layout: uses image layout (evidence: `src/backends/pe/runtime/loader.cpp`)
- Application → Wasm session: watches and updates
- Wasm session → Offer poller: creates pollers (evidence: `src/backends/wasm/session.cpp`)
- Offer poller → Module candidate: prepares candidates (evidence: `src/backends/wasm/offer_poller.hpp`)
- Application → TUI monitor: observes reload status
