# jonimoni09/hydra-stone architecture

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

- Interactive diagram: https://gitdiagram.com/jonimoni09/hydra-stone
- Repository: https://github.com/jonimoni09/hydra-stone

## Overview

Hydra-Stone combines two model formats and inference paths with a CLI, web console, Android app, and model-conversion/training workflows. The v1 engine runs ternary `.hydra` weights; the v2 container and MoE engine support transformer-style inference. The README documents the major cross-surface capabilities, while source excerpts are partial, so some connections below rely on that documentation and uncertain native wiring is omitted or marked unverified.

Main entry points: [`src/main.c`](https://github.com/jonimoni09/hydra-stone/blob/main/src/main.c) (CLI runner), [`server.js`](https://github.com/jonimoni09/hydra-stone/blob/main/server.js) (Console server), [`android/app/src/main/java/dev/hydrastone/MainActivity.kt`](https://github.com/jonimoni09/hydra-stone/blob/main/android/app/src/main/java/dev/hydrastone/MainActivity.kt) (App coordinator), [`android/app/src/main/java/dev/hydrastone/EngineInterface.kt`](https://github.com/jonimoni09/hydra-stone/blob/main/android/app/src/main/java/dev/hydrastone/EngineInterface.kt) (Engine interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_models["Model preparation"]
  node_converter["GGUF converters<br/>[gguf_to_hydra2.py]"]
  node_reader["GGUF reader<br/>[gguf_reader.py]"]
  node_trainer["Model training<br/>[hydra_train.js]"]
end

subgraph group_runtime["Inference runtime"]
  node_hydra1["V1 engine<br/>[hydra_engine.c]"]
  node_container[("V2 container")]
  node_moe["MoE engine<br/>[hydra_moe.c]"]
  node_cli["CLI runner<br/>[main.c]"]
end

subgraph group_console["Web console"]
  node_webui["Web console UI<br/>[app.js]"]
  node_server["Console server<br/>[server.js]"]
end

subgraph group_android["Android app"]
  node_androidui["Chat UI<br/>[HydraApp.kt]"]
  node_activity["App coordinator<br/>[MainActivity.kt]"]
  node_engineapi["Engine interface<br/>[EngineInterface.kt]"]
  node_hydraapp["Android Hydra engine<br/>[HydraEngine.kt]"]
  node_llamaapp["Android llama engine<br/>[LlamaEngine.kt]"]
  node_hydra_bridge["Hydra JNI bridge<br/>[HydraBridge.kt]"]
  node_llama_bridge["Llama JNI bridge<br/>[LlamaBridge.kt]"]
  node_hydra_jni["Native Hydra JNI<br/>[hydra_jni.c]"]
  node_llama_jni["Native llama JNI<br/>[llama_jni.cpp]"]
end

node_user(("User"))
node_corpus["Training corpus"]
node_gguf["GGUF model"]

node_user -->|"runs inference"| node_cli
node_gguf -->|"decodes tensors"| node_reader
node_reader -->|"supplies decoding"| node_converter
node_gguf -->|"converts model"| node_converter
node_corpus -->|"trains model"| node_trainer
node_user -->|"uses console"| node_server
node_server -->|"serves UI"| node_webui
node_webui -->|"calls API"| node_server
node_server -->|"invokes training"| node_trainer
node_server -->|"runs engine"| node_cli
node_cli -->|"runs v1 inference"| node_hydra1
node_cli -->|"inspects v2"| node_container
node_cli -->|"runs v2 inference"| node_moe
node_container -->|"provides model data"| node_moe
node_user -->|"uses app"| node_activity
node_activity -->|"hosts UI"| node_androidui
node_activity -->|"selects engine"| node_engineapi
node_hydraapp -->|"implements"| node_engineapi
node_llamaapp -->|"implements"| node_engineapi
node_hydraapp -->|"calls bridge"| node_hydra_bridge
node_llamaapp -->|"calls bridge"| node_llama_bridge
node_hydra_bridge -.->|"native dispatch"| node_hydra_jni
node_llama_bridge -.->|"native dispatch"| node_llama_jni

click node_converter "https://github.com/jonimoni09/hydra-stone/blob/main/tools/gguf_to_hydra2.py"
click node_reader "https://github.com/jonimoni09/hydra-stone/blob/main/tools/gguf_reader.py"
click node_trainer "https://github.com/jonimoni09/hydra-stone/blob/main/tools/hydra_train.js"
click node_hydra1 "https://github.com/jonimoni09/hydra-stone/blob/main/src/hydra_engine.c"
click node_container "https://github.com/jonimoni09/hydra-stone/blob/main/src/hydra_v2_container.c"
click node_moe "https://github.com/jonimoni09/hydra-stone/blob/main/src/hydra_moe.c"
click node_cli "https://github.com/jonimoni09/hydra-stone/blob/main/src/main.c"
click node_webui "https://github.com/jonimoni09/hydra-stone/blob/main/public/app.js"
click node_server "https://github.com/jonimoni09/hydra-stone/blob/main/server.js"
click node_androidui "https://github.com/jonimoni09/hydra-stone/blob/main/android/app/src/main/java/dev/hydrastone/ui/HydraApp.kt"
click node_activity "https://github.com/jonimoni09/hydra-stone/blob/main/android/app/src/main/java/dev/hydrastone/MainActivity.kt"
click node_engineapi "https://github.com/jonimoni09/hydra-stone/blob/main/android/app/src/main/java/dev/hydrastone/EngineInterface.kt"
click node_hydraapp "https://github.com/jonimoni09/hydra-stone/blob/main/android/app/src/main/java/dev/hydrastone/HydraEngine.kt"
click node_llamaapp "https://github.com/jonimoni09/hydra-stone/blob/main/android/app/src/main/java/dev/hydrastone/LlamaEngine.kt"
click node_hydra_bridge "https://github.com/jonimoni09/hydra-stone/blob/main/android/app/src/main/java/dev/hydrastone/HydraBridge.kt"
click node_llama_bridge "https://github.com/jonimoni09/hydra-stone/blob/main/android/app/src/main/java/dev/hydrastone/LlamaBridge.kt"
click node_hydra_jni "https://github.com/jonimoni09/hydra-stone/blob/main/android/app/src/main/cpp/hydra_jni.c"
click node_llama_jni "https://github.com/jonimoni09/hydra-stone/blob/main/android/app/src/main/cpp/llama_jni.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_converter,node_reader,node_trainer,node_user toneBlue
class node_hydra1,node_container,node_moe,node_cli toneAmber
class node_webui,node_server toneMint
class node_androidui,node_activity,node_engineapi,node_hydraapp,node_llamaapp,node_hydra_bridge,node_llama_bridge,node_hydra_jni,node_llama_jni toneRose
class node_corpus,node_gguf toneIndigo
```

## Components

### Model preparation

- [GGUF converters](https://github.com/jonimoni09/hydra-stone/blob/main/tools/gguf_to_hydra2.py): `tools/gguf_to_hydra2.py`
- [GGUF reader](https://github.com/jonimoni09/hydra-stone/blob/main/tools/gguf_reader.py): `tools/gguf_reader.py`
- [Model training](https://github.com/jonimoni09/hydra-stone/blob/main/tools/hydra_train.js): `tools/hydra_train.js`

### Inference runtime

- [V1 engine](https://github.com/jonimoni09/hydra-stone/blob/main/src/hydra_engine.c): `src/hydra_engine.c`
- [V2 container](https://github.com/jonimoni09/hydra-stone/blob/main/src/hydra_v2_container.c): `src/hydra_v2_container.c`
- [MoE engine](https://github.com/jonimoni09/hydra-stone/blob/main/src/hydra_moe.c): `src/hydra_moe.c`
- [CLI runner](https://github.com/jonimoni09/hydra-stone/blob/main/src/main.c): `src/main.c`

### Web console

- [Web console UI](https://github.com/jonimoni09/hydra-stone/blob/main/public/app.js): `public/app.js`
- [Console server](https://github.com/jonimoni09/hydra-stone/blob/main/server.js): `server.js`

### Android app

- [Chat UI](https://github.com/jonimoni09/hydra-stone/blob/main/android/app/src/main/java/dev/hydrastone/ui/HydraApp.kt): `android/app/src/main/java/dev/hydrastone/ui/HydraApp.kt`
- [App coordinator](https://github.com/jonimoni09/hydra-stone/blob/main/android/app/src/main/java/dev/hydrastone/MainActivity.kt): `android/app/src/main/java/dev/hydrastone/MainActivity.kt`
- [Engine interface](https://github.com/jonimoni09/hydra-stone/blob/main/android/app/src/main/java/dev/hydrastone/EngineInterface.kt): `android/app/src/main/java/dev/hydrastone/EngineInterface.kt`
- [Android Hydra engine](https://github.com/jonimoni09/hydra-stone/blob/main/android/app/src/main/java/dev/hydrastone/HydraEngine.kt): `android/app/src/main/java/dev/hydrastone/HydraEngine.kt`
- [Android llama engine](https://github.com/jonimoni09/hydra-stone/blob/main/android/app/src/main/java/dev/hydrastone/LlamaEngine.kt): `android/app/src/main/java/dev/hydrastone/LlamaEngine.kt`
- [Hydra JNI bridge](https://github.com/jonimoni09/hydra-stone/blob/main/android/app/src/main/java/dev/hydrastone/HydraBridge.kt): `android/app/src/main/java/dev/hydrastone/HydraBridge.kt`
- [Llama JNI bridge](https://github.com/jonimoni09/hydra-stone/blob/main/android/app/src/main/java/dev/hydrastone/LlamaBridge.kt): `android/app/src/main/java/dev/hydrastone/LlamaBridge.kt`
- [Native Hydra JNI](https://github.com/jonimoni09/hydra-stone/blob/main/android/app/src/main/cpp/hydra_jni.c): `android/app/src/main/cpp/hydra_jni.c`
- [Native llama JNI](https://github.com/jonimoni09/hydra-stone/blob/main/android/app/src/main/cpp/llama_jni.cpp): `android/app/src/main/cpp/llama_jni.cpp`

### Other components

- **User**
- **Training corpus**
- **GGUF model**

## Connections

- User → CLI runner: runs inference
- GGUF model → GGUF reader: decodes tensors
- GGUF reader → GGUF converters: supplies decoding (evidence: `tools/gguf_to_hydra2.py`)
- GGUF model → GGUF converters: converts model
- Training corpus → Model training: trains model
- User → Console server: uses console
- Console server → Web console UI: serves UI
- Web console UI → Console server: calls API
- Console server → Model training: invokes training (evidence: `server.js`)
- Console server → CLI runner: runs engine
- CLI runner → V1 engine: runs v1 inference
- CLI runner → V2 container: inspects v2 (evidence: `src/main.c`)
- CLI runner → MoE engine: runs v2 inference (evidence: `src/main.c`)
- V2 container → MoE engine: provides model data (evidence: `src/hydra_moe.c`)
- User → App coordinator: uses app
- App coordinator → Chat UI: hosts UI (evidence: `android/app/src/main/java/dev/hydrastone/MainActivity.kt`)
- App coordinator → Engine interface: selects engine (evidence: `android/app/src/main/java/dev/hydrastone/MainActivity.kt`)
- Android Hydra engine → Engine interface: implements (evidence: `android/app/src/main/java/dev/hydrastone/HydraEngine.kt`)
- Android llama engine → Engine interface: implements (evidence: `android/app/src/main/java/dev/hydrastone/LlamaEngine.kt`)
- Android Hydra engine → Hydra JNI bridge: calls bridge (evidence: `android/app/src/main/java/dev/hydrastone/HydraEngine.kt`)
- Android llama engine → Llama JNI bridge: calls bridge (evidence: `android/app/src/main/java/dev/hydrastone/LlamaEngine.kt`)
- Hydra JNI bridge → Native Hydra JNI: native dispatch
- Llama JNI bridge → Native llama JNI: native dispatch
