# hghit-harshit/kites architecture

> Architecture diagram of the GitHub repository hghit-harshit/kites, 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/hghit-harshit/kites
- Repository: https://github.com/hghit-harshit/kites

## Overview

Kites is a RISC-V assembly editor and simulator, with a headless CLI alongside the Qt application. The primary workflow is to edit or provide assembly, assemble it into a program, load that program into a selected processor, then run or debug it while inspecting execution state and profiling results. The documented processor modes and custom cache policies are also represented. Several UI connections and processor internals were not sampled, so those links are omitted or marked unverified rather than asserted as confirmed calls.

Main entry points: [`src/processor/processor_manager.cpp`](https://github.com/hghit-harshit/kites/blob/main/src/processor/processor_manager.cpp) (Processor Manager), [`src/assembler/assembler.h`](https://github.com/hghit-harshit/kites/blob/main/src/assembler/assembler.h) (Assembler API), [`cli/main.cpp`](https://github.com/hghit-harshit/kites/blob/main/cli/main.cpp) (CLI Entry), [`src/language_service`](https://github.com/hghit-harshit/kites/tree/main/src/language_service) (Live Diagnostics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Assembly Authoring"]
  node_language["Live Diagnostics"]
  node_assembler["Assembler API<br/>[assembler.h]"]
  node_lexer["Lexer<br/>[lexer.cpp]"]
  node_parser["Parser<br/>[parser.cpp]"]
  node_codegen["Code Generator<br/>[code_generator.cpp]"]
  node_program["Assembled Program"]
end

subgraph group_execution["Simulation and Debugging"]
  node_manager["Processor Manager"]
  node_factory["Processor Factory"]
  node_processors["RISC-V Processors"]
  node_memory["Memory Controller"]
  node_cache["Cache<br/>[cache.cpp]"]
  node_profiler["Profiler<br/>[profiler.cpp]"]
end

subgraph group_interfaces["User Interfaces"]
  node_editor["Assembly Editor"]
  node_mainwindow["Desktop Window<br/>[mainwindow.cpp]"]
  node_cli["CLI Entry<br/>[main.cpp]"]
  node_commands["Command Handler"]
end

subgraph group_extensions["Configuration and Extensions"]
  node_pseudo["Pseudo Manager"]
  node_custompolicy["Custom Cache Policy"]
  node_config["Application Config<br/>[config.h]"]
end

subgraph group_lua["Lua Runtime"]
  node_lua["Lua Interpreter<br/>[src]"]
end

node_user(("Engineer"))

node_user -.->|"edits assembly"| node_editor
node_editor -.->|"requests diagnostics"| node_language
node_language -->|"checks source"| node_assembler
node_language -->|"uses expansions"| node_pseudo
node_assembler -->|"tokenizes with"| node_lexer
node_assembler -->|"parses with"| node_parser
node_parser -->|"generates code"| node_codegen
node_assembler -->|"produces"| node_program
node_user -->|"runs assembly"| node_cli
node_cli -->|"assembles file"| node_assembler
node_cli -->|"loads and runs"| node_manager
node_cli -->|"starts REPL"| node_commands
node_commands -->|"loads source"| node_assembler
node_commands -->|"executes commands"| node_manager
node_mainwindow -.->|"controls simulation"| node_manager
node_manager -->|"creates processor"| node_factory
node_manager -->|"selects variant"| node_processors
node_manager -->|"forwards clock events"| node_profiler
node_manager -->|"loads program"| node_program
node_memory -.->|"uses cache"| node_cache
node_custompolicy -->|"calls interpreter"| node_lua
node_config -.->|"configures memory"| node_memory
node_user -.->|"provides policy script"| node_custompolicy

click node_editor "https://github.com/hghit-harshit/kites/tree/main/src/ui/editor_tab"
click node_language "https://github.com/hghit-harshit/kites/tree/main/src/language_service"
click node_pseudo "https://github.com/hghit-harshit/kites/blob/main/src/custom_pseudo_manager/custom_pseudo_manager.cpp"
click node_assembler "https://github.com/hghit-harshit/kites/blob/main/src/assembler/assembler.h"
click node_lexer "https://github.com/hghit-harshit/kites/blob/main/src/assembler/lexer.cpp"
click node_parser "https://github.com/hghit-harshit/kites/blob/main/src/assembler/parser.cpp"
click node_codegen "https://github.com/hghit-harshit/kites/blob/main/src/assembler/code_generator.cpp"
click node_program "https://github.com/hghit-harshit/kites/blob/main/src/common/assembled_program.h"
click node_mainwindow "https://github.com/hghit-harshit/kites/blob/main/src/ui/mainwindow/mainwindow.cpp"
click node_cli "https://github.com/hghit-harshit/kites/blob/main/cli/main.cpp"
click node_commands "https://github.com/hghit-harshit/kites/blob/main/src/command_handler/command_handler.cpp"
click node_manager "https://github.com/hghit-harshit/kites/blob/main/src/processor/processor_manager.cpp"
click node_factory "https://github.com/hghit-harshit/kites/blob/main/src/processor/processor_factory.cpp"
click node_processors "https://github.com/hghit-harshit/kites/tree/main/src/processor/rv5s"
click node_memory "https://github.com/hghit-harshit/kites/blob/main/src/processor/memory_controller.cpp"
click node_cache "https://github.com/hghit-harshit/kites/blob/main/src/processor/cache/cache.cpp"
click node_profiler "https://github.com/hghit-harshit/kites/blob/main/src/profiler/profiler.cpp"
click node_custompolicy "https://github.com/hghit-harshit/kites/blob/main/src/processor/cache/custom_policy_engine.cpp"
click node_lua "https://github.com/hghit-harshit/kites/tree/main/external/lua-5.5.0/src"
click node_config "https://github.com/hghit-harshit/kites/blob/main/src/config/config.h"

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_language,node_assembler,node_lexer,node_parser,node_codegen,node_program toneBlue
class node_manager,node_factory,node_processors,node_memory,node_cache,node_profiler toneAmber
class node_editor,node_mainwindow,node_cli,node_commands toneMint
class node_pseudo,node_custompolicy,node_config toneRose
class node_lua,node_user toneIndigo
```

## Components

### Assembly Authoring

- [Live Diagnostics](https://github.com/hghit-harshit/kites/tree/main/src/language_service): `src/language_service`
- [Assembler API](https://github.com/hghit-harshit/kites/blob/main/src/assembler/assembler.h): `src/assembler/assembler.h`
- [Lexer](https://github.com/hghit-harshit/kites/blob/main/src/assembler/lexer.cpp): `src/assembler/lexer.cpp`
- [Parser](https://github.com/hghit-harshit/kites/blob/main/src/assembler/parser.cpp): `src/assembler/parser.cpp`
- [Code Generator](https://github.com/hghit-harshit/kites/blob/main/src/assembler/code_generator.cpp): `src/assembler/code_generator.cpp`
- [Assembled Program](https://github.com/hghit-harshit/kites/blob/main/src/common/assembled_program.h): `src/common/assembled_program.h`

### Simulation and Debugging

- [Processor Manager](https://github.com/hghit-harshit/kites/blob/main/src/processor/processor_manager.cpp): `src/processor/processor_manager.cpp`
- [Processor Factory](https://github.com/hghit-harshit/kites/blob/main/src/processor/processor_factory.cpp): `src/processor/processor_factory.cpp`
- [RISC-V Processors](https://github.com/hghit-harshit/kites/tree/main/src/processor/rv5s): `src/processor/rv5s`
- [Memory Controller](https://github.com/hghit-harshit/kites/blob/main/src/processor/memory_controller.cpp): `src/processor/memory_controller.cpp`
- [Cache](https://github.com/hghit-harshit/kites/blob/main/src/processor/cache/cache.cpp): `src/processor/cache/cache.cpp`
- [Profiler](https://github.com/hghit-harshit/kites/blob/main/src/profiler/profiler.cpp): `src/profiler/profiler.cpp`

### User Interfaces

- [Assembly Editor](https://github.com/hghit-harshit/kites/tree/main/src/ui/editor_tab): `src/ui/editor_tab`
- [Desktop Window](https://github.com/hghit-harshit/kites/blob/main/src/ui/mainwindow/mainwindow.cpp): `src/ui/mainwindow/mainwindow.cpp`
- [CLI Entry](https://github.com/hghit-harshit/kites/blob/main/cli/main.cpp): `cli/main.cpp`
- [Command Handler](https://github.com/hghit-harshit/kites/blob/main/src/command_handler/command_handler.cpp): `src/command_handler/command_handler.cpp`

### Configuration and Extensions

- [Pseudo Manager](https://github.com/hghit-harshit/kites/blob/main/src/custom_pseudo_manager/custom_pseudo_manager.cpp): `src/custom_pseudo_manager/custom_pseudo_manager.cpp`
- [Custom Cache Policy](https://github.com/hghit-harshit/kites/blob/main/src/processor/cache/custom_policy_engine.cpp): `src/processor/cache/custom_policy_engine.cpp`
- [Application Config](https://github.com/hghit-harshit/kites/blob/main/src/config/config.h): `src/config/config.h`

### Lua Runtime

- [Lua Interpreter](https://github.com/hghit-harshit/kites/tree/main/external/lua-5.5.0/src): `external/lua-5.5.0/src`

### Other components

- **Engineer**

## Connections

- Engineer → Assembly Editor: edits assembly
- Assembly Editor → Live Diagnostics: requests diagnostics
- Live Diagnostics → Assembler API: checks source (evidence: `src/language_service/language_service.cpp`)
- Live Diagnostics → Pseudo Manager: uses expansions (evidence: `src/language_service/language_service.cpp`)
- Assembler API → Lexer: tokenizes with (evidence: `src/assembler/assembler.h`)
- Assembler API → Parser: parses with (evidence: `src/assembler/assembler.h`)
- Parser → Code Generator: generates code
- Assembler API → Assembled Program: produces (evidence: `src/assembler/assembler.h`)
- Engineer → CLI Entry: runs assembly (evidence: `cli/main.cpp`)
- CLI Entry → Assembler API: assembles file (evidence: `cli/main.cpp`)
- CLI Entry → Processor Manager: loads and runs (evidence: `cli/main.cpp`)
- CLI Entry → Command Handler: starts REPL (evidence: `cli/main.cpp`)
- Command Handler → Assembler API: loads source (evidence: `src/command_handler/command_handler.cpp`)
- Command Handler → Processor Manager: executes commands
- Desktop Window → Processor Manager: controls simulation
- Processor Manager → Processor Factory: creates processor (evidence: `src/processor/processor_manager.cpp`)
- Processor Manager → RISC-V Processors: selects variant (evidence: `src/processor/processor_manager.cpp`)
- Processor Manager → Profiler: forwards clock events (evidence: `src/processor/processor_manager.cpp`)
- Processor Manager → Assembled Program: loads program (evidence: `src/processor/processor_manager.cpp`)
- Memory Controller → Cache: uses cache
- Custom Cache Policy → Lua Interpreter: calls interpreter (evidence: `src/processor/cache/custom_policy_engine.cpp`)
- Application Config → Memory Controller: configures memory
- Engineer → Custom Cache Policy: provides policy script
