# dont-rely-on-nulls/karuta architecture

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

- Interactive diagram: https://gitdiagram.com/dont-rely-on-nulls/karuta
- Repository: https://github.com/dont-rely-on-nulls/karuta

## Overview

Karuta is a semi-toy relational programming language. Its documented workflow is to parse and compile Karuta programs, produce BEAM assembly, and use `erlc` as part of the toolchain; its BEAM runtime provides logic variables and backtracking. The repository also includes module support and a Sakura-related integration that the README marks incomplete. Source excerpts were not available, so internal call order and ownership are not established here; dashed edges indicate those unverified links rather than inspected behavior.

Main entry points: [`lib/cli.ml`](https://github.com/dont-rely-on-nulls/karuta/blob/master/lib/cli.ml) (Command Line), [`lib/shared/Compiler.ml`](https://github.com/dont-rely-on-nulls/karuta/blob/master/lib/shared/Compiler.ml) (Compiler), [`lib/Parser.ml`](https://github.com/dont-rely-on-nulls/karuta/blob/master/lib/Parser.ml) (Parser), [`lib/beam/builder.ml`](https://github.com/dont-rely-on-nulls/karuta/blob/master/lib/beam/builder.ml) (BEAM Builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Language Frontend"]
  node_parser["Parser<br/>[Parser.ml]"]
  node_ast["Language AST<br/>[Ast.ml]"]
end

subgraph group_modules["Modules"]
  node_module_support["Module Support<br/>[Module.ml]"]
  node_sakura_support["Sakura Integration"]
end

subgraph group_backend["BEAM Toolchain"]
  node_cli["Command Line<br/>[cli.ml]"]
  node_compiler["Compiler<br/>[Compiler.ml]"]
  node_beam_builder["BEAM Builder<br/>[builder.ml]"]
  node_beam_serializer["BEAM Serializer<br/>[serializer.ml]"]
  node_beam_assembly["BEAM Assembly<br/>[abstract_format.ml]"]
end

subgraph group_runtime["Runtime"]
  node_beam_runtime["BEAM Runtime<br/>[karuta.lfe]"]
end

node_user(("Programmer"))
node_erlc["Erlang Compiler"]

node_user -.->|"invokes"| node_cli
node_cli -.->|"parses"| node_parser
node_parser -.->|"produces"| node_ast
node_cli -.->|"compiles"| node_compiler
node_compiler -.->|"supports modules"| node_module_support
node_compiler -.->|"builds BEAM"| node_beam_builder
node_beam_builder -.->|"serializes"| node_beam_serializer
node_beam_serializer -.->|"produces"| node_beam_assembly
node_beam_assembly -->|"compiled by"| node_erlc
node_beam_runtime -->|"provides logic runtime"| node_user

click node_cli "https://github.com/dont-rely-on-nulls/karuta/blob/master/lib/cli.ml"
click node_parser "https://github.com/dont-rely-on-nulls/karuta/blob/master/lib/Parser.ml"
click node_ast "https://github.com/dont-rely-on-nulls/karuta/blob/master/lib/Ast.ml"
click node_module_support "https://github.com/dont-rely-on-nulls/karuta/blob/master/lib/karuta/Module.ml"
click node_compiler "https://github.com/dont-rely-on-nulls/karuta/blob/master/lib/shared/Compiler.ml"
click node_beam_builder "https://github.com/dont-rely-on-nulls/karuta/blob/master/lib/beam/builder.ml"
click node_beam_serializer "https://github.com/dont-rely-on-nulls/karuta/blob/master/lib/beam/serializer.ml"
click node_beam_assembly "https://github.com/dont-rely-on-nulls/karuta/blob/master/lib/beam/abstract_format.ml"
click node_beam_runtime "https://github.com/dont-rely-on-nulls/karuta/blob/master/runtime/karuta.lfe"
click node_sakura_support "https://github.com/dont-rely-on-nulls/karuta/tree/master/lib/sakura"

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_parser,node_ast toneBlue
class node_module_support,node_sakura_support toneAmber
class node_cli,node_compiler,node_beam_builder,node_beam_serializer,node_beam_assembly toneMint
class node_beam_runtime toneRose
class node_user,node_erlc toneIndigo
```

## Components

### Language Frontend

- [Parser](https://github.com/dont-rely-on-nulls/karuta/blob/master/lib/Parser.ml): `lib/Parser.ml`
- [Language AST](https://github.com/dont-rely-on-nulls/karuta/blob/master/lib/Ast.ml): `lib/Ast.ml`

### Modules

- [Module Support](https://github.com/dont-rely-on-nulls/karuta/blob/master/lib/karuta/Module.ml): `lib/karuta/Module.ml`
- [Sakura Integration](https://github.com/dont-rely-on-nulls/karuta/tree/master/lib/sakura): `lib/sakura`

### BEAM Toolchain

- [Command Line](https://github.com/dont-rely-on-nulls/karuta/blob/master/lib/cli.ml): `lib/cli.ml`
- [Compiler](https://github.com/dont-rely-on-nulls/karuta/blob/master/lib/shared/Compiler.ml): `lib/shared/Compiler.ml`
- [BEAM Builder](https://github.com/dont-rely-on-nulls/karuta/blob/master/lib/beam/builder.ml): `lib/beam/builder.ml`
- [BEAM Serializer](https://github.com/dont-rely-on-nulls/karuta/blob/master/lib/beam/serializer.ml): `lib/beam/serializer.ml`
- [BEAM Assembly](https://github.com/dont-rely-on-nulls/karuta/blob/master/lib/beam/abstract_format.ml): `lib/beam/abstract_format.ml`

### Runtime

- [BEAM Runtime](https://github.com/dont-rely-on-nulls/karuta/blob/master/runtime/karuta.lfe): `runtime/karuta.lfe`

### Other components

- **Programmer**
- **Erlang Compiler**

## Connections

- Programmer → Command Line: invokes
- Command Line → Parser: parses
- Parser → Language AST: produces
- Command Line → Compiler: compiles
- Compiler → Module Support: supports modules
- Compiler → BEAM Builder: builds BEAM
- BEAM Builder → BEAM Serializer: serializes
- BEAM Serializer → BEAM Assembly: produces
- BEAM Assembly → Erlang Compiler: compiled by (evidence: `README.org`)
- BEAM Runtime → Programmer: provides logic runtime (evidence: `README.org`)