This document details the end-to-end system design, component boundaries, package structure, and lifecycle flows of PrefixOS.
PrefixOS Core Engine
├── API Layer (internal/api/)
│ ├── REST Gateway (Gin/Net/HTTP)
│ ├── gRPC Server (proto/v1/prefixos.proto)
│ ├── Admin Operations Server (/admin/*)
│ └── SSE Streaming Server
│
├── Core Control Plane (internal/)
│ ├── interfaces/ <-- Pure Go Interfaces
│ ├── memory/ <-- Slab Allocator, NUMA, Defrag, Quotas
│ ├── radix/ <-- 64-Way Sharded RCU Tree Engine
│ ├── eviction/ <-- Adaptive, ARC, TinyLFU, LFU, LRU
│ ├── persistence/ <-- WAL Engine, Snapshots, CRC32 Checksums
│ ├── replication/ <-- Raft Consensus, Consistent Hash Ring
│ ├── security/ <-- TLS/mTLS, API Keys, Rate Limiter
│ ├── metrics/ <-- Prometheus, OpenTelemetry, pprof
│ ├── tokenizer/ <-- Tiktoken / BPE Wrapper
│ └── adapters/ <-- vLLM, SGLang, llama.cpp Adapters
│
└── Client Libraries (pkg/sdk/)
├── go/ <-- Native Go SDK Client
├── python/ <-- Python Client SDK
└── rest/ <-- HTTP REST Client
cmd/serverinitializesinternal/config, bindsinternal/memorySlab Allocator, and instantiates the 64-wayinternal/radixTree.internal/radixregisters leaf nodes withinternal/evictionpolicy handlers upon node creation.internal/apiendpoints delegate request validation tointernal/securitybefore invokinginternal/radixmethods.- Write operations (
Insert) publish mutations asynchronously tointernal/persistence(WAL) andinternal/replication(Raft Log).
- Node Failure: If a Raft follower node crashes, the cluster continues serving reads and writes without interruption.
- Leader Failure: Raft triggers leader election within
< 1.5 seconds. Clients automatically reconnect to the newly elected leader via the gRPC client load balancer. - Disk Corruption: CRC32 checksum validation detects corrupted WAL entries during startup recovery, reverting safely to the latest valid snapshot.