# sathvikadevineni/rayven architecture

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

- Interactive diagram: https://gitdiagram.com/sathvikadevineni/rayven
- Repository: https://github.com/sathvikadevineni/rayven

## Overview

RayVen is a DSL and optical-simulation environment. A user writes an `.rv` program; the OCaml compiler tokenizes and parses it, checks semantics, and generates Python, which the Python/Pygame engine runs to simulate and render optics and optionally record video. The README documents the compiler stages and end-to-end flow; the sampled engine excerpt confirms its optical objects, ray interactions, simulation runtime, and recording. Compiler internals were not sampled, so their connections rely on README documentation.

Main entry points: [`RayVen_engine.py`](https://github.com/sathvikadevineni/rayven/blob/main/RayVen_engine.py) (Simulation engine), [`lib/parser.ml`](https://github.com/sathvikadevineni/rayven/blob/main/lib/parser.ml) (Parser), [`bin/main.ml`](https://github.com/sathvikadevineni/rayven/blob/main/bin/main.ml) (Compiler entry), [`lib/tokenizer.ml`](https://github.com/sathvikadevineni/rayven/blob/main/lib/tokenizer.ml) (Tokenizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_compiler["DSL compiler"]
  node_entry["Compiler entry<br/>[main.ml]"]
  node_tokenizer["Tokenizer<br/>[tokenizer.ml]"]
  node_parser["Parser<br/>[parser.ml]"]
  node_ast["AST<br/>[ast.ml]"]
  node_checks["Static checks<br/>[static_checks.ml]"]
  node_codegen["Python codegen<br/>[codegen.ml]"]
end

subgraph group_optics["Optics simulation"]
  node_optical_objects["Optical objects<br/>[RayVen_engine.py]"]
  node_ray["Ray tracing<br/>[RayVen_engine.py]"]
  node_physics["Optics physics<br/>[RayVen_engine.py]"]
end

subgraph group_runtime["Interactive output"]
  node_generated["Generated Python"]
  node_engine["Simulation engine<br/>[RayVen_engine.py]"]
  node_world["Simulation world<br/>[RayVen_engine.py]"]
  node_render["Pygame display<br/>[RayVen_engine.py]"]
  node_recording["Video recording<br/>[RayVen_engine.py]"]
end

node_user(("DSL author"))
node_viewer(("Simulation viewer"))
node_video["MP4 video"]

node_user -->|"submits program"| node_entry
node_entry -->|"starts compilation"| node_tokenizer
node_tokenizer -->|"produces tokens"| node_parser
node_parser -->|"builds AST"| node_ast
node_parser -->|"checks semantics"| node_checks
node_checks -->|"feeds checked program"| node_codegen
node_codegen -->|"generates Python"| node_generated
node_generated -->|"runs simulation"| node_engine
node_engine -->|"creates optics"| node_optical_objects
node_engine -->|"manages world"| node_world
node_ray -->|"uses refraction"| node_physics
node_viewer -->|"views simulation"| node_render
node_engine -.->|"renders display"| node_render
node_engine -->|"records frames"| node_recording
node_recording -->|"writes video"| node_video

click node_entry "https://github.com/sathvikadevineni/rayven/blob/main/bin/main.ml"
click node_tokenizer "https://github.com/sathvikadevineni/rayven/blob/main/lib/tokenizer.ml"
click node_parser "https://github.com/sathvikadevineni/rayven/blob/main/lib/parser.ml"
click node_ast "https://github.com/sathvikadevineni/rayven/blob/main/lib/ast.ml"
click node_checks "https://github.com/sathvikadevineni/rayven/blob/main/lib/static_checks.ml"
click node_codegen "https://github.com/sathvikadevineni/rayven/blob/main/lib/codegen.ml"
click node_engine "https://github.com/sathvikadevineni/rayven/blob/main/RayVen_engine.py"
click node_optical_objects "https://github.com/sathvikadevineni/rayven/blob/main/RayVen_engine.py"
click node_ray "https://github.com/sathvikadevineni/rayven/blob/main/RayVen_engine.py"
click node_physics "https://github.com/sathvikadevineni/rayven/blob/main/RayVen_engine.py"
click node_world "https://github.com/sathvikadevineni/rayven/blob/main/RayVen_engine.py"
click node_render "https://github.com/sathvikadevineni/rayven/blob/main/RayVen_engine.py"
click node_recording "https://github.com/sathvikadevineni/rayven/blob/main/RayVen_engine.py"

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_entry,node_tokenizer,node_parser,node_ast,node_checks,node_codegen,node_viewer toneBlue
class node_optical_objects,node_ray,node_physics toneAmber
class node_generated,node_engine,node_world,node_render,node_recording toneMint
class node_user,node_video toneIndigo
```

## Components

### DSL compiler

- [Compiler entry](https://github.com/sathvikadevineni/rayven/blob/main/bin/main.ml): `bin/main.ml`
- [Tokenizer](https://github.com/sathvikadevineni/rayven/blob/main/lib/tokenizer.ml): `lib/tokenizer.ml`
- [Parser](https://github.com/sathvikadevineni/rayven/blob/main/lib/parser.ml): `lib/parser.ml`
- [AST](https://github.com/sathvikadevineni/rayven/blob/main/lib/ast.ml): `lib/ast.ml`
- [Static checks](https://github.com/sathvikadevineni/rayven/blob/main/lib/static_checks.ml): `lib/static_checks.ml`
- [Python codegen](https://github.com/sathvikadevineni/rayven/blob/main/lib/codegen.ml): `lib/codegen.ml`

### Optics simulation

- [Optical objects](https://github.com/sathvikadevineni/rayven/blob/main/RayVen_engine.py): `RayVen_engine.py`
- [Ray tracing](https://github.com/sathvikadevineni/rayven/blob/main/RayVen_engine.py): `RayVen_engine.py`
- [Optics physics](https://github.com/sathvikadevineni/rayven/blob/main/RayVen_engine.py): `RayVen_engine.py`

### Interactive output

- **Generated Python**
- [Simulation engine](https://github.com/sathvikadevineni/rayven/blob/main/RayVen_engine.py): `RayVen_engine.py`
- [Simulation world](https://github.com/sathvikadevineni/rayven/blob/main/RayVen_engine.py): `RayVen_engine.py`
- [Pygame display](https://github.com/sathvikadevineni/rayven/blob/main/RayVen_engine.py): `RayVen_engine.py`
- [Video recording](https://github.com/sathvikadevineni/rayven/blob/main/RayVen_engine.py): `RayVen_engine.py`

### Other components

- **DSL author**
- **Simulation viewer**
- **MP4 video**

## Connections

- DSL author → Compiler entry: submits program (evidence: `README.md`)
- Compiler entry → Tokenizer: starts compilation (evidence: `README.md`)
- Tokenizer → Parser: produces tokens (evidence: `README.md`)
- Parser → AST: builds AST (evidence: `README.md`)
- Parser → Static checks: checks semantics (evidence: `README.md`)
- Static checks → Python codegen: feeds checked program (evidence: `README.md`)
- Python codegen → Generated Python: generates Python (evidence: `README.md`)
- Generated Python → Simulation engine: runs simulation (evidence: `README.md`)
- Simulation engine → Optical objects: creates optics (evidence: `RayVen_engine.py`)
- Simulation engine → Simulation world: manages world (evidence: `RayVen_engine.py`)
- Ray tracing → Optics physics: uses refraction (evidence: `RayVen_engine.py`)
- Simulation viewer → Pygame display: views simulation (evidence: `README.md`)
- Simulation engine → Pygame display: renders display (evidence: `RayVen_engine.py`)
- Simulation engine → Video recording: records frames (evidence: `RayVen_engine.py`)
- Video recording → MP4 video: writes video (evidence: `README.md`)
