# leonardo-alegria/garlic-llm architecture

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

- Interactive diagram: https://gitdiagram.com/leonardo-alegria/garlic-llm
- Repository: https://github.com/leonardo-alegria/garlic-llm

## Overview

Garlic LLM is an offline PS4 chat application: controller or API requests reach the console-side coordinator, which tokenizes prompts and drives GPU inference; optional branches add dictation, spoken replies, and execution of generated Python. The graph also preserves model-kernel execution, API serving, and the embedded MicroPython runtime. Relationships are limited to README statements and shown source references/calls; unsampled voice and API internals are represented at subsystem level rather than with guessed internal steps.

Main entry points: [`chat/main.c`](https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/main.c) (App Coordinator), [`chat/engine.c`](https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/engine.c) (GPU Model Engine), [`chat/py/mp/port/embed_util.c`](https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/py/mp/port/embed_util.c) (MicroPython Embed), [`chat/api.c`](https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/api.c) (OpenAI API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_chat["Chat and UI"]
  node_main["App Coordinator<br/>[main.c]"]
  node_ui["Chat Interface<br/>[ui.c]"]
  node_tokenizer["Text Tokenizer<br/>[tokenizer.c]"]
end

subgraph group_inference["Model Inference"]
  node_engine["GPU Model Engine<br/>[engine.c]"]
  node_kernels["Compute Kernels<br/>[attn.h]"]
  node_model_weights[("Model Weights")]
end

subgraph group_voice["Voice Features"]
  node_dictation["Speech Recognition<br/>[speech_norm.c]"]
  node_speech_text["Speech Text<br/>[speech_text.c]"]
  node_tts_tokens["Speech Tokens<br/>[tts_tok.c]"]
  node_audio["Audio Output<br/>[audio_out.c]"]
end

subgraph group_api["Network API"]
  node_api_server["OpenAI API<br/>[api.c]"]
  node_api_protocol["API Protocol<br/>[api_proto.c]"]
end

subgraph group_python["Python Runtime"]
  node_python_runner["Python Runner<br/>[pyrun.c]"]
  node_mp_embed["MicroPython Embed<br/>[embed_util.c]"]
  node_mp_compile["Python Compiler<br/>[compile.c]"]
  node_mp_runtime["Python Runtime<br/>[runtime.c]"]
  node_mp_vm["Bytecode VM<br/>[vm.c]"]
end

node_controller(("PS4 User"))
node_api_client(("API Client"))
node_microphone(("Microphone"))

node_controller -->|"controls"| node_main
node_main -->|"updates display"| node_ui
node_main -->|"tokenizes prompts"| node_tokenizer
node_main -->|"requests generation"| node_engine
node_engine -->|"dispatches kernels"| node_kernels
node_engine -->|"reads weights"| node_model_weights
node_microphone -->|"provides audio"| node_main
node_main -->|"runs recognition"| node_dictation
node_main -.->|"normalizes speech"| node_speech_text
node_main -.->|"prepares speech"| node_tts_tokens
node_main -.->|"plays reply"| node_audio
node_api_client -->|"sends requests"| node_api_server
node_main -->|"serves API"| node_api_server
node_api_server -.->|"uses protocol"| node_api_protocol
node_main -->|"runs program"| node_python_runner
node_python_runner -.->|"executes scripts"| node_mp_embed
node_mp_embed -->|"compiles source"| node_mp_compile
node_mp_embed -->|"initializes runtime"| node_mp_runtime
node_mp_runtime -.->|"executes bytecode"| node_mp_vm

click node_main "https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/main.c"
click node_ui "https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/ui.c"
click node_tokenizer "https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/tokenizer.c"
click node_engine "https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/engine.c"
click node_kernels "https://github.com/leonardo-alegria/garlic-llm/blob/main/shaders/attn.h"
click node_dictation "https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/speech_norm.c"
click node_speech_text "https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/speech_text.c"
click node_tts_tokens "https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/tts_tok.c"
click node_audio "https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/audio_out.c"
click node_api_server "https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/api.c"
click node_api_protocol "https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/api_proto.c"
click node_python_runner "https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/pyrun.c"
click node_mp_embed "https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/py/mp/port/embed_util.c"
click node_mp_compile "https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/py/mp/py/compile.c"
click node_mp_runtime "https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/py/mp/py/runtime.c"
click node_mp_vm "https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/py/mp/py/vm.c"

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_main,node_ui,node_tokenizer,node_controller,node_api_client toneBlue
class node_engine,node_kernels,node_model_weights toneAmber
class node_dictation,node_speech_text,node_tts_tokens,node_audio toneMint
class node_api_server,node_api_protocol toneRose
class node_python_runner,node_mp_embed,node_mp_compile,node_mp_runtime,node_mp_vm,node_microphone toneIndigo
```

## Components

### Chat and UI

- [App Coordinator](https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/main.c): `chat/main.c`
- [Chat Interface](https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/ui.c): `chat/ui.c`
- [Text Tokenizer](https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/tokenizer.c): `chat/tokenizer.c`

### Model Inference

- [GPU Model Engine](https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/engine.c): `chat/engine.c`
- [Compute Kernels](https://github.com/leonardo-alegria/garlic-llm/blob/main/shaders/attn.h): `shaders/attn.h`
- **Model Weights**

### Voice Features

- [Speech Recognition](https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/speech_norm.c): `chat/speech_norm.c`
- [Speech Text](https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/speech_text.c): `chat/speech_text.c`
- [Speech Tokens](https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/tts_tok.c): `chat/tts_tok.c`
- [Audio Output](https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/audio_out.c): `chat/audio_out.c`

### Network API

- [OpenAI API](https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/api.c): `chat/api.c`
- [API Protocol](https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/api_proto.c): `chat/api_proto.c`

### Python Runtime

- [Python Runner](https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/pyrun.c): `chat/pyrun.c`
- [MicroPython Embed](https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/py/mp/port/embed_util.c): `chat/py/mp/port/embed_util.c`
- [Python Compiler](https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/py/mp/py/compile.c): `chat/py/mp/py/compile.c`
- [Python Runtime](https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/py/mp/py/runtime.c): `chat/py/mp/py/runtime.c`
- [Bytecode VM](https://github.com/leonardo-alegria/garlic-llm/blob/main/chat/py/mp/py/vm.c): `chat/py/mp/py/vm.c`

### Other components

- **PS4 User**
- **API Client**
- **Microphone**

## Connections

- PS4 User → App Coordinator: controls (evidence: `README.md`)
- App Coordinator → Chat Interface: updates display (evidence: `chat/main.c`)
- App Coordinator → Text Tokenizer: tokenizes prompts (evidence: `chat/main.c`)
- App Coordinator → GPU Model Engine: requests generation (evidence: `chat/main.c`)
- GPU Model Engine → Compute Kernels: dispatches kernels (evidence: `README.md`)
- GPU Model Engine → Model Weights: reads weights (evidence: `chat/engine.c`)
- Microphone → App Coordinator: provides audio (evidence: `README.md`)
- App Coordinator → Speech Recognition: runs recognition (evidence: `README.md`)
- App Coordinator → Speech Text: normalizes speech
- App Coordinator → Speech Tokens: prepares speech
- App Coordinator → Audio Output: plays reply
- API Client → OpenAI API: sends requests (evidence: `README.md`)
- App Coordinator → OpenAI API: serves API (evidence: `chat/main.c`)
- OpenAI API → API Protocol: uses protocol
- App Coordinator → Python Runner: runs program (evidence: `README.md`)
- Python Runner → MicroPython Embed: executes scripts
- MicroPython Embed → Python Compiler: compiles source (evidence: `chat/py/mp/port/embed_util.c`)
- MicroPython Embed → Python Runtime: initializes runtime (evidence: `chat/py/mp/port/embed_util.c`)
- Python Runtime → Bytecode VM: executes bytecode
