# hsantosdias/hpp-lang architecture

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

- Interactive diagram: https://gitdiagram.com/hsantosdias/hpp-lang
- Repository: https://github.com/hsantosdias/hpp-lang

## Overview

H++ is an educational robotics language whose main workflow is compiling bilingual source into executable statements, then running those statements cycle by cycle against host-provided hardware. The repository also provides universal motion semantics and separate soccer, line-following, and maze extension contracts. The README documents the broader runtime and adapter boundary; some subsystem wiring is therefore shown only where supported by the sampled source or explicit architecture description.

Main entry points: [`packages/hpp-lang/src/interpreter.ts`](https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/interpreter.ts) (Interpreter), [`packages/hpp-lang/src/index.ts`](https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/index.ts) (Public API), [`packages/hpp-lang/src/capabilities.ts`](https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/capabilities.ts) (Capability Model), [`packages/hpp-lang/src/parser.ts`](https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/parser.ts) (Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["Language Core"]
  node_api["Public API<br/>[index.ts]"]
  node_lexer["Lexer<br/>[lexer.ts]"]
  node_parser["Parser<br/>[parser.ts]"]
  node_ast["AST<br/>[ast.ts]"]
  node_interpreter["Interpreter<br/>[interpreter.ts]"]
  node_runtime["Cycle Runtime<br/>[runtime.ts]"]
  node_errors["Runtime Errors<br/>[errors.ts]"]
end

subgraph group_robotics["Robotics Runtime"]
  node_motion["Motion State<br/>[motion.ts]"]
  node_contracts["Motion Contracts<br/>[contracts.ts]"]
  node_capabilities["Capability Model<br/>[capabilities.ts]"]
  node_sensors["Sensor Snapshot<br/>[sensors.ts]"]
end

subgraph group_domains["Domain Extensions"]
  node_soccer["Soccer Extension<br/>[index.ts]"]
  node_line["Line Extension<br/>[index.ts]"]
  node_maze["Maze Extension<br/>[index.ts]"]
end

subgraph group_host["Hardware Boundary"]
  node_hardware["Hardware Contract<br/>[hardware.ts]"]
  node_adapter["Host Adapter"]
end

node_learner(("Program Author"))
node_source["H++ Source"]
node_robot(("Robot or Simulator"))

node_learner -->|"writes"| node_source
node_source -->|"compiles"| node_api
node_api -->|"tokenizes"| node_lexer
node_api -->|"parses"| node_parser
node_lexer -->|"passes tokens"| node_parser
node_parser -->|"produces"| node_ast
node_api -->|"runs program"| node_interpreter
node_ast -->|"executes"| node_interpreter
node_runtime -->|"cycles"| node_interpreter
node_interpreter -->|"updates movement"| node_motion
node_interpreter -->|"checks requirements"| node_capabilities
node_interpreter -->|"raises"| node_errors
node_contracts -->|"defines commands"| node_motion
node_soccer -->|"declares capabilities"| node_capabilities
node_line -->|"declares capabilities"| node_capabilities
node_maze -->|"declares capabilities"| node_capabilities
node_interpreter -->|"reads sensors; dispatches actions"| node_hardware
node_hardware -->|"implemented by"| node_adapter
node_adapter -->|"controls"| node_robot
node_adapter -->|"provides readings"| node_sensors

click node_api "https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/index.ts"
click node_lexer "https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/lexer.ts"
click node_parser "https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/parser.ts"
click node_ast "https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/ast.ts"
click node_interpreter "https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/interpreter.ts"
click node_runtime "https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/runtime.ts"
click node_errors "https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/errors.ts"
click node_motion "https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/robotics/motion.ts"
click node_contracts "https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/robotics/contracts.ts"
click node_capabilities "https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/capabilities.ts"
click node_sensors "https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/robotics/sensors.ts"
click node_soccer "https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/extensions/soccer/index.ts"
click node_line "https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/extensions/line/index.ts"
click node_maze "https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/extensions/maze/index.ts"
click node_hardware "https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/hardware.ts"

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_api,node_lexer,node_parser,node_ast,node_interpreter,node_runtime,node_errors toneBlue
class node_motion,node_contracts,node_capabilities,node_sensors toneAmber
class node_soccer,node_line,node_maze toneMint
class node_hardware,node_adapter toneRose
class node_learner,node_source,node_robot toneIndigo
```

## Components

### Language Core

- [Public API](https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/index.ts): `packages/hpp-lang/src/index.ts`
- [Lexer](https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/lexer.ts): `packages/hpp-lang/src/lexer.ts`
- [Parser](https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/parser.ts): `packages/hpp-lang/src/parser.ts`
- [AST](https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/ast.ts): `packages/hpp-lang/src/ast.ts`
- [Interpreter](https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/interpreter.ts): `packages/hpp-lang/src/interpreter.ts`
- [Cycle Runtime](https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/runtime.ts): `packages/hpp-lang/src/runtime.ts`
- [Runtime Errors](https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/errors.ts): `packages/hpp-lang/src/errors.ts`

### Robotics Runtime

- [Motion State](https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/robotics/motion.ts): `packages/hpp-lang/src/robotics/motion.ts`
- [Motion Contracts](https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/robotics/contracts.ts): `packages/hpp-lang/src/robotics/contracts.ts`
- [Capability Model](https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/capabilities.ts): `packages/hpp-lang/src/capabilities.ts`
- [Sensor Snapshot](https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/robotics/sensors.ts): `packages/hpp-lang/src/robotics/sensors.ts`

### Domain Extensions

- [Soccer Extension](https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/extensions/soccer/index.ts): `packages/hpp-lang/src/extensions/soccer/index.ts`
- [Line Extension](https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/extensions/line/index.ts): `packages/hpp-lang/src/extensions/line/index.ts`
- [Maze Extension](https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/extensions/maze/index.ts): `packages/hpp-lang/src/extensions/maze/index.ts`

### Hardware Boundary

- [Hardware Contract](https://github.com/hsantosdias/hpp-lang/blob/main/packages/hpp-lang/src/hardware.ts): `packages/hpp-lang/src/hardware.ts`
- **Host Adapter**

### Other components

- **Program Author**
- **H++ Source**
- **Robot or Simulator**

## Connections

- Program Author → H++ Source: writes
- H++ Source → Public API: compiles
- Public API → Lexer: tokenizes
- Public API → Parser: parses
- Lexer → Parser: passes tokens
- Parser → AST: produces
- Public API → Interpreter: runs program
- AST → Interpreter: executes
- Cycle Runtime → Interpreter: cycles
- Interpreter → Motion State: updates movement
- Interpreter → Capability Model: checks requirements
- Interpreter → Runtime Errors: raises
- Motion Contracts → Motion State: defines commands
- Soccer Extension → Capability Model: declares capabilities
- Line Extension → Capability Model: declares capabilities
- Maze Extension → Capability Model: declares capabilities
- Interpreter → Hardware Contract: reads sensors; dispatches actions
- Hardware Contract → Host Adapter: implemented by
- Host Adapter → Robot or Simulator: controls
- Host Adapter → Sensor Snapshot: provides readings