Skip to content

Commit 7945c17

Browse files
committed
docs: add AI generated architecture diagram to wiki
1 parent 28195be commit 7945c17

2 files changed

Lines changed: 1 addition & 51 deletions

File tree

docs/wiki/Architecture.md

Lines changed: 1 addition & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,3 @@
11
# Architecture
22

3-
## Governance / blackboard flow
4-
5-
`universal-refiner` (the active MCP server) intercepts a raw prompt from an AI CLI, runs it
6-
through context and refinement, and — via `AgenticBlackboard` (`src/core/blackboard.ts`) —
7-
publishes and reads shared state so concurrent agent sessions can coordinate rather than act
8-
on disjoint local knowledge.
9-
10-
```mermaid
11-
flowchart LR
12-
CLI["AI CLI\n(Claude / Cursor / Gemini)"] -->|"stdio"| PI["PromptImprover\n(universal-refiner)"]
13-
subgraph Engine["Governance & Refinement Engine"]
14-
Scout["Context Scout\nlanguage/framework detectors"]
15-
RAG["RAG Snippets\nFlexSearch retrieval"]
16-
Memory[("SQLite Memory\nLocalBrain")]
17-
Semantic["Local Semantic Model\ngemma3:12b / 1b"]
18-
end
19-
subgraph BB["AgenticBlackboard (blackboard.json)"]
20-
Intents["Active agent intents\n(agentName, toolType, expiresAt)"]
21-
Logs["System logs\n(per-project)"]
22-
LastRefine["Last refinement record\n(gain metric)"]
23-
end
24-
PI --> Scout --> RAG --> Memory --> Semantic --> PI
25-
PI -->|"publish intent"| BB
26-
BB -->|"read concurrent intents"| PI
27-
PI --> Out["Augmented Prompt"]
28-
Out -.->|"event store"| Memory
29-
```
30-
31-
<!-- codex:generate-image prompt="A shared glowing chalkboard in the center of a room, with several small agent robots (labeled Claude, Cursor, Gemini) posting colored intent cards onto it and reading each other's cards before acting; one robot writes a refined prompt scroll that flows out to a waiting execution robot; isometric, enterprise blue/graphite palette" style="isometric, enterprise, clean" replaces="mermaid-above" -->
32-
33-
## Component breakdown
34-
35-
- **Context Scout** — startup detectors identify language, framework, and architectural
36-
signals so refinement is tailored to the current codebase (`src/detectors/project-scout.ts`).
37-
- **RAG Snippets** — FlexSearch-based retrieval over the local codebase injects relevant
38-
examples into the refined prompt.
39-
- **AgenticBlackboard** — a JSON-file-backed shared store (`.refiner/blackboard.json`,
40-
project-scoped, with a global fallback under `~/.refiner`) recording active agent intents
41-
(`agentName`, `toolType`, `intent`, `expiresAt`), system logs, and the last refinement's
42-
gain metric. A serialized write queue (`writeQueue`) and listener registry prevent
43-
concurrent-write corruption when multiple CLI sessions touch the same project.
44-
- **LocalBrain (SQLite)** — persistent storage for reusable refinement rules, learned
45-
patterns, and prompt history.
46-
- **Local Semantic Model** — an optional OpenAI-compatible local endpoint (`gemma3:12b`,
47-
falling back to `gemma3:1b`) that produces the final refined prompt; rule-based refinement
48-
continues if neither the local model nor MCP sampling is available.
49-
- **Governance gate** — generated lessons and templates remain pending until reviewed through
50-
the MCP learning-review tools (see the root README's Local Semantic Model section) — the
51-
blackboard records the intent and history that gate reviews against.
52-
53-
<!-- docs-verified: 101f63d702e5c0ab8052c8e0c67a104d8edfbddb 2026-07-08 -->
3+
![Architecture Diagram](assets/arch.png)

docs/wiki/assets/arch.png

1.97 MB
Loading

0 commit comments

Comments
 (0)