# kalkiii1511/kites architecture

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

- Interactive diagram: https://gitdiagram.com/kalkiii1511/kites
- Repository: https://github.com/kalkiii1511/kites

## Overview

Kites is a RISC-V assembly editor and simulator, with a headless CLI. The main workflow is to edit or load assembly, assemble it into a program, load that program into a selected processor, then run or debug it while viewing machine state and profiling results. The repository also provides live language diagnostics, custom pseudo-instructions, cache configuration and Lua-backed custom replacement policies. Edges are limited to relationships shown in the README or source index and excerpts; UI internals and several processor/memory interactions are not sampled.

Main entry points: [`src/processor/processor_manager.cpp`](https://github.com/kalkiii1511/kites/blob/main/src/processor/processor_manager.cpp) (Processor manager), [`src/assembler/assembler.cpp`](https://github.com/kalkiii1511/kites/blob/main/src/assembler/assembler.cpp) (Assembler), [`cli/main.cpp`](https://github.com/kalkiii1511/kites/blob/main/cli/main.cpp) (CLI), [`src/processor/memory_controller.cpp`](https://github.com/kalkiii1511/kites/blob/main/src/processor/memory_controller.cpp) (Memory controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_desktop["Desktop UI<br/>[main.cpp]"]
  node_editor["Assembly editor"]
  node_cli["CLI<br/>[main.cpp]"]
  node_repl["Command REPL<br/>[repl.cpp]"]
  node_commands["Command handler"]
end

subgraph group_assembly["Assembly tools"]
  node_assembler["Assembler<br/>[assembler.cpp]"]
  node_lexer["Lexer<br/>[lexer.cpp]"]
  node_parser["Parser<br/>[parser.cpp]"]
  node_pseudo["Custom pseudos"]
  node_language["Language service"]
  node_program["Assembled program"]
end

subgraph group_execution["Simulation runtime"]
  node_manager["Processor manager"]
  node_factory["Processor factory"]
  node_processors["RISC-V processors<br/>[rvss_processor.cpp]"]
  node_memory["Memory controller"]
  node_cache["Cache<br/>[cache.cpp]"]
end

subgraph group_insight["Runtime views"]
  node_profiler["Profiler<br/>[profiler.cpp]"]
  node_processor_view["Processor view<br/>[processortab.cpp]"]
  node_memory_view["Memory view<br/>[memorytab.cpp]"]
  node_cache_view["Cache view<br/>[cachetab.cpp]"]
  node_profiler_view["Profiler view<br/>[profilertab.cpp]"]
end

subgraph group_extensions["Configuration and extensions"]
  node_config["App configuration<br/>[config.cpp]"]
  node_cache_policy["Custom cache policy"]
  node_lua["Lua runtime<br/>[src]"]
  node_themes["Theme manager<br/>[theme_manager.cpp]"]
end

node_user(("Engineer"))

node_user -->|"opens"| node_desktop
node_user -->|"runs"| node_cli
node_desktop -.->|"presents"| node_editor
node_cli -->|"assembles"| node_assembler
node_cli -->|"runs through"| node_manager
node_cli -->|"enters"| node_repl
node_repl -.->|"dispatches"| node_commands
node_commands -->|"loads via"| node_assembler
node_commands -->|"controls"| node_manager
node_assembler -->|"uses"| node_lexer
node_assembler -->|"uses"| node_parser
node_parser -->|"produces"| node_program
node_language -->|"checks source with"| node_assembler
node_language -->|"uses"| node_pseudo
node_manager -->|"loads"| node_program
node_manager -->|"creates via"| node_factory
node_manager -->|"selects"| node_processors
node_manager -->|"forwards clock events"| node_profiler
node_memory -.->|"uses"| node_cache
node_memory -.->|"reads configuration"| node_config
node_cache_policy -->|"calls"| node_lua
node_profiler -.->|"shown in"| node_profiler_view
node_manager -.->|"updates"| node_processor_view
node_memory -.->|"displayed by"| node_memory_view
node_cache -.->|"displayed by"| node_cache_view
node_user -.->|"customizes appearance"| node_themes

click node_desktop "https://github.com/kalkiii1511/kites/blob/main/main.cpp"
click node_editor "https://github.com/kalkiii1511/kites/tree/main/src/ui/editor_tab"
click node_cli "https://github.com/kalkiii1511/kites/blob/main/cli/main.cpp"
click node_repl "https://github.com/kalkiii1511/kites/blob/main/cli/repl.cpp"
click node_assembler "https://github.com/kalkiii1511/kites/blob/main/src/assembler/assembler.cpp"
click node_lexer "https://github.com/kalkiii1511/kites/blob/main/src/assembler/lexer.cpp"
click node_parser "https://github.com/kalkiii1511/kites/blob/main/src/assembler/parser.cpp"
click node_pseudo "https://github.com/kalkiii1511/kites/blob/main/src/custom_pseudo_manager/custom_pseudo_manager.cpp"
click node_language "https://github.com/kalkiii1511/kites/blob/main/src/language_service/language_service.cpp"
click node_program "https://github.com/kalkiii1511/kites/blob/main/src/common/assembled_program.h"
click node_commands "https://github.com/kalkiii1511/kites/blob/main/src/command_handler/command_handler.cpp"
click node_manager "https://github.com/kalkiii1511/kites/blob/main/src/processor/processor_manager.cpp"
click node_factory "https://github.com/kalkiii1511/kites/blob/main/src/processor/processor_factory.cpp"
click node_processors "https://github.com/kalkiii1511/kites/blob/main/src/processor/rvss/rvss_processor.cpp"
click node_memory "https://github.com/kalkiii1511/kites/blob/main/src/processor/memory_controller.cpp"
click node_cache "https://github.com/kalkiii1511/kites/blob/main/src/processor/cache/cache.cpp"
click node_profiler "https://github.com/kalkiii1511/kites/blob/main/src/profiler/profiler.cpp"
click node_processor_view "https://github.com/kalkiii1511/kites/blob/main/src/ui/processor_tab/processortab.cpp"
click node_memory_view "https://github.com/kalkiii1511/kites/blob/main/src/ui/memory_tab/memorytab.cpp"
click node_cache_view "https://github.com/kalkiii1511/kites/blob/main/src/ui/cache_tab/cachetab.cpp"
click node_profiler_view "https://github.com/kalkiii1511/kites/blob/main/src/ui/profiler_tab/profilertab.cpp"
click node_config "https://github.com/kalkiii1511/kites/blob/main/src/config/config.cpp"
click node_cache_policy "https://github.com/kalkiii1511/kites/blob/main/src/processor/cache/custom_policy_engine.cpp"
click node_lua "https://github.com/kalkiii1511/kites/tree/main/external/lua-5.5.0/src"
click node_themes "https://github.com/kalkiii1511/kites/blob/main/src/ui/theme/theme_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_desktop,node_editor,node_cli,node_repl,node_commands toneBlue
class node_assembler,node_lexer,node_parser,node_pseudo,node_language,node_program toneAmber
class node_manager,node_factory,node_processors,node_memory,node_cache toneMint
class node_profiler,node_processor_view,node_memory_view,node_cache_view,node_profiler_view toneRose
class node_config,node_cache_policy,node_lua,node_themes,node_user toneIndigo
```

## Components

### User entry points

- [Desktop UI](https://github.com/kalkiii1511/kites/blob/main/main.cpp): `main.cpp`
- [Assembly editor](https://github.com/kalkiii1511/kites/tree/main/src/ui/editor_tab): `src/ui/editor_tab`
- [CLI](https://github.com/kalkiii1511/kites/blob/main/cli/main.cpp): `cli/main.cpp`
- [Command REPL](https://github.com/kalkiii1511/kites/blob/main/cli/repl.cpp): `cli/repl.cpp`
- [Command handler](https://github.com/kalkiii1511/kites/blob/main/src/command_handler/command_handler.cpp): `src/command_handler/command_handler.cpp`

### Assembly tools

- [Assembler](https://github.com/kalkiii1511/kites/blob/main/src/assembler/assembler.cpp): `src/assembler/assembler.cpp`
- [Lexer](https://github.com/kalkiii1511/kites/blob/main/src/assembler/lexer.cpp): `src/assembler/lexer.cpp`
- [Parser](https://github.com/kalkiii1511/kites/blob/main/src/assembler/parser.cpp): `src/assembler/parser.cpp`
- [Custom pseudos](https://github.com/kalkiii1511/kites/blob/main/src/custom_pseudo_manager/custom_pseudo_manager.cpp): `src/custom_pseudo_manager/custom_pseudo_manager.cpp`
- [Language service](https://github.com/kalkiii1511/kites/blob/main/src/language_service/language_service.cpp): `src/language_service/language_service.cpp`
- [Assembled program](https://github.com/kalkiii1511/kites/blob/main/src/common/assembled_program.h): `src/common/assembled_program.h`

### Simulation runtime

- [Processor manager](https://github.com/kalkiii1511/kites/blob/main/src/processor/processor_manager.cpp): `src/processor/processor_manager.cpp`
- [Processor factory](https://github.com/kalkiii1511/kites/blob/main/src/processor/processor_factory.cpp): `src/processor/processor_factory.cpp`
- [RISC-V processors](https://github.com/kalkiii1511/kites/blob/main/src/processor/rvss/rvss_processor.cpp): `src/processor/rvss/rvss_processor.cpp`
- [Memory controller](https://github.com/kalkiii1511/kites/blob/main/src/processor/memory_controller.cpp): `src/processor/memory_controller.cpp`
- [Cache](https://github.com/kalkiii1511/kites/blob/main/src/processor/cache/cache.cpp): `src/processor/cache/cache.cpp`

### Runtime views

- [Profiler](https://github.com/kalkiii1511/kites/blob/main/src/profiler/profiler.cpp): `src/profiler/profiler.cpp`
- [Processor view](https://github.com/kalkiii1511/kites/blob/main/src/ui/processor_tab/processortab.cpp): `src/ui/processor_tab/processortab.cpp`
- [Memory view](https://github.com/kalkiii1511/kites/blob/main/src/ui/memory_tab/memorytab.cpp): `src/ui/memory_tab/memorytab.cpp`
- [Cache view](https://github.com/kalkiii1511/kites/blob/main/src/ui/cache_tab/cachetab.cpp): `src/ui/cache_tab/cachetab.cpp`
- [Profiler view](https://github.com/kalkiii1511/kites/blob/main/src/ui/profiler_tab/profilertab.cpp): `src/ui/profiler_tab/profilertab.cpp`

### Configuration and extensions

- [App configuration](https://github.com/kalkiii1511/kites/blob/main/src/config/config.cpp): `src/config/config.cpp`
- [Custom cache policy](https://github.com/kalkiii1511/kites/blob/main/src/processor/cache/custom_policy_engine.cpp): `src/processor/cache/custom_policy_engine.cpp`
- [Lua runtime](https://github.com/kalkiii1511/kites/tree/main/external/lua-5.5.0/src): `external/lua-5.5.0/src`
- [Theme manager](https://github.com/kalkiii1511/kites/blob/main/src/ui/theme/theme_manager.cpp): `src/ui/theme/theme_manager.cpp`

### Other components

- **Engineer**

## Connections

- Engineer → Desktop UI: opens
- Engineer → CLI: runs
- Desktop UI → Assembly editor: presents
- CLI → Assembler: assembles (evidence: `cli/main.cpp`)
- CLI → Processor manager: runs through (evidence: `cli/main.cpp`)
- CLI → Command REPL: enters (evidence: `cli/main.cpp`)
- Command REPL → Command handler: dispatches
- Command handler → Assembler: loads via (evidence: `src/command_handler/command_handler.cpp`)
- Command handler → Processor manager: controls
- Assembler → Lexer: uses
- Assembler → Parser: uses
- Parser → Assembled program: produces (evidence: `src/common/assembled_program.h`)
- Language service → Assembler: checks source with (evidence: `src/language_service/language_service.cpp`)
- Language service → Custom pseudos: uses (evidence: `src/language_service/language_service.cpp`)
- Processor manager → Assembled program: loads (evidence: `src/processor/processor_manager.cpp`)
- Processor manager → Processor factory: creates via (evidence: `src/processor/processor_manager.cpp`)
- Processor manager → RISC-V processors: selects (evidence: `src/processor/processor_manager.cpp`)
- Processor manager → Profiler: forwards clock events (evidence: `src/processor/processor_manager.cpp`)
- Memory controller → Cache: uses
- Memory controller → App configuration: reads configuration
- Custom cache policy → Lua runtime: calls (evidence: `src/processor/cache/custom_policy_engine.cpp`)
- Profiler → Profiler view: shown in
- Processor manager → Processor view: updates
- Memory controller → Memory view: displayed by
- Cache → Cache view: displayed by
- Engineer → Theme manager: customizes appearance
