# jasonkerama-dev/ampersand architecture

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

- Interactive diagram: https://gitdiagram.com/jasonkerama-dev/ampersand
- Repository: https://github.com/jasonkerama-dev/ampersand

## Overview

Ampersand combines a browser-based graph IDE with a C++ DataGraph compiler. The main workflow is to edit a graph on the canvas, save it through the API, and compile it to receive execution results. The compiler’s documented stages include graph ordering, bounded lifecycle evaluation, arena and immutable-memory rules, and termination checks. The source excerpts show the API’s graph serialization and compiler invocation; compiler internals and some browser interactions are described in the README rather than excerpted here.

Main entry points: [`app/Http/Controllers/CanvasController.php`](https://github.com/jasonkerama-dev/ampersand/blob/main/app/Http/Controllers/CanvasController.php) (Canvas API), [`app/Models/Project.php`](https://github.com/jasonkerama-dev/ampersand/blob/main/app/Models/Project.php) (Projects), [`compiler/main.cpp`](https://github.com/jasonkerama-dev/ampersand/blob/main/compiler/main.cpp) (C++ compiler), [`resources/views/canvas.blade.php`](https://github.com/jasonkerama-dev/ampersand/blob/main/resources/views/canvas.blade.php) (Canvas view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ide["Canvas IDE"]
  node_canvas_view["Canvas view<br/>[canvas.blade.php]"]
  node_canvas_app["Canvas editor<br/>[canvas.js]"]
end

subgraph group_api["Web API"]
  node_web_routes["Web routes<br/>[web.php]"]
  node_canvas_api["Canvas API"]
end

subgraph group_data["Graph persistence"]
  node_projects["Projects<br/>[Project.php]"]
  node_functions["Function nodes<br/>[FnNode.php]"]
  node_variables["Variables<br/>[Variable.php]"]
  node_immutables["Immutables<br/>[Immutable.php]"]
  node_connections["Graph connections<br/>[Connection.php]"]
  node_database[("Application database")]
  node_users["User accounts<br/>[User.php]"]
end

subgraph group_engine["Compiler engine"]
  node_compiler["C++ compiler<br/>[main.cpp]"]
  node_compile_output["Compile results<br/>[main.cpp]"]
  node_ordering["Graph ordering<br/>[main.cpp]"]
  node_lifecycle["Lifecycle engine<br/>[main.cpp]"]
  node_memory["Memory arena<br/>[main.cpp]"]
  node_worm["WORM semantics<br/>[main.cpp]"]
end

node_engineer(("IDE user"))

node_engineer -->|"opens IDE"| node_canvas_view
node_canvas_view -->|"hosts editor"| node_canvas_app
node_canvas_app -.->|"calls API"| node_web_routes
node_web_routes -->|"routes requests"| node_canvas_api
node_canvas_api -->|"loads and saves"| node_projects
node_canvas_api -->|"saves nodes"| node_functions
node_canvas_api -->|"saves nodes"| node_variables
node_canvas_api -->|"saves nodes"| node_immutables
node_canvas_api -->|"saves edges"| node_connections
node_projects -->|"has many"| node_functions
node_projects -->|"has many"| node_variables
node_projects -->|"has many"| node_immutables
node_projects -->|"has many"| node_connections
node_canvas_api -->|"invokes compiler"| node_compiler
node_compiler -->|"orders graph"| node_ordering
node_compiler -->|"evaluates cycles"| node_lifecycle
node_lifecycle -->|"uses arena"| node_memory
node_lifecycle -->|"enforces writes"| node_worm
node_compiler -->|"returns results"| node_compile_output
node_canvas_api -->|"returns JSON"| node_compile_output

click node_canvas_view "https://github.com/jasonkerama-dev/ampersand/blob/main/resources/views/canvas.blade.php"
click node_canvas_app "https://github.com/jasonkerama-dev/ampersand/blob/main/public/canvas.js"
click node_web_routes "https://github.com/jasonkerama-dev/ampersand/blob/main/routes/web.php"
click node_canvas_api "https://github.com/jasonkerama-dev/ampersand/blob/main/app/Http/Controllers/CanvasController.php"
click node_compiler "https://github.com/jasonkerama-dev/ampersand/blob/main/compiler/main.cpp"
click node_compile_output "https://github.com/jasonkerama-dev/ampersand/blob/main/compiler/main.cpp"
click node_projects "https://github.com/jasonkerama-dev/ampersand/blob/main/app/Models/Project.php"
click node_functions "https://github.com/jasonkerama-dev/ampersand/blob/main/app/Models/FnNode.php"
click node_variables "https://github.com/jasonkerama-dev/ampersand/blob/main/app/Models/Variable.php"
click node_immutables "https://github.com/jasonkerama-dev/ampersand/blob/main/app/Models/Immutable.php"
click node_connections "https://github.com/jasonkerama-dev/ampersand/blob/main/app/Models/Connection.php"
click node_database "https://github.com/jasonkerama-dev/ampersand/tree/main/database/migrations"
click node_users "https://github.com/jasonkerama-dev/ampersand/blob/main/app/Models/User.php"
click node_ordering "https://github.com/jasonkerama-dev/ampersand/blob/main/compiler/main.cpp"
click node_lifecycle "https://github.com/jasonkerama-dev/ampersand/blob/main/compiler/main.cpp"
click node_memory "https://github.com/jasonkerama-dev/ampersand/blob/main/compiler/main.cpp"
click node_worm "https://github.com/jasonkerama-dev/ampersand/blob/main/compiler/main.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_canvas_view,node_canvas_app,node_engineer toneBlue
class node_web_routes,node_canvas_api toneAmber
class node_projects,node_functions,node_variables,node_immutables,node_connections,node_database,node_users toneMint
class node_compiler,node_compile_output,node_ordering,node_lifecycle,node_memory,node_worm toneRose
```

## Components

### Canvas IDE

- [Canvas view](https://github.com/jasonkerama-dev/ampersand/blob/main/resources/views/canvas.blade.php): `resources/views/canvas.blade.php`
- [Canvas editor](https://github.com/jasonkerama-dev/ampersand/blob/main/public/canvas.js): `public/canvas.js`

### Web API

- [Web routes](https://github.com/jasonkerama-dev/ampersand/blob/main/routes/web.php): `routes/web.php`
- [Canvas API](https://github.com/jasonkerama-dev/ampersand/blob/main/app/Http/Controllers/CanvasController.php): `app/Http/Controllers/CanvasController.php`

### Graph persistence

- [Projects](https://github.com/jasonkerama-dev/ampersand/blob/main/app/Models/Project.php): `app/Models/Project.php`
- [Function nodes](https://github.com/jasonkerama-dev/ampersand/blob/main/app/Models/FnNode.php): `app/Models/FnNode.php`
- [Variables](https://github.com/jasonkerama-dev/ampersand/blob/main/app/Models/Variable.php): `app/Models/Variable.php`
- [Immutables](https://github.com/jasonkerama-dev/ampersand/blob/main/app/Models/Immutable.php): `app/Models/Immutable.php`
- [Graph connections](https://github.com/jasonkerama-dev/ampersand/blob/main/app/Models/Connection.php): `app/Models/Connection.php`
- [Application database](https://github.com/jasonkerama-dev/ampersand/tree/main/database/migrations): `database/migrations`
- [User accounts](https://github.com/jasonkerama-dev/ampersand/blob/main/app/Models/User.php): `app/Models/User.php`

### Compiler engine

- [C++ compiler](https://github.com/jasonkerama-dev/ampersand/blob/main/compiler/main.cpp): `compiler/main.cpp`
- [Compile results](https://github.com/jasonkerama-dev/ampersand/blob/main/compiler/main.cpp): `compiler/main.cpp`
- [Graph ordering](https://github.com/jasonkerama-dev/ampersand/blob/main/compiler/main.cpp): `compiler/main.cpp`
- [Lifecycle engine](https://github.com/jasonkerama-dev/ampersand/blob/main/compiler/main.cpp): `compiler/main.cpp`
- [Memory arena](https://github.com/jasonkerama-dev/ampersand/blob/main/compiler/main.cpp): `compiler/main.cpp`
- [WORM semantics](https://github.com/jasonkerama-dev/ampersand/blob/main/compiler/main.cpp): `compiler/main.cpp`

### Other components

- **IDE user**

## Connections

- IDE user → Canvas view: opens IDE (evidence: `README.md`)
- Canvas view → Canvas editor: hosts editor (evidence: `README.md`)
- Canvas editor → Web routes: calls API
- Web routes → Canvas API: routes requests (evidence: `routes/web.php`)
- Canvas API → Projects: loads and saves (evidence: `app/Http/Controllers/CanvasController.php`)
- Canvas API → Function nodes: saves nodes (evidence: `app/Http/Controllers/CanvasController.php`)
- Canvas API → Variables: saves nodes (evidence: `app/Http/Controllers/CanvasController.php`)
- Canvas API → Immutables: saves nodes (evidence: `app/Http/Controllers/CanvasController.php`)
- Canvas API → Graph connections: saves edges (evidence: `app/Http/Controllers/CanvasController.php`)
- Projects → Function nodes: has many (evidence: `app/Models/Project.php`)
- Projects → Variables: has many (evidence: `app/Models/Project.php`)
- Projects → Immutables: has many (evidence: `app/Models/Project.php`)
- Projects → Graph connections: has many (evidence: `app/Models/Project.php`)
- Canvas API → C++ compiler: invokes compiler (evidence: `app/Http/Controllers/CanvasController.php`)
- C++ compiler → Graph ordering: orders graph (evidence: `README.md`)
- C++ compiler → Lifecycle engine: evaluates cycles (evidence: `README.md`)
- Lifecycle engine → Memory arena: uses arena (evidence: `README.md`)
- Lifecycle engine → WORM semantics: enforces writes (evidence: `README.md`)
- C++ compiler → Compile results: returns results (evidence: `compiler/main.cpp`)
- Canvas API → Compile results: returns JSON (evidence: `app/Http/Controllers/CanvasController.php`)
