# jhonc6797/smental_solver architecture

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

- Interactive diagram: https://gitdiagram.com/jhonc6797/smental_solver
- Repository: https://github.com/jhonc6797/smental_solver

## Overview

Semantle Hebrew Solver searches for the daily answer by scoring guesses against the game API, then presents the run in a terminal or interactive board. The principal workflow probes anchors, estimates and searches a semantic region, and switches to focused nearest-neighbour search; morphology and vocabulary support that engine. For the web, the server streams serialized, projected events and keeps runs replayable; the static site can instead load a published daily recording. The graph follows documented behavior and sampled call sites; daily publishing details are documented but its implementation was not sampled.

Main entry points: [`server/app.py`](https://github.com/jhonc6797/smental_solver/blob/main/server/app.py) (HTTP and socket API), [`web/src/App.tsx`](https://github.com/jhonc6797/smental_solver/blob/main/web/src/App.tsx) (Board application), [`solver/engine.py`](https://github.com/jhonc6797/smental_solver/blob/main/solver/engine.py) (Search engine), [`cli/runner.py`](https://github.com/jhonc6797/smental_solver/blob/main/cli/runner.py) (Terminal runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_solver["Solver engine"]
  node_engine["Search engine<br/>[engine.py]"]
  node_morphology["Hebrew morphology<br/>[morphology.py]"]
  node_vocabulary["Word vocabulary<br/>[vocabulary.py]"]
  node_config["Search settings<br/>[config.py]"]
  node_game_client["Game client<br/>[client.py]"]
end

subgraph group_server["Run server"]
  node_server_app["HTTP and socket API<br/>[app.py]"]
  node_daily_runs["Daily run manager<br/>[daily.py]"]
  node_run_store[("Run history store<br/>[daily.py]")]
  node_session["Solve session<br/>[session.py]"]
  node_serialization["Event serialization<br/>[serialization.py]"]
  node_projection["Board projection<br/>[projection.py]"]
end

subgraph group_web["Web board"]
  node_web_app["Board application<br/>[App.tsx]"]
  node_web_api["Web API client<br/>[api.ts]"]
  node_board["3D guess board<br/>[Board.tsx]"]
  node_log["Guess log<br/>[Log.tsx]"]
  node_progress_chart["Progress chart<br/>[ProgressChart.tsx]"]
end

subgraph group_daily["Daily publishing"]
  node_daily_publisher["Recording publisher<br/>[publish_daily.py]"]
end

subgraph group_terminal["Terminal interface"]
  node_terminal_runner["Terminal runner<br/>[runner.py]"]
  node_terminal_plot["Summary plot<br/>[plotting.py]"]
end

node_visitor(("Viewer / operator"))
node_scheduler(("Daily scheduler"))
node_game_api(("Semantle API"))
node_recording["Published daily recording"]

node_visitor -->|"views"| node_web_app
node_web_app -->|"requests / reconnects"| node_web_api
node_web_api -->|"starts / streams"| node_server_app
node_server_app -->|"gets current run"| node_daily_runs
node_daily_runs -->|"loads / saves"| node_run_store
node_daily_runs -->|"creates session"| node_session
node_server_app -->|"loads vocabulary"| node_vocabulary
node_server_app -->|"builds projection"| node_projection
node_server_app -->|"checks answer"| node_game_client
node_session -->|"runs search"| node_engine
node_engine -->|"reads words / vectors"| node_vocabulary
node_engine -->|"filters duplicates"| node_morphology
node_engine -->|"reads settings"| node_config
node_engine -->|"scores guesses"| node_game_client
node_game_client -->|"requests scores"| node_game_api
node_session -->|"serializes events"| node_serialization
node_session -->|"projects event data"| node_projection
node_server_app -->|"streams messages"| node_session
node_server_app -->|"sends messages"| node_web_api
node_web_api -->|"delivers messages"| node_web_app
node_web_app -->|"renders guesses"| node_board
node_web_app -->|"shows guesses"| node_log
node_web_app -->|"charts progress"| node_progress_chart
node_scheduler -.->|"triggers publish"| node_daily_publisher
node_daily_publisher -.->|"publishes run"| node_recording
node_web_app -.->|"loads recording"| node_recording
node_visitor -->|"runs solver"| node_terminal_runner
node_terminal_runner -->|"loads vocabulary"| node_vocabulary
node_terminal_runner -->|"scores guesses"| node_game_client
node_terminal_runner -->|"consumes events"| node_engine
node_terminal_runner -->|"plots history"| node_terminal_plot

click node_engine "https://github.com/jhonc6797/smental_solver/blob/main/solver/engine.py"
click node_morphology "https://github.com/jhonc6797/smental_solver/blob/main/solver/morphology.py"
click node_vocabulary "https://github.com/jhonc6797/smental_solver/blob/main/solver/vocabulary.py"
click node_config "https://github.com/jhonc6797/smental_solver/blob/main/solver/config.py"
click node_game_client "https://github.com/jhonc6797/smental_solver/blob/main/semantle/client.py"
click node_server_app "https://github.com/jhonc6797/smental_solver/blob/main/server/app.py"
click node_daily_runs "https://github.com/jhonc6797/smental_solver/blob/main/server/daily.py"
click node_run_store "https://github.com/jhonc6797/smental_solver/blob/main/server/daily.py"
click node_session "https://github.com/jhonc6797/smental_solver/blob/main/server/session.py"
click node_serialization "https://github.com/jhonc6797/smental_solver/blob/main/server/serialization.py"
click node_projection "https://github.com/jhonc6797/smental_solver/blob/main/server/projection.py"
click node_web_app "https://github.com/jhonc6797/smental_solver/blob/main/web/src/App.tsx"
click node_web_api "https://github.com/jhonc6797/smental_solver/blob/main/web/src/api.ts"
click node_board "https://github.com/jhonc6797/smental_solver/blob/main/web/src/board/Board.tsx"
click node_log "https://github.com/jhonc6797/smental_solver/blob/main/web/src/ui/Log.tsx"
click node_progress_chart "https://github.com/jhonc6797/smental_solver/blob/main/web/src/ui/ProgressChart.tsx"
click node_daily_publisher "https://github.com/jhonc6797/smental_solver/blob/main/scripts/publish_daily.py"
click node_terminal_runner "https://github.com/jhonc6797/smental_solver/blob/main/cli/runner.py"
click node_terminal_plot "https://github.com/jhonc6797/smental_solver/blob/main/cli/plotting.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_engine,node_morphology,node_vocabulary,node_config,node_game_client,node_visitor toneBlue
class node_server_app,node_daily_runs,node_run_store,node_session,node_serialization,node_projection toneAmber
class node_web_app,node_web_api,node_board,node_log,node_progress_chart,node_game_api toneMint
class node_daily_publisher,node_scheduler toneRose
class node_terminal_runner,node_terminal_plot,node_recording toneIndigo
```

## Components

### Solver engine

- [Search engine](https://github.com/jhonc6797/smental_solver/blob/main/solver/engine.py): `solver/engine.py`
- [Hebrew morphology](https://github.com/jhonc6797/smental_solver/blob/main/solver/morphology.py): `solver/morphology.py`
- [Word vocabulary](https://github.com/jhonc6797/smental_solver/blob/main/solver/vocabulary.py): `solver/vocabulary.py`
- [Search settings](https://github.com/jhonc6797/smental_solver/blob/main/solver/config.py): `solver/config.py`
- [Game client](https://github.com/jhonc6797/smental_solver/blob/main/semantle/client.py): `semantle/client.py`

### Run server

- [HTTP and socket API](https://github.com/jhonc6797/smental_solver/blob/main/server/app.py): `server/app.py`
- [Daily run manager](https://github.com/jhonc6797/smental_solver/blob/main/server/daily.py): `server/daily.py`
- [Run history store](https://github.com/jhonc6797/smental_solver/blob/main/server/daily.py): `server/daily.py`
- [Solve session](https://github.com/jhonc6797/smental_solver/blob/main/server/session.py): `server/session.py`
- [Event serialization](https://github.com/jhonc6797/smental_solver/blob/main/server/serialization.py): `server/serialization.py`
- [Board projection](https://github.com/jhonc6797/smental_solver/blob/main/server/projection.py): `server/projection.py`

### Web board

- [Board application](https://github.com/jhonc6797/smental_solver/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Web API client](https://github.com/jhonc6797/smental_solver/blob/main/web/src/api.ts): `web/src/api.ts`
- [3D guess board](https://github.com/jhonc6797/smental_solver/blob/main/web/src/board/Board.tsx): `web/src/board/Board.tsx`
- [Guess log](https://github.com/jhonc6797/smental_solver/blob/main/web/src/ui/Log.tsx): `web/src/ui/Log.tsx`
- [Progress chart](https://github.com/jhonc6797/smental_solver/blob/main/web/src/ui/ProgressChart.tsx): `web/src/ui/ProgressChart.tsx`

### Daily publishing

- [Recording publisher](https://github.com/jhonc6797/smental_solver/blob/main/scripts/publish_daily.py): `scripts/publish_daily.py`

### Terminal interface

- [Terminal runner](https://github.com/jhonc6797/smental_solver/blob/main/cli/runner.py): `cli/runner.py`
- [Summary plot](https://github.com/jhonc6797/smental_solver/blob/main/cli/plotting.py): `cli/plotting.py`

### Other components

- **Viewer / operator**
- **Daily scheduler**
- **Semantle API**
- **Published daily recording**

## Connections

- Viewer / operator → Board application: views
- Board application → Web API client: requests / reconnects
- Web API client → HTTP and socket API: starts / streams
- HTTP and socket API → Daily run manager: gets current run
- Daily run manager → Run history store: loads / saves
- Daily run manager → Solve session: creates session
- HTTP and socket API → Word vocabulary: loads vocabulary
- HTTP and socket API → Board projection: builds projection
- HTTP and socket API → Game client: checks answer
- Solve session → Search engine: runs search
- Search engine → Word vocabulary: reads words / vectors
- Search engine → Hebrew morphology: filters duplicates
- Search engine → Search settings: reads settings
- Search engine → Game client: scores guesses
- Game client → Semantle API: requests scores
- Solve session → Event serialization: serializes events
- Solve session → Board projection: projects event data
- HTTP and socket API → Solve session: streams messages
- HTTP and socket API → Web API client: sends messages
- Web API client → Board application: delivers messages
- Board application → 3D guess board: renders guesses
- Board application → Guess log: shows guesses
- Board application → Progress chart: charts progress
- Daily scheduler → Recording publisher: triggers publish
- Recording publisher → Published daily recording: publishes run
- Board application → Published daily recording: loads recording
- Viewer / operator → Terminal runner: runs solver
- Terminal runner → Word vocabulary: loads vocabulary
- Terminal runner → Game client: scores guesses
- Terminal runner → Search engine: consumes events
- Terminal runner → Summary plot: plots history