# scriptoriumlab/scriptorium-inkstone architecture

> Architecture diagram of the GitHub repository scriptoriumlab/scriptorium-inkstone, 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/scriptoriumlab/scriptorium-inkstone
- Repository: https://github.com/scriptoriumlab/scriptorium-inkstone
- Video tour (about a minute): https://gitdiagram.com/scriptoriumlab/scriptorium-inkstone/video

## Overview

Inkstone is a platform-independent input-method service: Brush forwards key events, Inkstone updates authoritative composition and candidate state, and Ink receives render updates or reports user actions. The main path runs from the IPC server through the session orchestrator and engine manager to the Pinyin engine, which segments input and looks up dictionary entries to assemble candidates. Managers coordinate selection and notification; the server translates protocol messages and bridges candidate state to the UI. The README documents ranking, paging, and committed/uncommitted state, but sampled code does not establish complete implementations for all of them. External links follow documented protocol boundaries.

Main entry points: [`inkstone/server.cpp`](https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/inkstone/server.cpp) (IPC server), [`core/src/engine/pinyin_engine.cpp`](https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/core/src/engine/pinyin_engine.cpp) (Pinyin engine), [`manager/src/session_orchestrator.cpp`](https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/manager/src/session_orchestrator.cpp) (Session orchestrator), [`manager/src/engine_manager.cpp`](https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/manager/src/engine_manager.cpp) (Engine manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and IPC"]
  node_app["Application entry<br/>[app.cpp]"]
  node_server["IPC server<br/>[server.cpp]"]
  node_bridge["UI bridge<br/>[server.cpp]"]
end

subgraph group_managers["Session orchestration"]
  node_orchestrator["Session orchestrator"]
  node_engine_manager["Engine manager<br/>[engine_manager.cpp]"]
  node_candidate_manager["Candidate manager"]
end

subgraph group_core["Input capabilities"]
  node_input_engine["Engine interface<br/>[input_engine.h]"]
  node_pinyin_engine["Pinyin engine<br/>[pinyin_engine.cpp]"]
  node_tokenizer["Pinyin tokenizer<br/>[tokenizer.cpp]"]
  node_dictionary["Dictionary lookup<br/>[dictionary.cpp]"]
  node_dictionary_data["Pinyin entries"]
end

subgraph group_external["External processes"]
  node_brush(("Brush adapter"))
  node_ink(("Ink presentation"))
end

node_app -->|"starts"| node_server
node_brush -->|"sends key events"| node_server
node_server -->|"dispatches key events"| node_orchestrator
node_orchestrator -->|"updates engine"| node_engine_manager
node_engine_manager -->|"calls engine"| node_input_engine
node_pinyin_engine -->|"implements"| node_input_engine
node_pinyin_engine -->|"segments input"| node_tokenizer
node_pinyin_engine -->|"looks up entries"| node_dictionary
node_pinyin_engine -->|"loads entries"| node_dictionary_data
node_orchestrator -->|"updates candidates"| node_candidate_manager
node_candidate_manager -->|"notifies observer"| node_bridge
node_bridge -->|"sends render state"| node_ink
node_ink -->|"sends user action"| node_server
node_server -->|"requests selection"| node_orchestrator
node_server -->|"returns instruction"| node_brush

click node_app "https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/inkstone/app.cpp"
click node_server "https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/inkstone/server.cpp"
click node_bridge "https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/inkstone/server.cpp"
click node_orchestrator "https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/manager/src/session_orchestrator.cpp"
click node_engine_manager "https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/manager/src/engine_manager.cpp"
click node_candidate_manager "https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/manager/src/candidate_manager.cpp"
click node_input_engine "https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/core/include/scriptorium/core/engine/input_engine.h"
click node_pinyin_engine "https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/core/src/engine/pinyin_engine.cpp"
click node_tokenizer "https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/core/src/tokenizer/tokenizer.cpp"
click node_dictionary "https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/core/src/dictionary/dictionary.cpp"
click node_dictionary_data "https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/data/pinyin_dictionary.txt"

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_app,node_server,node_bridge toneBlue
class node_orchestrator,node_engine_manager,node_candidate_manager toneAmber
class node_input_engine,node_pinyin_engine,node_tokenizer,node_dictionary,node_dictionary_data toneMint
class node_brush,node_ink toneRose
```

## Components

### Runtime and IPC

- [Application entry](https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/inkstone/app.cpp): `inkstone/app.cpp`
- [IPC server](https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/inkstone/server.cpp): `inkstone/server.cpp`
- [UI bridge](https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/inkstone/server.cpp): `inkstone/server.cpp`

### Session orchestration

- [Session orchestrator](https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/manager/src/session_orchestrator.cpp): `manager/src/session_orchestrator.cpp`
- [Engine manager](https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/manager/src/engine_manager.cpp): `manager/src/engine_manager.cpp`
- [Candidate manager](https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/manager/src/candidate_manager.cpp): `manager/src/candidate_manager.cpp`

### Input capabilities

- [Engine interface](https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/core/include/scriptorium/core/engine/input_engine.h): `core/include/scriptorium/core/engine/input_engine.h`
- [Pinyin engine](https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/core/src/engine/pinyin_engine.cpp): `core/src/engine/pinyin_engine.cpp`
- [Pinyin tokenizer](https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/core/src/tokenizer/tokenizer.cpp): `core/src/tokenizer/tokenizer.cpp`
- [Dictionary lookup](https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/core/src/dictionary/dictionary.cpp): `core/src/dictionary/dictionary.cpp`
- [Pinyin entries](https://github.com/scriptoriumlab/scriptorium-inkstone/blob/master/data/pinyin_dictionary.txt): `data/pinyin_dictionary.txt`

### External processes

- **Brush adapter**
- **Ink presentation**

## Connections

- Application entry → IPC server: starts
- Brush adapter → IPC server: sends key events
- IPC server → Session orchestrator: dispatches key events
- Session orchestrator → Engine manager: updates engine
- Engine manager → Engine interface: calls engine
- Pinyin engine → Engine interface: implements
- Pinyin engine → Pinyin tokenizer: segments input
- Pinyin engine → Dictionary lookup: looks up entries
- Pinyin engine → Pinyin entries: loads entries
- Session orchestrator → Candidate manager: updates candidates
- Candidate manager → UI bridge: notifies observer
- UI bridge → Ink presentation: sends render state
- Ink presentation → IPC server: sends user action
- IPC server → Session orchestrator: requests selection
- IPC server → Brush adapter: returns instruction