# aygaoua/minirt_ architecture

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

- Interactive diagram: https://gitdiagram.com/aygaoua/minirt_
- Repository: https://github.com/aygaoua/minirt_

## Overview

1. **Project purpose and runtime shape**
   - This is a C ray tracer (`miniRT`) that reads a scene description from a `.rt` file, builds an in-memory scene, and renders it to a window/image using **MLX42**.
   - The repository is organized as a classic pipeline: **parse scene → build geometry/light data → cast rays → compute shading → display image**.

2. **Top-level execution boundary**
   - `sources/main.c` is the application entrypoint.
   - It likely coordinates startup, file loading, parsing, scene initialization, render invocation, and teardown.
   - The main boundary is between **text input from scene files** and **rendered pixel output**.

3. **Scene description ingestion**
   - The `scenes/` directory contains sample `.rt` inputs used for evaluation and extra scenes.
   - The parser subsystem under `sources/parsing/` handles the `.rt` grammar, validates scene constraints, and populates runtime structures.
   - This layer is responsible for converting human-readable scene definitions into typed objects such as camera, ambient light, point lights, spheres, planes, and cylinders.

4. **Parsing subsystem responsibilities**
   - Files like `camera.c`, `light.c`, `ambient_lightning.c`, `sphere_pars.c`, `plane_pars.c`, and `cylinder_pars.c` suggest each object type has dedicated parsing/validation logic.
   - `collector.c`, `object_list.c`, and `parser.c` likely orchestrate tokenization, dispatch, and accumulation of parsed elements.
   - `data_validation*.c` and `check_elements.c` enforce correctness rules such as bounds, uniqueness, and format constraints.
   - `atof.c` indicates custom numeric parsing rather than relying purely on standard conversion.

5. **Runtime scene model**
   - The headers in `includes/` define the shared data model used across parsing, geometry, lighting, and rendering.
   - `miniRT.h` is the central project header, while `geometry.h`, `lighting.h`, `pars.h`, and `rt_mathematics.h` split the domain into subsystems.
   - The scene likely consists of linked lists or collections of primitives and lights, with camera and ambient values stored globally or in a scene struct.

6. **Geometry and intersection subsystem**
   - `sources/geometry/` contains the ray/object intersection logic for the supported primitives: **sphere, plane, cylinder**.
   - `rays.c`, `hits.c`, and `objects.c` likely manage ray construction, intersection selection, and object dispatch.
   - `lists.c` suggests object collections and iteration over scene primitives.
   - `cylinder_1.c` implies the cylinder logic is split, probably because it needs both side-surface and cap handling.

7. **Lighting and shading subsystem**
   - `sources/lighting/` implements color handling and shading, with `phong.c` indicating **Phong illumination**.
   - `lights.c` and `colors.c` likely combine ambient, diffuse, and specular terms, plus shadow checks.
   - The lighting stage consumes intersection results and surface normals to produce final pixel colors.
   - This is the main abstraction boundary where pure geometry becomes visible image output.

8. **Math and transformation layer**
   - `sources/rt_mathematics/` is the computational backbone: tuples/vectors, matrix math, normalization, reflection, scaling, rotation, translation, and coordinate transforms.
   - Files such as `mtx.c`, `tuple_mtx_ops.c`, `transformations.c`, and `render_*.c` suggest a reusable math kernel used by both parsing validation and rendering.
   - This layer isolates low-level linear algebra from ray-tracing logic, which is important for maintainability and diagramming dependencies.

9. **Rendering pipeline**
   - The `render_1.c` to `render_5.c` split suggests the render loop is decomposed into multiple stages, likely camera ray generation, per-pixel tracing, hit selection, shading, and post-processing or image writing.
   - The pipeline probably traverses the camera’s view plane, generates one ray per pixel, computes closest hits against all objects, then shades and writes the resulting color.
   - Any shadows are likely handled by secondary rays from hit points toward lights.

10. **Windowing and image output**
   - The project depends on **MLX42** under `lib/MLX42/` for graphics window management, image buffers, input hooks, and pixel display.
   - This external library is the boundary between CPU-side ray tracing and the user-facing GUI/window.
   - MLX42 is vendored in the repo, so the project is self-contained at build time except for system graphics dependencies.

11. **Shared utility library**
   - `lib/libft/` is the standard 42-style helper library used for string, memory, numeric, and I/O utilities, plus `get_next_line`.
   - It supports parsing and general housekeeping rather than architecture-critical rendering logic.
   - In a diagram, it is best treated as a foundational utility dependency beneath parsing and file handling.

12. **Build and packaging**
   - `Makefile` is the top-level build entry, likely compiling the app, linking `libft` and `MLX42`, and producing the `miniRT` binary.
   - The repo is mostly single-binary, monolithic C application architecture rather than a multi-service system.
   - The key architectural concern is dependency layering: **libft/utilities → parsing/math → geometry/lighting → MLX42 output**.

13. **High-level data flow to show in a diagram**
   - Scene file input flows into the parser.
   - Parser produces scene state: camera, ambient light, lights, and primitive object lists.
   - The renderer consumes that scene state, uses math helpers to transform and trace rays, calls geometry intersection functions, then passes hit information into lighting.
   - The final color buffer is handed to MLX42 for display in a window.

14. **Important boundaries and coupling points**
   - Parsing is separated from rendering: once the scene is built, render logic should not depend on raw file text.
   - Geometry is separated from shading: intersection code determines “what was hit,” while lighting code determines “what color it becomes.”
   - Math is shared and central, making it the lowest-level reusable layer.
   - MLX42 remains the only external UI/display boundary; everything else is application logic inside the repo.

Main entry points: [`sources/geometry/hits.c`](https://github.com/aygaoua/minirt_/blob/main/sources/geometry/hits.c) (Hits), [`sources/rt_mathematics/render_1.c`](https://github.com/aygaoua/minirt_/blob/main/sources/rt_mathematics/render_1.c) (Render), [`includes/miniRT.h`](https://github.com/aygaoua/minirt_/blob/main/includes/miniRT.h) (Scene Model), [`sources/parsing/parser.c`](https://github.com/aygaoua/minirt_/blob/main/sources/parsing/parser.c) (Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_main["Main<br/>entrypoint<br/>[main.c]"]
  node_scene_model["Scene Model<br/>shared structs<br/>[miniRT.h]"]
end

subgraph group_parsing["Parsing"]
  node_parser_core["Parser<br/>[parser.c]"]
  node_collector["Collector<br/>parse coordinator<br/>[collector.c]"]
  node_validation["Validation<br/>input checks<br/>[data_validation.c]"]
  node_camera_parse["Camera<br/>[camera.c]"]
  node_light_parse["Lights<br/>light parser<br/>[light.c]"]
  node_object_parse["Primitives<br/>shape parsers<br/>[object_list.c]"]
end

subgraph group_geometry["Geometry"]
  node_ray_core["Rays<br/>ray state<br/>[rays.c]"]
  node_hit_core["Hits<br/>intersection core<br/>[hits.c]"]
  node_sphere_geo["Sphere<br/>intersection<br/>[sphere.c]"]
  node_plane_geo["Plane<br/>intersection<br/>[plane.c]"]
  node_cylinder_geo["Cylinder<br/>intersection<br/>[cylinder.c]"]
end

subgraph group_lighting["Lighting"]
  node_lighting_core["Shading<br/>lighting pipeline<br/>[lights.c]"]
  node_phong["Phong<br/>illumination model<br/>[phong.c]"]
end

subgraph group_math["Math"]
  node_render_pipeline["Render<br/>pixel pipeline<br/>[render_1.c]"]
  node_math_kernel["Math Core<br/>linear algebra<br/>[mtx.c]"]
end

subgraph group_deps["Dependencies"]
  node_mlx42["MLX42<br/>windowing library<br/>[MLX42.h]"]
  node_libft["libft<br/>utility library<br/>[libft.h]"]
end

subgraph group_assets["Scenes"]
  node_scenes["Scenes<br/>sample inputs<br/>[objects.rt]"]
end

node_main -->|"loads scene"| node_parser_core
node_main -->|"renders"| node_render_pipeline
node_parser_core -->|"accumulates"| node_collector
node_parser_core -->|"checks"| node_validation
node_collector -->|"populates"| node_scene_model
node_camera_parse -->|"writes camera"| node_scene_model
node_light_parse -->|"writes lights"| node_scene_model
node_object_parse -->|"writes objects"| node_scene_model
node_render_pipeline -->|"consumes"| node_scene_model
node_render_pipeline -->|"uses"| node_math_kernel
node_render_pipeline -->|"emits rays"| node_ray_core
node_ray_core -->|"tests hits"| node_hit_core
node_hit_core -->|"dispatches"| node_sphere_geo
node_hit_core -->|"dispatches"| node_plane_geo
node_hit_core -->|"dispatches"| node_cylinder_geo
node_hit_core -->|"returns hit"| node_lighting_core
node_lighting_core -->|"applies"| node_phong
node_lighting_core -->|"uses"| node_math_kernel
node_render_pipeline -->|"display buffer"| node_mlx42
node_parser_core -->|"parses text"| node_libft
node_main -.->|"reads examples"| node_scenes

click node_main "https://github.com/aygaoua/minirt_/blob/main/sources/main.c"
click node_scene_model "https://github.com/aygaoua/minirt_/blob/main/includes/miniRT.h"
click node_parser_core "https://github.com/aygaoua/minirt_/blob/main/sources/parsing/parser.c"
click node_collector "https://github.com/aygaoua/minirt_/blob/main/sources/parsing/collector.c"
click node_validation "https://github.com/aygaoua/minirt_/blob/main/sources/parsing/data_validation.c"
click node_camera_parse "https://github.com/aygaoua/minirt_/blob/main/sources/parsing/camera.c"
click node_light_parse "https://github.com/aygaoua/minirt_/blob/main/sources/parsing/light.c"
click node_object_parse "https://github.com/aygaoua/minirt_/blob/main/sources/parsing/object_list.c"
click node_ray_core "https://github.com/aygaoua/minirt_/blob/main/sources/geometry/rays.c"
click node_hit_core "https://github.com/aygaoua/minirt_/blob/main/sources/geometry/hits.c"
click node_sphere_geo "https://github.com/aygaoua/minirt_/blob/main/sources/geometry/sphere.c"
click node_plane_geo "https://github.com/aygaoua/minirt_/blob/main/sources/geometry/plane.c"
click node_cylinder_geo "https://github.com/aygaoua/minirt_/blob/main/sources/geometry/cylinder.c"
click node_lighting_core "https://github.com/aygaoua/minirt_/blob/main/sources/lighting/lights.c"
click node_phong "https://github.com/aygaoua/minirt_/blob/main/sources/lighting/phong.c"
click node_render_pipeline "https://github.com/aygaoua/minirt_/blob/main/sources/rt_mathematics/render_1.c"
click node_math_kernel "https://github.com/aygaoua/minirt_/blob/main/sources/rt_mathematics/mtx.c"
click node_mlx42 "https://github.com/aygaoua/minirt_/blob/main/lib/MLX42/include/MLX42/MLX42.h"
click node_libft "https://github.com/aygaoua/minirt_/blob/main/lib/libft/libft.h"
click node_scenes "https://github.com/aygaoua/minirt_/blob/main/scenes/evaluation/objects.rt"

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_scene_model,node_scenes toneBlue
class node_parser_core,node_collector,node_validation,node_camera_parse,node_light_parse,node_object_parse toneAmber
class node_ray_core,node_hit_core,node_sphere_geo,node_plane_geo,node_cylinder_geo toneMint
class node_lighting_core,node_phong toneRose
class node_render_pipeline,node_math_kernel toneIndigo
class node_mlx42,node_libft toneTeal
```

## Components

### Application

Entrypoint and top-level orchestration

- [Main](https://github.com/aygaoua/minirt_/blob/main/sources/main.c): entrypoint · Starts the app and drives load-render-teardown flow · `sources/main.c`
- [Scene Model](https://github.com/aygaoua/minirt_/blob/main/includes/miniRT.h): shared structs · Central scene and data definitions used across the pipeline · `includes/miniRT.h`

### Parsing

Scene file ingestion and validation

- [Parser](https://github.com/aygaoua/minirt_/blob/main/sources/parsing/parser.c): scene parser · Coordinates .rt file reading and dispatch into object parsers · `sources/parsing/parser.c`
- [Collector](https://github.com/aygaoua/minirt_/blob/main/sources/parsing/collector.c): parse coordinator · Accumulates parsed tokens and scene elements · `sources/parsing/collector.c`
- [Validation](https://github.com/aygaoua/minirt_/blob/main/sources/parsing/data_validation.c): input checks · Enforces scene constraints and format correctness · `sources/parsing/data_validation.c`
- [Camera](https://github.com/aygaoua/minirt_/blob/main/sources/parsing/camera.c): camera parser · Parses camera definition and view parameters · `sources/parsing/camera.c`
- [Lights](https://github.com/aygaoua/minirt_/blob/main/sources/parsing/light.c): light parser · Parses ambient and point light definitions · `sources/parsing/light.c`
- [Primitives](https://github.com/aygaoua/minirt_/blob/main/sources/parsing/object_list.c): shape parsers · Parses sphere, plane, and cylinder records · `sources/parsing/object_list.c`

### Geometry

Ray and primitive intersection logic

- [Rays](https://github.com/aygaoua/minirt_/blob/main/sources/geometry/rays.c): ray state · Constructs rays and manages hit traversal inputs · `sources/geometry/rays.c`
- [Hits](https://github.com/aygaoua/minirt_/blob/main/sources/geometry/hits.c): intersection core · Selects closest intersections and combines object tests · `sources/geometry/hits.c`
- [Sphere](https://github.com/aygaoua/minirt_/blob/main/sources/geometry/sphere.c): intersection · Sphere ray intersection logic · `sources/geometry/sphere.c`
- [Plane](https://github.com/aygaoua/minirt_/blob/main/sources/geometry/plane.c): intersection · Plane ray intersection logic · `sources/geometry/plane.c`
- [Cylinder](https://github.com/aygaoua/minirt_/blob/main/sources/geometry/cylinder.c): intersection · Cylinder side and cap intersection logic · `sources/geometry/cylinder.c`

### Lighting

Shading and color composition

- [Shading](https://github.com/aygaoua/minirt_/blob/main/sources/lighting/lights.c): lighting pipeline · Combines ambient, diffuse, specular, and shadow terms · `sources/lighting/lights.c`
- [Phong](https://github.com/aygaoua/minirt_/blob/main/sources/lighting/phong.c): illumination model · Implements the Phong shading model · `sources/lighting/phong.c`

### Math

Linear algebra and transform utilities

- [Render](https://github.com/aygaoua/minirt_/blob/main/sources/rt_mathematics/render_1.c): pixel pipeline · Generates camera rays, traces hits, shades pixels, and fills the image · `sources/rt_mathematics/render_1.c`
- [Math Core](https://github.com/aygaoua/minirt_/blob/main/sources/rt_mathematics/mtx.c): linear algebra · Vectors, tuples, matrices, transforms, normalization, and reflection · `sources/rt_mathematics/mtx.c`

### Dependencies

Vendored runtime and utility libraries

- [MLX42](https://github.com/aygaoua/minirt_/blob/main/lib/MLX42/include/MLX42/MLX42.h): windowing library · Window, input, image buffer, and pixel display backend · `lib/MLX42/include/MLX42/MLX42.h`
- [libft](https://github.com/aygaoua/minirt_/blob/main/lib/libft/libft.h): utility library · String, memory, I/O, and line-reading helpers · `lib/libft/libft.h`

### Scenes

Sample .rt scene inputs

- [Scenes](https://github.com/aygaoua/minirt_/blob/main/scenes/evaluation/objects.rt): sample inputs · Reference .rt files used for evaluation and examples · `scenes/evaluation/objects.rt`

## Connections

- Main → Parser: loads scene · Reads the .rt file and starts parsing
- Main → Render: renders · Invokes the rendering loop after scene setup
- Parser → Collector: accumulates · Builds the scene from parsed elements
- Parser → Validation: checks · Validates structure and constraints during parse
- Collector → Scene Model: populates · Materializes the shared runtime scene state
- Camera → Scene Model: writes camera · Stores parsed camera parameters
- Lights → Scene Model: writes lights · Stores ambient and point light data
- Primitives → Scene Model: writes objects · Adds primitives to the scene model
- Render → Scene Model: consumes · Uses camera, lights, and object lists for tracing
- Render → Math Core: uses · Relies on vector and matrix operations
- Render → Rays: emits rays · Generates primary rays per pixel
- Rays → Hits: tests hits · Feeds rays into intersection selection
- Hits → Sphere: dispatches · Evaluates sphere intersections
- Hits → Plane: dispatches · Evaluates plane intersections
- Hits → Cylinder: dispatches · Evaluates cylinder intersections
- Hits → Shading: returns hit · Passes closest hit and surface data to shading
- Shading → Phong: applies · Computes diffuse and specular response
- Shading → Math Core: uses · Uses normals, reflection, and normalization helpers
- Render → MLX42: display buffer · Uploads final pixels to the window/image backend
- Parser → libft: parses text · Uses helper routines for input and string handling
- Main → Scenes: reads examples · Can be driven by bundled scene files
