How PugDB Works
PugDB is built on a modular, layered architecture that separates concerns and allows you to choose the right components for your specific needs. The system follows the principle of composition over inheritance with a minimal core and powerful extensions.
Architecture Overview
PugDB's architecture consists of five distinct layers, each with specific responsibilities:
CLI Tools, Shell, Migration
S3 Storage, Tiering, Edge
Server, Client, Clustering
Storage Engines, QL, Monitoring
Core Abstractions, Memory Storage
Each layer depends only on the layers below it, creating a clean dependency hierarchy. This strict layering ensures:
- Clear Boundaries: Each layer has well-defined responsibilities
- Testability: Layers can be tested independently
- Flexibility: Components can be swapped or extended without affecting other layers
- Maintainability: Changes are isolated to specific layers
Foundation Layer
The foundation provides the core abstractions and basic memory storage.
Core Components
- f4kvs-core: Core abstractions, traits, and configuration (1,199 tests, 90%+ coverage)
- f4kvs-ffi: Foreign function interface bindings for multi-language support (C, C++, Python, Go, Node.js, etc.)
Status: ✅ Beta - Well Tested - 1,199 tests, 90%+ coverage
Extensions Layer
The extensions layer adds advanced capabilities on top of the foundation.
Core Components
- f4kvs-storage: Advanced persistent storage engines (813 tests, 80%+ coverage)
- f4kvs-ttl: Time-to-live management
- f4kvs-ql: Query language interface (856+ tests, 62% project-wide coverage) - Beta (Approaching Production)
- f4kvs-observability: Monitoring and observability (Beta, 50-100% coverage)
Storage Status: ✅ Beta - Well Tested - 813 tests, 80%+ coverage
Query Language Status: 🟡 Beta (Approaching Production) - 856+ tests, 62% project-wide coverage
Distributed Layer
The distributed layer provides networking, clustering, and multi-node capabilities.
Core Components
- f4kvs-network: Network protocol implementation (109 tests, 90%+ coverage)
- f4kvs-server: Server implementation
- f4kvs-client: Client libraries
- f4kvs-clustering: Clustering and consensus (588 tests, 30-70% coverage)
Status: ✅ Beta - Well Tested - Network (109 tests, 90%+ coverage), Clustering (588 tests, 30-70% coverage)
How Operations Work
Key-Value Operations
When you perform a basic operation like put or get:
- Request: Client sends operation request to server
- Routing: Server routes request to appropriate storage engine
- Storage Engine: Selected engine performs the operation
- Compression: Optional compression applied (if configured)
- Response: Result returned to client
Batch Operations
Batch operations are optimized for efficiency with connection reuse, parallel processing, and atomic batch commits.
Architecture Principles
Separation of Concerns
Each layer has specific, non-overlapping responsibilities.
Layered Dependencies
Strict dependency rules ensure clean architecture with no circular dependencies.
Composition over Inheritance
Complex features built by composing simple ones with pluggable extensions.
Performance Optimizations
- Async I/O: Tokio for non-blocking operations and excellent concurrency
- Memory Management: Optimized memory pools, zero-copy where possible
- Batch Processing: Connection reuse, parallel processing, reduced network overhead