# nssmd/jev-bot architecture

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

- Interactive diagram: https://gitdiagram.com/nssmd/jev-bot
- Repository: https://github.com/nssmd/jev-bot

## Overview

JEV is a self-hosted decision workbench with a web UI and a Feishu bot. Users submit a question for automatic candidate generation and Jev selection, or provide options for direct comparison; results include probabilities. Experimental writing repeatedly selects words or characters. The server routes requests to Jev and, optionally, a separate text-model provider. The bot also supports guided input, cancellation, and durable event deduplication. The graph follows documented capabilities and sampled wiring; unsampled UI and server details are represented only where README documentation supports them.

Main entry points: [`bot/start.mjs`](https://github.com/nssmd/jev-bot/blob/main/bot/start.mjs) (Bot runtime), [`public/app.js`](https://github.com/nssmd/jev-bot/blob/main/public/app.js) (Web UI), [`gateway.mjs`](https://github.com/nssmd/jev-bot/blob/main/gateway.mjs) (Judge gateway), [`public/api.js`](https://github.com/nssmd/jev-bot/blob/main/public/api.js) (Browser API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web workbench"]
  node_web_ui["Web UI<br/>[app.js]"]
  node_web_api["Browser API client<br/>[api.js]"]
end

subgraph group_backend["Decision backend"]
  node_server["HTTP server<br/>[server.mjs]"]
  node_gateway["Judge gateway<br/>[gateway.mjs]"]
  node_structurer["Candidate generation<br/>[structurer.mjs]"]
end

subgraph group_writing["Writing loops"]
  node_word_loop["Word writing loop<br/>[word-writing.js]"]
  node_word_decoder["Word decision decoder<br/>[word-decoder.mjs]"]
  node_inventory["Word inventory"]
  node_character_loop["Character writing loop<br/>[writing.js]"]
end

subgraph group_bot["Feishu bot"]
  node_bot_start["Bot runtime<br/>[start.mjs]"]
  node_bot_core["Message workflow<br/>[core.mjs]"]
  node_event_journal[("Deduplication journal<br/>[start.mjs]")]
end

subgraph group_integrations["External services"]
  node_jev["TypeSafe Jev API"]
  node_text_provider["Text model provider"]
  node_feishu["Feishu platform"]
end

node_web_user(("Web user"))
node_feishu_user(("Feishu user"))

node_web_user -->|"submits input"| node_web_ui
node_web_ui -->|"requests decisions"| node_web_api
node_web_api -->|"POSTs request"| node_server
node_server -->|"routes request"| node_gateway
node_gateway -.->|"generates candidates"| node_structurer
node_structurer -.->|"requests options"| node_text_provider
node_gateway -->|"requests judgment"| node_jev
node_gateway -->|"decodes next word"| node_word_decoder
node_word_decoder -->|"reads vocabulary"| node_inventory
node_web_ui -->|"generates words"| node_word_loop
node_word_loop -->|"requests predictions"| node_web_api
node_web_ui -->|"generates characters"| node_character_loop
node_character_loop -->|"requests predictions"| node_web_api
node_gateway -->|"returns results"| node_web_api
node_web_ui -->|"shows probabilities"| node_web_user
node_feishu_user -->|"sends message"| node_feishu
node_feishu -->|"delivers events"| node_bot_start
node_bot_start -->|"dispatches messages"| node_bot_core
node_bot_core -->|"invokes callbacks"| node_bot_start
node_bot_start -->|"requests judgment"| node_server
node_bot_start -->|"generates bot writing"| node_word_loop
node_bot_start -->|"claims and records events"| node_event_journal
node_bot_start -->|"replies with cards"| node_feishu

click node_web_ui "https://github.com/nssmd/jev-bot/blob/main/public/app.js"
click node_web_api "https://github.com/nssmd/jev-bot/blob/main/public/api.js"
click node_server "https://github.com/nssmd/jev-bot/blob/main/server.mjs"
click node_gateway "https://github.com/nssmd/jev-bot/blob/main/gateway.mjs"
click node_structurer "https://github.com/nssmd/jev-bot/blob/main/structurer.mjs"
click node_word_loop "https://github.com/nssmd/jev-bot/blob/main/public/word-writing.js"
click node_word_decoder "https://github.com/nssmd/jev-bot/blob/main/word-decoder.mjs"
click node_inventory "https://github.com/nssmd/jev-bot/blob/main/word-inventory.json"
click node_character_loop "https://github.com/nssmd/jev-bot/blob/main/public/writing.js"
click node_bot_start "https://github.com/nssmd/jev-bot/blob/main/bot/start.mjs"
click node_bot_core "https://github.com/nssmd/jev-bot/blob/main/bot/core.mjs"
click node_event_journal "https://github.com/nssmd/jev-bot/blob/main/bot/start.mjs"

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_web_ui,node_web_api,node_web_user,node_feishu_user toneBlue
class node_server,node_gateway,node_structurer toneAmber
class node_word_loop,node_word_decoder,node_inventory,node_character_loop toneMint
class node_bot_start,node_bot_core,node_event_journal toneRose
class node_jev,node_text_provider,node_feishu toneIndigo
```

## Components

### Web workbench

- [Web UI](https://github.com/nssmd/jev-bot/blob/main/public/app.js): `public/app.js`
- [Browser API client](https://github.com/nssmd/jev-bot/blob/main/public/api.js): `public/api.js`

### Decision backend

- [HTTP server](https://github.com/nssmd/jev-bot/blob/main/server.mjs): `server.mjs`
- [Judge gateway](https://github.com/nssmd/jev-bot/blob/main/gateway.mjs): `gateway.mjs`
- [Candidate generation](https://github.com/nssmd/jev-bot/blob/main/structurer.mjs): `structurer.mjs`

### Writing loops

- [Word writing loop](https://github.com/nssmd/jev-bot/blob/main/public/word-writing.js): `public/word-writing.js`
- [Word decision decoder](https://github.com/nssmd/jev-bot/blob/main/word-decoder.mjs): `word-decoder.mjs`
- [Word inventory](https://github.com/nssmd/jev-bot/blob/main/word-inventory.json): `word-inventory.json`
- [Character writing loop](https://github.com/nssmd/jev-bot/blob/main/public/writing.js): `public/writing.js`

### Feishu bot

- [Bot runtime](https://github.com/nssmd/jev-bot/blob/main/bot/start.mjs): `bot/start.mjs`
- [Message workflow](https://github.com/nssmd/jev-bot/blob/main/bot/core.mjs): `bot/core.mjs`
- [Deduplication journal](https://github.com/nssmd/jev-bot/blob/main/bot/start.mjs): `bot/start.mjs`

### External services

- **TypeSafe Jev API**
- **Text model provider**
- **Feishu platform**

### Other components

- **Web user**
- **Feishu user**

## Connections

- Web user → Web UI: submits input
- Web UI → Browser API client: requests decisions
- Browser API client → HTTP server: POSTs request
- HTTP server → Judge gateway: routes request
- Judge gateway → Candidate generation: generates candidates
- Candidate generation → Text model provider: requests options
- Judge gateway → TypeSafe Jev API: requests judgment
- Judge gateway → Word decision decoder: decodes next word
- Word decision decoder → Word inventory: reads vocabulary
- Web UI → Word writing loop: generates words
- Word writing loop → Browser API client: requests predictions
- Web UI → Character writing loop: generates characters
- Character writing loop → Browser API client: requests predictions
- Judge gateway → Browser API client: returns results
- Web UI → Web user: shows probabilities
- Feishu user → Feishu platform: sends message
- Feishu platform → Bot runtime: delivers events
- Bot runtime → Message workflow: dispatches messages
- Message workflow → Bot runtime: invokes callbacks
- Bot runtime → HTTP server: requests judgment
- Bot runtime → Word writing loop: generates bot writing
- Bot runtime → Deduplication journal: claims and records events
- Bot runtime → Feishu platform: replies with cards