Skip to content

Commit aa5f19b

Browse files
varshith-Gitvarshith-Git
committed
docs: Enhance architecture diagram with detailed multi-layer visualization
- Added comprehensive layer breakdown (Interface, Durability, Kernel) - Showed WAL writer, reader, snapshot manager components - Illustrated crash recovery data flow - Included key properties and guarantees - Much more professional and informative
1 parent 80a96e7 commit aa5f19b

File tree

1 file changed

+113
-44
lines changed

1 file changed

+113
-44
lines changed

‎README.md‎

Lines changed: 113 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -160,53 +160,122 @@ results = client.search([0.15, 0.25, ...], k=5)
160160

161161
## 📐 Architecture
162162

163+
Valori uses a **strict layered architecture** ensuring the deterministic kernel remains pure while enabling production durability and multiple deployment modes.
164+
163165
```
164-
┌─────────────────────────────────────────────────────────┐
165-
│ User Applications │
166-
│ (Python Scripts, Rust Apps, Embedded Devices) │
167-
└───────────────────┬─────────────────────────────────────┘
168-
│
169-
┌───────────┴───────────┐
170-
│ │
171-
▼ ▼
172-
┌──────────────┐ ┌──────────────────┐
173-
│ Python FFI │ │ HTTP Server │
174-
│ (pyo3) │ │ (axum/tokio) │
175-
│ Embedded │ │ Remote │
176-
└──────┬───────┘ └────────┬─────────┘
177-
│ │
178-
│ ┌──────────────────┤
179-
│ │ WAL Writer │ ← fsync after each command
180-
│ │ (durability) │
181-
│ └──────────────────┤
182-
│ │
183-
└───────────┬───────────┘
184-
▼
185-
┌────────────────────────┐
186-
│ Valori Kernel │
187-
│ (no_std, pure Rust) │
188-
│ │
189-
│ • Fixed-Point Math │
190-
│ • Vector Storage │
191-
│ • Knowledge Graph │
192-
│ • Deterministic Ops │
193-
└────────────────────────┘
194-
│
195-
┌──────────┴──────────┐
196-
▼ ▼
197-
┌─────────┐ ┌──────────┐
198-
│Snapshot │ │ WAL │
199-
│ (state) │ │ (commands)│
200-
└─────────┘ └──────────┘
201-
│ │
202-
└──────────┬──────────┘
203-
▼
204-
Crash Recovery
205-
Snapshot + WAL Replay
206-
= Bit-Identical State ✅
166+
╔═══════════════════════════════════════════════════════════════════════════════════╗
167+
║ CLIENT APPLICATIONS ║
168+
║ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ║
169+
║ │ Python │ │ Rust App │ │ HTTP │ │ Embedded │ ║
170+
║ │ Scripts │ │ Binary │ │ Clients │ │ Devices │ ║
171+
║ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ ║
172+
╚═════════╪══════════════════╪══════════════════════╪══════════════════╪═══════════╝
173+
│ │ │ │
174+
▼ ▼ ▼ ▼
175+
┌─────────────────────────────────────────────────────────────────────────────────┐
176+
│ INTERFACE LAYER (std) │
177+
│ ┌──────────────────────┐ ┌────────────────────────────┐ │
178+
│ │ Python FFI (pyo3) │ │ HTTP Server (axum) │ │
179+
│ │ ┌────────────────┐ │ │ ┌──────────────────────┐ │ │
180+
│ │ │ EmbeddedKernel │ │ │ │ REST API Handlers │ │ │
181+
│ │ │ (in-process) │ │ │ │ /v1/memory/* │ │ │
182+
│ │ └────────┬───────┘ │ │ └──────────┬───────────┘ │ │
183+
│ └───────────┼──────────┘ └─────────────┼──────────────┘ │
184+
│ │ │ │
185+
│ └────────────────┬───────────────────────┘ │
186+
└───────────────────────────────┼──────────────────────────────────────────────────┘
187+
│
188+
▼
189+
┌─────────────────────────────────────────────────────────────────────────────────┐
190+
│ DURABILITY LAYER (std) │
191+
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
192+
│ │ Engine Coordinator │ │
193+
│ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────────────────┐ │ │
194+
│ │ │ WAL Writer │ │ WAL Reader │ │ Snapshot Manager │ │ │
195+
│ │ │ │ │ │ │ │ │ │
196+
│ │ │ • Serialize │ │ • Deserialize │ │ • encode_state() │ │ │
197+
│ │ │ • fsync() │ │ • Iterator │ │ • decode_state() │ │ │
198+
│ │ │ • Length Frame │ │ • replay_wal() │ │ • BLAKE3 hash │ │ │
199+
│ │ └───────┬────────┘ └────────┬───────┘ └────────┬───────────────────┘ │ │
200+
│ └──────────┼──────────────────────┼──────────────────┼──────────────────────┘ │
201+
│ │ │ │ │
202+
│ ▼ ▼ ▼ │
203+
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
204+
│ │ Persistence │ │
205+
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
206+
│ │ │ commands.wal │ │state.snapshot│ │ Metadata │ │ │
207+
│ │ │ │ │ │ │ │ │ │
208+
│ │ │ [v:u8][l:u32]│──┐ │ [Header] │ │ Indexes, │ │ │
209+
│ │ │ [cmd_bytes] │ │ │ [Kernel] │ │ Configs │ │ │
210+
│ │ │ ... │ │ │ [Meta] │ │ │ │ │
211+
│ │ └──────────────┘ │ │ [Index] │ └──────────────┘ │ │
212+
│ │ │ └──────────────┘ │ │
213+
│ │ │ ▲ │ │
214+
│ │ │ │ │ │
215+
│ │ └────Replay──────┘ │ │
216+
│ │ (Crash Recovery) │ │
217+
│ └──────────────────────────────────────────────────────────────────────────┘ │
218+
└────────────────────────────────────┬────────────────────────────────────────────┘
219+
│
220+
▼
221+
┌─────────────────────────────────────────────────────────────────────────────────┐
222+
│ VALORI KERNEL (no_std, pure Rust) │
223+
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
224+
│ │ KernelState<R,D,N,E> │ │
225+
│ │ ┌────────────────────────────────────────────────────────────────────┐ │ │
226+
│ │ │ Deterministic State Machine │ │ │
227+
│ │ │ │ │ │
228+
│ │ │ • apply(Command) → Result<(), Error> │ │ │
229+
│ │ │ • All operations use Fixed-Point arithmetic (Q16.16) │ │ │
230+
│ │ │ • No floating point, no randomness, no timestamps │ │ │
231+
│ │ │ • Bit-identical across x86, ARM, WASM, RISC-V │ │ │
232+
│ │ └────────────────────────────────────────────────────────────────────┘ │ │
233+
│ │ │ │
234+
│ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────────────────┐ │ │
235+
│ │ │ Vector Storage │ │ Knowledge Graph│ │ Fixed-Point Math │ │ │
236+
│ │ │ │ │ │ │ │ │ │
237+
│ │ │ RecordPool[R] │ │ NodePool[N] │ │ FxpScalar (i32) │ │ │
238+
│ │ │ FxpVector<D> │ │ EdgePool[E] │ │ FxpVector<D> │ │ │
239+
│ │ │ │ │ AdjacencyList │ │ │ │ │
240+
│ │ │ • insert() │ │ │ │ • add, sub, mul, div │ │ │
241+
│ │ │ • delete() │ │ • create_node()│ │ • l2_distance() │ │ │
242+
│ │ │ • get() │ │ • create_edge()│ │ • normalize() │ │ │
243+
│ │ └────────────────┘ └────────────────┘ └────────────────────────────┘ │ │
244+
│ │ │ │
245+
│ │ ┌────────────────────────────────────────────────────────────────────┐ │ │
246+
│ │ │ Cryptographic Verification │ │ │
247+
│ │ │ • kernel_state_hash() → [u8; 32] (BLAKE3) │ │ │
248+
│ │ │ • Deterministic snapshot encoding │ │ │
249+
│ │ └────────────────────────────────────────────────────────────────────┘ │ │
250+
│ └──────────────────────────────────────────────────────────────────────────┘ │
251+
└─────────────────────────────────────────────────────────────────────────────────┘
252+
253+
DATA FLOW: CRASH RECOVERY
254+
255+
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
256+
│ Snapshot │────────▶│ WAL Reader │────────▶│ Kernel │
257+
│ (State S₀) │ Load │ (Commands) │ Replay │ (State Sₙ) │
258+
└──────────────┘ └──────────────┘ └──────────────┘
259+
│ │ │
260+
│ │ │
261+
└─────────────────────────┴────────────────────────┘
262+
│
263+
verify_hash()
264+
│
265+
▼
266+
✅ Bit-Identical State
267+
(Guaranteed Determinism)
207268
```
208269

209-
See: [Architecture Details](architecture.md)
270+
**Key Properties**:
271+
272+
- **Separation of Concerns**: Core kernel stays pure (no I/O), durability wrapped outside
273+
- **Deterministic Core**: Fixed-point math ensures bit-identical results across architectures
274+
- **Crash Recovery**: Snapshot + WAL replay = mathematically proven state restoration
275+
- **Multi-Deployment**: Same kernel runs embedded (no_std) or as HTTP service (std)
276+
- **Verifiable**: Cryptographic hashes prove state integrity
277+
278+
See [Architecture Details](architecture.md) for deep dive.
210279

211280
---
212281

0 commit comments

Comments
 (0)