Skip to content

Commit eeeb3ca

Browse files
novatechflownovatechflow
authored
Merge pull request #18 from scalytics/novatechflow/readme-fix
docs: improve navigation and architecture diagrams
2 parents b644cd9 + b656531 commit eeeb3ca

9 files changed

Lines changed: 156 additions & 36 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# KafClaw
2-
[![CI (Smoke+Fuzz+Go)](https://github.com/scalytics/KafClaw/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/scalytics/KafClaw/actions/workflows/ci.yml)
3-
[![Release](https://github.com/scalytics/KafClaw/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/scalytics/KafClaw/actions/workflows/release.yml)
4-
[![Pages](https://github.com/scalytics/KafClaw/actions/workflows/pages.yml/badge.svg?branch=main)](https://github.com/scalytics/KafClaw/actions/workflows/pages.yml)
2+
[![CI (Smoke+Fuzz+Go)](https://github.com/KafClaw/KafClaw/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/KafClaw/KafClaw/actions/workflows/ci.yml)
3+
[![Release](https://github.com/KafClaw/KafClaw/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/KafClaw/KafClaw/actions/workflows/release.yml)
4+
[![Pages](https://github.com/KafClaw/KafClaw/actions/workflows/pages.yml/badge.svg?branch=main)](https://github.com/KafClaw/KafClaw/actions/workflows/pages.yml)
55

66
[![Go Report Card](https://goreportcard.com/badge/github.com/KafClaw/KafClaw)](https://goreportcard.com/report/github.com/KafClaw/KafClaw)
77
[![License](https://img.shields.io/github/license/KafClaw/KafClaw)](LICENSE)

‎docs/_includes/topnav.html‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
<style>
2+
.kc-topnav {
3+
margin: 0 0 1rem;
4+
padding: 0.7rem 0.9rem;
5+
border: 1px solid #d4dcec;
6+
border-radius: 10px;
7+
background: #f7faff;
8+
font-size: 0.92rem;
9+
}
10+
.kc-topnav .back {
11+
border: 1px solid #c4d3ef;
12+
border-radius: 7px;
13+
background: #ffffff;
14+
color: #17408f;
15+
font-weight: 600;
16+
padding: 0.2rem 0.55rem;
17+
cursor: pointer;
18+
margin-right: 0.6rem;
19+
}
20+
.kc-topnav a {
21+
text-decoration: none;
22+
font-weight: 600;
23+
color: #17408f;
24+
margin-right: 0.6rem;
25+
}
26+
.kc-topnav .sep {
27+
color: #7a889f;
28+
margin-right: 0.6rem;
29+
}
30+
</style>
31+
<div class="kc-topnav">
32+
<button type="button" class="back" onclick="if (window.history.length > 1) { window.history.back(); } else { window.location.href='{{ '/' | relative_url }}'; }">Back</button>
33+
<a href="{{ '/' | relative_url }}">Home</a><span class="sep">|</span>
34+
<a href="{{ '/getting-started' | relative_url }}">Get Started</a><span class="sep">|</span>
35+
<a href="{{ '/manage-kafclaw' | relative_url }}">Manage</a><span class="sep">|</span>
36+
<a href="{{ '/v2' | relative_url }}">v2 Docs</a><span class="sep">|</span>
37+
<a href="{{ '/v2/architecture' | relative_url }}">Architecture</a><span class="sep">|</span>
38+
<a href="{{ '/v2/admin-guide' | relative_url }}">Admin</a><span class="sep">|</span>
39+
<a href="{{ '/v2/operations-guide' | relative_url }}">Operations</a>
40+
</div>

‎docs/getting-started.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Getting Started
22

3+
{% include topnav.html %}
4+
35
This guide gets KafClaw from zero to a working setup, with focus on onboarding and workspace identity files.
46

57
## 1. Prerequisites

‎docs/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44
<img src="./assets/kafclaw.png" alt="KafClaw Logo" width="320" />
55
</p>
66

7+
{% include topnav.html %}
8+
79
KafClaw is a Go-based agent runtime with three practical deployment modes:
810

911
- `local`: personal assistant on one machine

‎docs/maintenance.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Operations and Maintenance
22

3+
{% include topnav.html %}
4+
35
Operational runbook for keeping KafClaw healthy in dev and production-like setups.
46

57
## Daily Checks

‎docs/manage-kafclaw.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# KafClaw Management Guide
22

3+
{% include topnav.html %}
4+
35
Operator-focused guide for managing KafClaw from CLI and runtime endpoints.
46

57
## 1. Core Command Surface

‎docs/v2/architecture-detailed.md‎

Lines changed: 51 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# KafClaw System Architecture — Detailed Reference
22

3+
{% include topnav.html %}
4+
35
> For the quick overview, see [architecture.md](./architecture.md).
46
> See also: [FR-009 System Architecture](../requirements/FR-009-system-architecture.md), [FR-013 Package Design](../requirements/FR-013-package-design.md), [FR-018 Interface Contracts](../requirements/FR-018-interface-contracts.md)
57
@@ -27,20 +29,55 @@
2729

2830
KafClaw is a personal AI assistant framework written in Go with an Electron desktop frontend. It connects messaging channels (WhatsApp, local network, web UI) to LLM providers through an asynchronous message bus, with a tool registry for filesystem/shell/web operations, a 6-layer semantic memory system, policy-based authorization, multi-agent collaboration via Kafka, and a cron-based job scheduler.
2931

30-
```
31-
WhatsApp --+
32-
CLI -------+ +-- Filesystem Tools
33-
Web UI ----+-- Message Bus -- Agent Loop -- LLM +-- Shell Execution
34-
Scheduler -+ | | +-- Web Search
35-
| | +-- Memory (remember/recall)
36-
| Context Builder
37-
| +-- Soul Files (AGENTS.md, SOUL.md, ...)
38-
| +-- Working Memory (per-user scratchpad)
39-
| +-- Observations (compressed history)
40-
| +-- RAG Injection (vector search)
41-
| +-- Tool + Skill definitions
42-
|
43-
Timeline DB (SQLite)
32+
<div style="overflow:auto;border:1px solid #d4dcec;border-radius:10px;padding:10px;background:#fbfdff;">
33+
<svg viewBox="0 0 1120 340" role="img" aria-label="KafClaw detailed architecture overview diagram" style="min-width:900px;max-width:100%;height:auto;">
34+
<defs>
35+
<marker id="arrowB" markerWidth="9" markerHeight="7" refX="8" refY="3.5" orient="auto">
36+
<polygon points="0 0, 9 3.5, 0 7" fill="#2e5cab"></polygon>
37+
</marker>
38+
</defs>
39+
<rect x="400" y="28" width="320" height="70" rx="10" fill="#eaf1ff" stroke="#9bb5e6"></rect>
40+
<text x="560" y="56" text-anchor="middle" font-size="17" font-weight="700" fill="#1f3f84">Message Bus</text>
41+
<text x="560" y="76" text-anchor="middle" font-size="12" fill="#355d9c">decouples channels from agent loop</text>
42+
43+
<rect x="400" y="120" width="320" height="72" rx="10" fill="#ffffff" stroke="#d4dcec"></rect>
44+
<text x="560" y="148" text-anchor="middle" font-size="16" font-weight="700" fill="#24344d">Agent Loop + Context Builder</text>
45+
<text x="560" y="168" text-anchor="middle" font-size="12" fill="#4e5c73">soul files • memory • skills • tool calls</text>
46+
47+
<rect x="90" y="44" width="230" height="148" rx="10" fill="#ffffff" stroke="#d4dcec"></rect>
48+
<text x="205" y="68" text-anchor="middle" font-size="14" font-weight="700" fill="#24344d">Ingress Channels</text>
49+
<text x="205" y="92" text-anchor="middle" font-size="12" fill="#4e5c73">WhatsApp / CLI / Web</text>
50+
<text x="205" y="112" text-anchor="middle" font-size="12" fill="#4e5c73">Slack / Teams bridge</text>
51+
<text x="205" y="132" text-anchor="middle" font-size="12" fill="#4e5c73">Scheduler jobs</text>
52+
<text x="205" y="152" text-anchor="middle" font-size="12" fill="#4e5c73">Group traces/tasks</text>
53+
54+
<rect x="800" y="44" width="230" height="148" rx="10" fill="#ffffff" stroke="#d4dcec"></rect>
55+
<text x="915" y="68" text-anchor="middle" font-size="14" font-weight="700" fill="#24344d">Execution Plane</text>
56+
<text x="915" y="92" text-anchor="middle" font-size="12" fill="#4e5c73">Provider (LLM)</text>
57+
<text x="915" y="112" text-anchor="middle" font-size="12" fill="#4e5c73">Tools (fs/shell/web)</text>
58+
<text x="915" y="132" text-anchor="middle" font-size="12" fill="#4e5c73">Memory (RAG/observer)</text>
59+
<text x="915" y="152" text-anchor="middle" font-size="12" fill="#4e5c73">Group + Orchestrator</text>
60+
61+
<rect x="320" y="226" width="480" height="82" rx="10" fill="#f4f8ff" stroke="#c8d6f1"></rect>
62+
<text x="560" y="249" text-anchor="middle" font-size="14" font-weight="700" fill="#214483">Timeline DB (SQLite)</text>
63+
<text x="560" y="269" text-anchor="middle" font-size="12" fill="#4e5c73">events • traces • tasks • approvals • memory chunks</text>
64+
<text x="560" y="287" text-anchor="middle" font-size="12" fill="#4e5c73">settings • roster • topic metadata</text>
65+
66+
<line x1="320" y1="92" x2="400" y2="62" stroke="#2e5cab" stroke-width="2.2" marker-end="url(#arrowB)"></line>
67+
<line x1="720" y1="62" x2="800" y2="92" stroke="#2e5cab" stroke-width="2.2" marker-end="url(#arrowB)"></line>
68+
<line x1="560" y1="98" x2="560" y2="120" stroke="#2e5cab" stroke-width="2.2" marker-end="url(#arrowB)"></line>
69+
<line x1="560" y1="192" x2="560" y2="226" stroke="#2e5cab" stroke-width="2.2" marker-end="url(#arrowB)"></line>
70+
</svg>
71+
</div>
72+
73+
Mermaid source (GitHub code view renders this; GitHub Pages may require a Mermaid JS include depending on your theme setup):
74+
75+
```mermaid
76+
flowchart LR
77+
IN["Ingress Channels<br/>WhatsApp / CLI / Web / Slack / Teams / Scheduler"] --> MB["Message Bus"]
78+
MB --> AG["Agent Loop + Context Builder"]
79+
AG --> EX["Execution Plane<br/>Provider + Tools + Memory + Group"]
80+
AG --> DB["Timeline DB (SQLite)<br/>events + traces + tasks + approvals + memory"]
4481
```
4582

4683
### Design Principles

‎docs/v2/architecture.md‎

Lines changed: 52 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# KafClaw Architecture — Overview
22

3+
{% include topnav.html %}
4+
35
A quick reference for the KafClaw system architecture. For the comprehensive deep-dive, see [architecture-detailed.md](./architecture-detailed.md).
46

57
> See also: [FR-009 System Architecture](../requirements/FR-009-system-architecture.md), [FR-013 Package Design](../requirements/FR-013-package-design.md)
@@ -52,25 +54,56 @@ LLM abstraction supporting OpenAI-compatible APIs:
5254

5355
## System Diagram
5456

55-
```
56-
WhatsApp ---+
57-
CLI --------+ +-- Filesystem Tools
58-
Web UI -----+-- Message Bus -- Agent Loop -- LLM +-- Shell Execution
59-
Scheduler --+ | | +-- Web Search
60-
| | +-- Memory (remember/recall)
61-
| Context Builder
62-
| +-- Soul Files (AGENTS.md, SOUL.md, ...)
63-
| +-- Working Memory (per-user scratchpad)
64-
| +-- Observations (compressed history)
65-
| +-- RAG Injection (vector search)
66-
| +-- Tool + Skill definitions
67-
|
68-
Timeline DB (SQLite)
69-
+-- Event log
70-
+-- Memory chunks (embeddings)
71-
+-- Settings, tasks, approvals
72-
+-- Group roster, skill channels
73-
+-- Orchestrator hierarchy
57+
<div style="overflow:auto;border:1px solid #d4dcec;border-radius:10px;padding:10px;background:#fbfdff;">
58+
<svg viewBox="0 0 1120 360" role="img" aria-label="KafClaw system diagram" style="min-width:900px;max-width:100%;height:auto;">
59+
<defs>
60+
<marker id="arrowA" markerWidth="9" markerHeight="7" refX="8" refY="3.5" orient="auto">
61+
<polygon points="0 0, 9 3.5, 0 7" fill="#2e5cab"></polygon>
62+
</marker>
63+
</defs>
64+
<rect x="410" y="40" width="300" height="64" rx="10" fill="#eaf1ff" stroke="#9bb5e6"></rect>
65+
<text x="560" y="65" text-anchor="middle" font-size="18" font-weight="700" fill="#1f3f84">Message Bus</text>
66+
<text x="560" y="84" text-anchor="middle" font-size="12" fill="#355d9c">Inbound / Outbound decoupling</text>
67+
68+
<rect x="410" y="130" width="300" height="70" rx="10" fill="#ffffff" stroke="#d4dcec"></rect>
69+
<text x="560" y="157" text-anchor="middle" font-size="16" font-weight="700" fill="#24344d">Agent Loop</text>
70+
<text x="560" y="176" text-anchor="middle" font-size="12" fill="#4e5c73">LLM orchestration + tool loop</text>
71+
72+
<rect x="120" y="48" width="190" height="140" rx="10" fill="#ffffff" stroke="#d4dcec"></rect>
73+
<text x="215" y="72" text-anchor="middle" font-size="14" font-weight="700" fill="#24344d">Channels</text>
74+
<text x="215" y="96" text-anchor="middle" font-size="12" fill="#4e5c73">WhatsApp</text>
75+
<text x="215" y="116" text-anchor="middle" font-size="12" fill="#4e5c73">CLI / Web UI</text>
76+
<text x="215" y="136" text-anchor="middle" font-size="12" fill="#4e5c73">Slack / Teams</text>
77+
<text x="215" y="156" text-anchor="middle" font-size="12" fill="#4e5c73">Scheduler</text>
78+
79+
<rect x="790" y="48" width="220" height="152" rx="10" fill="#ffffff" stroke="#d4dcec"></rect>
80+
<text x="900" y="72" text-anchor="middle" font-size="14" font-weight="700" fill="#24344d">Tools + Memory</text>
81+
<text x="900" y="96" text-anchor="middle" font-size="12" fill="#4e5c73">Filesystem / Shell</text>
82+
<text x="900" y="116" text-anchor="middle" font-size="12" fill="#4e5c73">Web / Recall</text>
83+
<text x="900" y="136" text-anchor="middle" font-size="12" fill="#4e5c73">Working Memory</text>
84+
<text x="900" y="156" text-anchor="middle" font-size="12" fill="#4e5c73">Observer + RAG</text>
85+
<text x="900" y="176" text-anchor="middle" font-size="12" fill="#4e5c73">Group / Skills</text>
86+
87+
<rect x="345" y="235" width="430" height="88" rx="10" fill="#f4f8ff" stroke="#c8d6f1"></rect>
88+
<text x="560" y="258" text-anchor="middle" font-size="14" font-weight="700" fill="#214483">Timeline DB (SQLite)</text>
89+
<text x="560" y="278" text-anchor="middle" font-size="12" fill="#4e5c73">Events • Tasks • Approvals • Memory chunks</text>
90+
<text x="560" y="297" text-anchor="middle" font-size="12" fill="#4e5c73">Group roster • Topics • Settings</text>
91+
92+
<line x1="310" y1="98" x2="410" y2="72" stroke="#2e5cab" stroke-width="2.2" marker-end="url(#arrowA)"></line>
93+
<line x1="710" y1="72" x2="790" y2="98" stroke="#2e5cab" stroke-width="2.2" marker-end="url(#arrowA)"></line>
94+
<line x1="560" y1="104" x2="560" y2="130" stroke="#2e5cab" stroke-width="2.2" marker-end="url(#arrowA)"></line>
95+
<line x1="560" y1="200" x2="560" y2="235" stroke="#2e5cab" stroke-width="2.2" marker-end="url(#arrowA)"></line>
96+
</svg>
97+
</div>
98+
99+
Mermaid source (GitHub code view renders this; GitHub Pages may require a Mermaid JS include depending on your theme setup):
100+
101+
```mermaid
102+
flowchart LR
103+
CH["Channels<br/>WhatsApp / CLI / Web / Slack / Teams / Scheduler"] --> MB["Message Bus"]
104+
MB --> AL["Agent Loop"]
105+
AL --> TM["Tools + Memory<br/>Filesystem / Shell / Web / RAG"]
106+
AL --> DB["Timeline DB (SQLite)<br/>events + tasks + approvals + memory"]
74107
```
75108

76109
## Design Principles

‎docs/v2/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# KafClaw Documentation (v2)
22

3+
{% include topnav.html %}
4+
35
Primary v2 reference set for KafClaw.
46

57
## Quick Links

0 commit comments

Comments
 (0)