# smlfg/human-agent-interface architecture

> Architecture diagram of the GitHub repository smlfg/human-agent-interface, 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/smlfg/human-agent-interface
- Repository: https://github.com/smlfg/human-agent-interface

## Overview

This repository is the JavaScript frontend for the public Human Agent Interface site, alongside interactive study tools for algorithms and data structures. HAI’s documented workflow turns human intent into scoped, inspectable work and a handoff; the sampled code also shows an intake packet flow and a harness-advice chat. The study tools offer practice, progress tracking, and timed exam simulation. Some source was not sampled, so the graph includes only relationships visible in excerpts or documented in the README; it does not assume how other site routes are wired.

Main entry points: [`proof/ads/probeklausur-interaktiv/app.js`](https://github.com/smlfg/human-agent-interface/blob/main/proof/ads/probeklausur-interaktiv/app.js) (Practice portal), [`APP/intake/app.js`](https://github.com/smlfg/human-agent-interface/blob/main/APP/intake/app.js) (Owner intake), [`Münztelfon/app.js`](https://github.com/smlfg/human-agent-interface/blob/main/M%C3%BCnztelfon/app.js) (Harness chat UI), [`Münztelfon/server.py`](https://github.com/smlfg/human-agent-interface/blob/main/M%C3%BCnztelfon/server.py) (Harness chat API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hai["HAI user flows"]
  node_public_site["Public HAI site"]
  node_intake["Owner intake<br/>[app.js]"]
  node_intake_packet["Intake packet<br/>[app.js]"]
  node_harness_ui["Harness chat UI<br/>[app.js]"]
  node_harness_api["Harness chat API<br/>[server.py]"]
end

subgraph group_runtime["Site runtime"]
  node_site_worker["Site request worker<br/>[worker.js]"]
end

subgraph group_ads["ADS learning"]
  node_practice_portal["Practice portal<br/>[app.js]"]
  node_tree_game["Tree practice<br/>[game.js]"]
  node_runtime_game["Runtime practice<br/>[game.js]"]
  node_sorting_lab["Sorting lab<br/>[lab.js]"]
  node_practice_tasks["Practice tasks"]
  node_exam_sim["Exam simulation"]
end

node_visitor(("Site visitor"))
node_model_provider{{"LLM provider"}}
node_site_assets["Static assets"]
node_study_learner(("Study learner"))

node_visitor -->|"enters details"| node_intake
node_intake -->|"builds packet"| node_intake_packet
node_visitor -->|"starts chat"| node_harness_ui
node_harness_ui -->|"posts chat"| node_harness_api
node_harness_api -->|"requests response"| node_model_provider
node_site_worker -->|"fetches assets"| node_site_assets
node_study_learner -->|"opens practice"| node_practice_portal
node_practice_portal -->|"links to"| node_tree_game
node_practice_portal -->|"links to tasks"| node_practice_tasks
node_study_learner -.->|"practices runtime"| node_runtime_game
node_study_learner -.->|"practices sorting"| node_sorting_lab
node_study_learner -.->|"takes simulation"| node_exam_sim

click node_intake "https://github.com/smlfg/human-agent-interface/blob/main/APP/intake/app.js"
click node_intake_packet "https://github.com/smlfg/human-agent-interface/blob/main/APP/intake/app.js"
click node_harness_ui "https://github.com/smlfg/human-agent-interface/blob/main/M%C3%BCnztelfon/app.js"
click node_harness_api "https://github.com/smlfg/human-agent-interface/blob/main/M%C3%BCnztelfon/server.py"
click node_site_worker "https://github.com/smlfg/human-agent-interface/blob/main/src/worker.js"
click node_practice_portal "https://github.com/smlfg/human-agent-interface/blob/main/proof/ads/probeklausur-interaktiv/app.js"
click node_tree_game "https://github.com/smlfg/human-agent-interface/blob/main/proof/ads/probeklausur-interaktiv/baum-detektiv/game.js"
click node_runtime_game "https://github.com/smlfg/human-agent-interface/blob/main/proof/ads/probeklausur-interaktiv/laufzeit-detektiv/game.js"
click node_sorting_lab "https://github.com/smlfg/human-agent-interface/blob/main/proof/ads/probeklausur-interaktiv/sortier-labor/lab.js"
click node_practice_tasks "https://github.com/smlfg/human-agent-interface/tree/main/proof/ads/probeklausur-interaktiv"
click node_exam_sim "https://github.com/smlfg/human-agent-interface/blob/main/proof/ads/klausur-simulation.js"

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_public_site,node_intake,node_intake_packet,node_harness_ui,node_harness_api toneBlue
class node_site_worker toneAmber
class node_practice_portal,node_tree_game,node_runtime_game,node_sorting_lab,node_practice_tasks,node_exam_sim toneMint
class node_visitor,node_model_provider,node_site_assets,node_study_learner toneIndigo
```

## Components

### HAI user flows

- **Public HAI site**
- [Owner intake](https://github.com/smlfg/human-agent-interface/blob/main/APP/intake/app.js): `APP/intake/app.js`
- [Intake packet](https://github.com/smlfg/human-agent-interface/blob/main/APP/intake/app.js): `APP/intake/app.js`
- [Harness chat UI](https://github.com/smlfg/human-agent-interface/blob/main/M%C3%BCnztelfon/app.js): `Münztelfon/app.js`
- [Harness chat API](https://github.com/smlfg/human-agent-interface/blob/main/M%C3%BCnztelfon/server.py): `Münztelfon/server.py`

### Site runtime

- [Site request worker](https://github.com/smlfg/human-agent-interface/blob/main/src/worker.js): `src/worker.js`

### ADS learning

- [Practice portal](https://github.com/smlfg/human-agent-interface/blob/main/proof/ads/probeklausur-interaktiv/app.js): `proof/ads/probeklausur-interaktiv/app.js`
- [Tree practice](https://github.com/smlfg/human-agent-interface/blob/main/proof/ads/probeklausur-interaktiv/baum-detektiv/game.js): `proof/ads/probeklausur-interaktiv/baum-detektiv/game.js`
- [Runtime practice](https://github.com/smlfg/human-agent-interface/blob/main/proof/ads/probeklausur-interaktiv/laufzeit-detektiv/game.js): `proof/ads/probeklausur-interaktiv/laufzeit-detektiv/game.js`
- [Sorting lab](https://github.com/smlfg/human-agent-interface/blob/main/proof/ads/probeklausur-interaktiv/sortier-labor/lab.js): `proof/ads/probeklausur-interaktiv/sortier-labor/lab.js`
- [Practice tasks](https://github.com/smlfg/human-agent-interface/tree/main/proof/ads/probeklausur-interaktiv): `proof/ads/probeklausur-interaktiv`
- [Exam simulation](https://github.com/smlfg/human-agent-interface/blob/main/proof/ads/klausur-simulation.js): `proof/ads/klausur-simulation.js`

### Other components

- **Site visitor**
- **LLM provider**
- **Static assets**
- **Study learner**

## Connections

- Site visitor → Owner intake: enters details (evidence: `APP/intake/app.js`)
- Owner intake → Intake packet: builds packet (evidence: `APP/intake/app.js`)
- Site visitor → Harness chat UI: starts chat (evidence: `Münztelfon/app.js`)
- Harness chat UI → Harness chat API: posts chat (evidence: `Münztelfon/app.js`)
- Harness chat API → LLM provider: requests response (evidence: `Münztelfon/server.py`)
- Site request worker → Static assets: fetches assets (evidence: `src/worker.js`)
- Study learner → Practice portal: opens practice (evidence: `proof/ads/probeklausur-interaktiv/app.js`)
- Practice portal → Tree practice: links to (evidence: `proof/ads/probeklausur-interaktiv/app.js`)
- Practice portal → Practice tasks: links to tasks (evidence: `proof/ads/probeklausur-interaktiv/app.js`)
- Study learner → Runtime practice: practices runtime
- Study learner → Sorting lab: practices sorting
- Study learner → Exam simulation: takes simulation
